@intlayer/docs 5.5.8

package/pt/vs_code_extension.md

@@ -0,0 +1,139 @@
+# Extensão oficial do VS Code
+
+## Visão Geral
+
+**Intlayer** é a extensão oficial do Visual Studio Code para **Intlayer**, projetada para melhorar a experiência do desenvolvedor ao trabalhar com conteúdo localizado em projetos **React, Next.js e JavaScript**.
+
+Com esta extensão, os desenvolvedores podem **navegar rapidamente** para seus dicionários de conteúdo, gerenciar arquivos de localização e otimizar seu fluxo de trabalho com comandos de automação poderosos.
+
+Link da extensão: [https://marketplace.visualstudio.com/items?itemName=Intlayer.intlayer-vs-code-extension](https://marketplace.visualstudio.com/items?itemName=Intlayer.intlayer-vs-code-extension)
+
+![Intlayer VS Code Extension](https://github.com/aymericzip/intlayer/blob/main/docs/assets/vs_code_extension_demo.gif)
+
+## Funcionalidades
+
+### Navegação Instantânea
+
+**Suporte a Ir para Definição** – Use `Cmd+Click` (Mac) ou `Ctrl+Click` (Windows/Linux) em uma chave `useIntlayer` para abrir instantaneamente o arquivo de conteúdo correspondente.  
+**Integração Sem Esforço** – Funciona perfeitamente com projetos **react-intlayer** e **next-intlayer**.  
+**Suporte Multilíngue** – Suporta conteúdo localizado em diferentes idiomas.  
+**Integração com VS Code** – Integra-se suavemente com a navegação e o painel de comandos do VS Code.
+
+### Comandos de Gerenciamento de Dicionários
+
+Gerencie seus dicionários de conteúdo diretamente do VS Code:
+
+- **Construir Dicionários** (`extension.buildDictionaries`) – Gere arquivos de conteúdo com base na estrutura do seu projeto.
+- **Enviar Dicionários** (`extension.pushDictionaries`) – Faça upload do conteúdo mais recente do dicionário para o seu repositório.
+- **Baixar Dicionários** (`extension.pullDictionaries`) – Sincronize o conteúdo mais recente do dicionário do seu repositório para o seu ambiente local.
+
+### Gerador de Declaração de Conteúdo
+
+Gere facilmente arquivos de dicionário estruturados em diferentes formatos:
+
+- **TypeScript (`.ts`)** – `extension.createDictionaryFile.ts`
+- **ES Module (`.esm`)** – `extension.createDictionaryFile.esm`
+- **CommonJS (`.cjs`)** – `extension.createDictionaryFile.cjs`
+- **JSON (`.json`)** – `extension.createDictionaryFile.json`
+
+## Instalação
+
+Você pode instalar o **Intlayer** diretamente do Marketplace do VS Code:
+
+1. Abra o **VS Code**.
+2. Vá para o **Marketplace de Extensões**.
+3. Procure por **"Intlayer"**.
+4. Clique em **Instalar**.
+
+Alternativamente, instale via linha de comando:
+
+```sh
+code --install-extension intlayer
+```
+
+## Uso
+
+### Navegação Rápida
+
+1. Abra um projeto usando **react-intlayer**.
+2. Localize uma chamada para `useIntlayer()`, como:
+
+   ```tsx
+   const content = useIntlayer("app");
+   ```
+
+3. **Command-click** (`⌘+Click` no macOS) ou **Ctrl+Click** (no Windows/Linux) na chave (por exemplo, `"app"`).
+4. O VS Code abrirá automaticamente o arquivo de dicionário correspondente, por exemplo, `src/app.content.ts`.
+
+### Gerenciando Dicionários de Conteúdo
+
+#### Construindo Dicionários
+
+Gere todos os arquivos de conteúdo do dicionário com:
+
+```sh
+Cmd + Shift + P (macOS) / Ctrl + Shift + P (Windows/Linux)
+```
+
+Procure por **Construir Dicionários** e execute o comando.
+
+#### Enviando Dicionários
+
+Faça upload do conteúdo mais recente do dicionário:
+
+1. Abra o **Painel de Comandos**.
+2. Procure por **Enviar Dicionários**.
+3. Selecione os dicionários para enviar e confirme.
+
+#### Baixando Dicionários
+
+Sincronize o conteúdo mais recente do dicionário:
+
+1. Abra o **Painel de Comandos**.
+2. Procure por **Baixar Dicionários**.
+3. Escolha os dicionários para baixar.
+
+### Personalizando Caminhos de Arquivos de Dicionário
+
+Por padrão, a extensão segue a estrutura padrão do projeto **Intlayer**. No entanto, você pode configurar caminhos personalizados:
+
+1. Abra **Configurações (`Cmd + ,` no macOS / `Ctrl + ,` no Windows/Linux)`**.
+2. Procure por `Intlayer`.
+3. Ajuste a configuração do caminho do arquivo de conteúdo.
+
+## Desenvolvimento e Contribuição
+
+Quer contribuir? Agradecemos contribuições da comunidade!
+
+URL do Repositório: https://github.com/aymericzip/intlayer-vs-code-extension
+
+### Começando
+
+Clone o repositório e instale as dependências:
+
+```sh
+git clone https://github.com/aymericzip/intlayer-vs-code-extension.git
+cd intlayer-vs-code-extension
+npm install
+```
+
+> Use o gerenciador de pacotes `npm` para compatibilidade com o pacote `vsce` para construir e publicar a extensão.
+
+### Executar no Modo de Desenvolvimento
+
+1. Abra o projeto no **VS Code**.
+2. Pressione `F5` para iniciar uma nova janela **Extension Development Host**.
+
+### Enviar um Pull Request
+
+Se você melhorar a extensão, envie um PR no [GitHub](https://github.com/aymericzip/intlayer-vs-code-extension).
+
+## Feedback e Problemas
+
+Encontrou um bug ou tem uma solicitação de recurso? Abra um problema no nosso **repositório do GitHub**:
+
+[Problemas no GitHub](https://github.com/aymericzip/intlayer-vs-code-extension/issues)
+
+## Licença
+
+O Intlayer é lançado sob a **Licença MIT**.

package/ru/CI_CD.md

@@ -0,0 +1,149 @@
+# Автоматическая генерация переводов в CI/CD пайплайне
+
+Intlayer позволяет автоматически генерировать переводы для ваших файлов декларации контента. Существует несколько способов достижения этого в зависимости от вашего рабочего процесса.
+
+## Использование CMS
+
+С помощью Intlayer вы можете использовать рабочий процесс, в котором локально объявляется только одна локаль, а все переводы управляются удаленно через CMS. Это позволяет полностью отделить контент и переводы от кодовой базы, предоставляя больше гибкости редакторам контента и обеспечивая горячую перезагрузку контента (нет необходимости пересобирать приложение для применения изменений).
+
+### Пример конфигурации
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.SPANISH, Locales.FRENCH],
+    requiredLocales: [Locales.ENGLISH], // Необязательные локали будут управляться удаленно
+    defaultLocale: Locales.ENGLISH,
+  },
+  editor: {
+    dictionaryPriorityStrategy: "distant_first", // Удаленный контент имеет приоритет
+
+    applicationURL: process.env.APPLICATION_URL, // URL приложения, используемый CMS
+
+    clientId: process.env.INTLAYER_CLIENT_ID, // Учетные данные CMS
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+  },
+  ai: {
+    applicationContext: "Это тестовое приложение", // Помогает обеспечить согласованность генерации переводов
+  },
+};
+
+export default config;
+```
+
+Чтобы узнать больше о CMS, обратитесь к [официальной документации](https://github.com/aymericzip/intlayer/blob/main/docs/ru/intlayer_CMS.md).
+
+## Использование Husky
+
+Вы можете интегрировать генерацию переводов в ваш локальный Git рабочий процесс с помощью [Husky](https://typicode.github.io/husky/).
+
+### Пример конфигурации
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.SPANISH, Locales.FRENCH],
+    requiredLocales: [Locales.ENGLISH], // Необязательные локали обрабатываются удаленно
+    defaultLocale: Locales.ENGLISH,
+  },
+  editor: {
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+  },
+  ai: {
+    provider: "openai",
+    apiKey: process.env.OPENAI_API_KEY, // Используйте ваш собственный API ключ
+
+    applicationContext: "Это тестовое приложение", // Помогает обеспечить согласованность генерации переводов
+  },
+};
+
+export default config;
+```
+
+```bash fileName=".husky/pre-push"
+npx intlayer build                          # Убедитесь, что словари актуальны
+npx intlayer fill --unpushed --mode fill    # Заполняет только отсутствующий контент, не обновляет существующий
+```
+
+> Для получения дополнительной информации о командах Intlayer CLI и их использовании обратитесь к [документации CLI](https://github.com/aymericzip/intlayer/blob/main/docs/ru/intlayer_cli.md).
+
+> Если у вас в репозитории несколько приложений, использующих отдельные экземпляры Intlayer, вы можете использовать аргумент `--base-dir`, например:
+
+    ```bash fileName=".husky/pre-push"
+    # Приложение 1
+    npx intlayer build --base-dir ./app1
+    npx intlayer fill --base-dir ./app1 --unpushed --mode fill
+
+    # Приложение 2
+    npx intlayer build --base-dir ./app2
+    npx intlayer fill --base-dir ./app2 --unpushed --mode fill
+    ```
+
+## Использование GitHub Actions
+
+Intlayer предоставляет CLI-команду для автозаполнения и проверки содержимого словарей. Это можно интегрировать в ваш CI/CD рабочий процесс с использованием GitHub Actions.
+
+```yaml fileName=".github/workflows/intlayer-translate.yml"
+name: Intlayer Auto-Fill
+on:
+  push:
+    branches: [ main ]
+    paths:
+      - 'src/**'
+  pull_request:
+    branches: [ main ]
+    paths:
+      - 'src/**'
+  workflow_dispatch: {}
+
+concurrency:
+  group: 'autofill-${{ github.ref }}'
+  cancel-in-progress: true
+
+jobs:
+  autofill:
+    runs-on: ubuntu-latest
+    env:
+      INTLAYER_CLIENT_ID: ${{ secrets.INTLAYER_CLIENT_ID }}
+      INTLAYER_CLIENT_SECRET: ${{ secrets.INTLAYER_CLIENT_SECRET }}
+      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+
+    steps:
+      - name: ⬇️ Checkout repository
+        uses: actions/checkout@v3
+        with:
+          persist-credentials: true
+
+      - name: 🟢 Set up Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 20
+
+      - name: 📦 Install dependencies
+        run: npm ci
+
+      - name: ⚙️ Build Intlayer project
+        run: npx intlayer build
+
+      - name: 🤖 Auto-fill missing translations
+        run: npx intlayer fill --git-diff --mode fill
+
+      - name: 📤 Create or update translation PR
+        uses: peter-evans/create-pull-request@v4
+        with:
+          commit-message: chore: auto-fill missing translations [skip ci]
+          branch: auto-translations
+          title: chore: update missing translations
+          labels: translation, automated
+```
+
+> Как и в случае с Husky, в случае монорепозитория вы можете использовать аргумент `--base-dir` для последовательной обработки каждого приложения.
+
+> По умолчанию аргумент `--git-diff` фильтрует словари, которые включают изменения от базовой ветки (по умолчанию `origin/main`) до текущей ветки (по умолчанию: `HEAD`).
+
+> Для получения дополнительной информации о командах Intlayer CLI и их использовании обратитесь к [документации CLI](https://github.com/aymericzip/intlayer/blob/main/docs/ru/intlayer_cli.md).

package/ru/autoFill.md

@@ -0,0 +1,157 @@
+# Автоматически заполняемые файлы объявления контента
+
+**Автоматически заполняемые файлы объявления контента** - это способ ускорить ваш рабочий процесс разработки.
+
+Механизм автозаполнения работает через отношение _master-slave_ между файлами объявления контента. Когда основной (master) файл обновляется, Intlayer автоматически применяет эти изменения к производным (автоматически заполненным) файлам объявления.
+
+```ts fileName="src/components/example/example.content.ts"
+import { Locales, type Dictionary } from "intlayer";
+
+const exampleContent = {
+  key: "example",
+  locale: Locales.ENGLISH,
+  autoFill: "./example.content.json",
+  content: {
+    contentExample: "This is an example of content",
+  },
+} satisfies Dictionary;
+
+export default exampleContent;
+```
+
+Вот [файл объявления контента для каждого языка](https://github.com/aymericzip/intlayer/blob/main/docs/ru/per_locale_file.md), использующий инструкцию `autoFill`.
+
+Затем, когда вы выполняете следующую команду:
+
+```bash
+npx intlayer fill --file 'src/components/example/example.content.ts'
+```
+
+Intlayer автоматически сгенерирует производный файл объявления в `src/components/example/example.content.json`, заполнив все языки, которые еще не объявлены в основном файле.
+
+```json5 fileName="src/components/example/example.content.json"
+{
+  "key": "example",
+  "content": {
+    "contentExample": {
+      "nodeType": "translation",
+      "translation": {
+        "fr": "Ceci est un exemple de contenu",
+        "es": "Este es un ejemplo de contenido",
+      },
+    },
+  },
+}
+```
+
+Впоследствии оба файла объявления будут объединены в один словарь, доступный через стандартный хук `useIntlayer("example")` (react) / composable (vue).
+
+## Формат автоматически заполняемых файлов
+
+Рекомендуемый формат для автоматически заполняемых файлов объявления - **JSON**, что помогает избежать ограничений форматирования. Однако Intlayer также поддерживает форматы `.ts`, `.js`, `.mjs`, `.cjs` и другие.
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  autoFill: "./example.filled.content.ts",
+  content: {
+    // Ваш контент
+  },
+};
+```
+
+Это сгенерирует файл в:
+
+```
+src/components/example/example.filled.content.ts
+```
+
+> Генерация файлов `.js`, `.ts` и подобных работает следующим образом:
+
+> - Если файл уже существует, Intlayer проанализирует его с помощью AST (Абстрактного Синтаксического Дерева), чтобы найти каждое поле и вставить отсутствующие переводы.
+
+> - Если файл не существует, Intlayer сгенерирует его, используя шаблон по умолчанию для файлов объявления контента.
+
+## Абсолютные пути
+
+Поле `autoFill` также поддерживает абсолютные пути.
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  autoFill: "/messages/example.content.json",
+  content: {
+    // Ваш контент
+  },
+};
+```
+
+Это сгенерирует файл в:
+
+```
+/messages/example.content.json
+```
+
+## Автоматическая генерация файлов объявления контента для каждого языка
+
+Поле `autoFill` также поддерживает генерацию файлов объявления контента **для каждого языка**.
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  autoFill: {
+    fr: "./example.fr.content.json",
+    es: "./example.es.content.json",
+  },
+  content: {
+    // Ваш контент
+  },
+};
+```
+
+Это сгенерирует два отдельных файла:
+
+- `src/components/example/example.fr.content.json`
+- `src/components/example/example.es.content.json`
+
+## Фильтрация автозаполнения по конкретному языку
+
+Использование объекта для поля `autoFill` позволяет применять фильтры и генерировать только файлы для конкретных языков.
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  autoFill: {
+    fr: "./example.fr.content.json",
+  },
+  content: {
+    // Ваш контент
+  },
+};
+```
+
+Это сгенерирует только файл французского перевода.
+
+## Переменные пути
+
+Вы можете использовать переменные внутри пути `autoFill` для динамического разрешения целевых путей для сгенерированных файлов.
+
+**Доступные переменные:**
+
+- `{{locale}}` – Код языка (например, `fr`, `es`)
+- `{{key}}` – Ключ словаря (например, `example`)
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  autoFill: "/messages/{{locale}}/{{key}}.content.json",
+  content: {
+    // Ваш контент
+  },
+};
+```
+
+Это сгенерирует:
+
+- `/messages/fr/example.content.json`
+- `/messages/es/example.content.json`