@intlayer/docs 7.2.3 → 7.3.0-canary.0

package/docs/pt/packages/intlayer/getPrefix.md

@@ -0,0 +1,217 @@
+---
+createdAt: 2025-11-16
+updatedAt: 2025-11-16
+title: Documentação da Função getPrefix | intlayer
+description: Veja como usar a função getPrefix para o pacote intlayer
+keywords:
+  - getPrefix
+  - prefixo
+  - Intlayer
+  - intlayer
+  - Internacionalização
+  - Documentação
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - getPrefix
+history:
+  - version: 7.1.0
+    date: 2025-11-16
+    changes: Documentação inicial
+---
+
+# Documentação: Função `getPrefix` no `intlayer`
+
+## Descrição
+
+A função `getPrefix` determina o prefixo da URL para um determinado locale com base na configuração do modo de roteamento. Ela compara o locale com o locale padrão e retorna um objeto contendo três formatos diferentes de prefixo para construção flexível de URLs.
+
+**Principais Características:**
+
+- Recebe um locale como primeiro parâmetro (obrigatório)
+- Objeto `options` opcional com `defaultLocale` e `mode`
+- Retorna um objeto com as propriedades `prefix` e `localePrefix`
+- Suporta todos os modos de roteamento: `prefix-no-default`, `prefix-all`, `no-prefix` e `search-params`
+- Utilitário leve para determinar quando adicionar prefixos de locale
+
+---
+
+## Assinatura da Função
+
+```typescript
+getPrefix(
+  locale: Locales,               // Obrigatório
+  options?: {                    // Opcional
+    defaultLocale?: Locales;
+    mode?: 'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params';
+  }
+): GetPrefixResult
+
+type GetPrefixResult = {
+  prefix: string;   // ex: 'fr/' ou ''
+  localePrefix?: Locale; // ex: 'fr' ou indefinido
+}
+```
+
+---
+
+## Parâmetros
+
+- `locale: Locales`
+  - **Descrição**: O locale para o qual gerar o prefixo. Se o valor for falsy (undefined, null, string vazia), a função retorna uma string vazia.
+  - **Tipo**: `Locales`
+  - **Obrigatório**: Sim
+
+- `options?: object`
+  - **Descrição**: Objeto de configuração para determinação do prefixo.
+  - **Tipo**: `object`
+  - **Obrigatório**: Não (Opcional)
+
+  - `options.defaultLocale?: Locales`
+    - **Descrição**: O locale padrão para a aplicação. Se não fornecido, usa o locale padrão configurado na configuração do seu projeto.
+    - **Tipo**: `Locales`
+    - **Padrão**: [`Configuração do Projeto`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/configuration.md#middleware)
+
+  - `options.mode?: 'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params'`
+    - **Descrição**: O modo de roteamento da URL para o tratamento do locale. Se não fornecido, usa o modo configurado na configuração do seu projeto.
+    - **Tipo**: `'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params'`
+    - **Padrão**: [`Configuração do Projeto`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/configuration.md#middleware)
+    - **Modos**:
+      - `prefix-no-default`: Retorna strings vazias quando o locale corresponde ao locale padrão
+      - `prefix-all`: Retorna prefixo para todos os locales, incluindo o padrão
+      - `no-prefix`: Retorna strings vazias (sem prefixo nas URLs)
+      - `search-params`: Retorna strings vazias (locale nos parâmetros de consulta)
+
+### Retorna
+
+- **Tipo**: `GetPrefixResult`
+- **Descrição**: Um objeto contendo três formatos diferentes de prefixo:
+  - `prefix`: O prefixo do caminho com barra no final (ex., `'fr/'`, `''`)
+  - `localePrefix`: O identificador do locale sem barras (ex., `'fr'`, `undefined`)
+
+---
+
+## Exemplo de Uso
+
+### Uso Básico
+
+```typescript codeFormat="typescript"
+import { getPrefix, Locales } from "intlayer";
+
+// Verifica o prefixo para o locale inglês
+getPrefix(Locales.ENGLISH, {
+  defaultLocale: Locales.ENGLISH,
+  mode: "prefix-all",
+});
+// Retorna: { prefix: 'en/', localePrefix: 'en' }
+
+// Verifica o prefixo para o locale francês
+getPrefix(Locales.FRENCH, {
+  defaultLocale: Locales.ENGLISH,
+  mode: "prefix-no-default",
+});
+// Retorna: { prefix: 'fr/', localePrefix: 'fr' }
+```
+
+```javascript codeFormat="esm"
+import { getPrefix, Locales } from "intlayer";
+
+getPrefix(Locales.ENGLISH, { mode: "prefix-all" });
+javascript codeFormat="esm"
+import { getPrefix, Locales } from "intlayer";
+
+getPrefix(Locales.ENGLISH, { mode: "prefix-all" });
+// Retorna: { prefix: '', localePrefix: undefined }
+```
+
+```javascript codeFormat="commonjs"
+const { getPrefix, Locales } = require("intlayer");
+
+getPrefix(Locales.ENGLISH, { mode: "prefix-all" });
+// Retorna: { prefix: '', localePrefix: undefined }
+```
+
+### Modos Diferentes de Roteamento
+
+```typescript
+import { getPrefix, Locales } from "intlayer";
+
+// prefix-all: Sempre retorna prefixo
+getPrefix(Locales.ENGLISH, {
+  mode: "prefix-all",
+  defaultLocale: Locales.ENGLISH,
+});
+// Retorna: { prefix: '/en', localePrefix: 'en' }
+
+// prefix-no-default: Sem prefixo quando o locale coincide com o padrão
+getPrefix(Locales.ENGLISH, {
+  mode: "prefix-no-default",
+  defaultLocale: Locales.ENGLISH,
+});
+// Retorna: { prefix: '', localePrefix: undefined }
+
+// prefix-no-default: Retorna prefixo quando o locale difere do padrão
+getPrefix(Locales.FRENCH, {
+  mode: "prefix-no-default",
+  defaultLocale: Locales.ENGLISH,
+});
+// Retorna: { prefix: 'fr/', localePrefix: 'fr' }
+
+// no-prefix & search-params: Nunca retorna prefixo
+getPrefix(Locales.ENGLISH, { mode: "no-prefix" });
+// Retorna: { prefix: '', localePrefix: undefined }
+
+getPrefix(Locales.ENGLISH, { mode: "search-params" });
+// Retorna: { prefix: '', localePrefix: undefined }
+```
+
+### Exemplo Prático
+
+```typescript
+import { getPrefix, Locales } from "intlayer";
+
+// Construir URLs com o prefixo apropriado para um locale específico
+const locale = Locales.FRENCH;
+const { prefix, localePrefix } = getPrefix(locale, {
+  defaultLocale: Locales.ENGLISH,
+  mode: "prefix-no-default",
+});
+
+// Usando prefix para construção do caminho
+const url1 = `/${prefix}about`.replace(/\/+/g, "/");
+// Resultado: "/fr/about"
+
+// Usando localePrefix para identificação do locale
+console.log(`Locale atual: ${localePrefix}`);
+// Saída: "Locale atual: fr"
+```
+
+---
+
+## Funções Relacionadas
+
+- [`getLocalizedUrl`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/packages/intlayer/getLocalizedUrl.md): Gera uma URL localizada para um locale específico
+- [`getMultilingualUrls`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/packages/intlayer/getMultilingualUrls.md): Gera URLs para todos os locales configurados
+
+---
+
+## TypeScript
+
+```typescript
+type GetPrefixResult = {
+  prefix: string; // O prefixo do caminho com barra final (ex: 'fr/' ou '')
+  localePrefix?: Locale; // O identificador do locale sem barras (ex: 'fr' ou indefinido)
+};
+
+function getPrefix(
+  locale: Locales,
+  options?: {
+    defaultLocale?: Locales;
+    mode?: "prefix-no-default" | "prefix-all" | "no-prefix" | "search-params";
+  }
+): GetPrefixResult;
+```

package/docs/ru/cli/build.md

@@ -0,0 +1,64 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: Построение словарей
+description: Узнайте, как создавать словари Intlayer из файлов декларации контента.
+keywords:
+  - Построение
+  - Словари
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - build
+---
+
+# Построение словарей
+
+Для построения ваших словарей вы можете выполнить команды:
+
+```bash
+npx intlayer build
+```
+
+или в режиме наблюдения
+
+```bash
+npx intlayer build --watch
+```
+
+Эта команда по умолчанию найдет ваши файлы декларации контента по пути `./src/**/*.content.{ts|js|mjs|cjs|json|tsx|jsx}` и построит словари в директории `.intlayer`.
+
+## Псевдонимы:
+
+- `npx intlayer dictionaries build`
+- `npx intlayer dictionary build`
+- `npx intlayer dic build`
+
+## Аргументы:
+
+- **`--base-dir`**: Укажите базовую директорию для проекта. Для получения конфигурации intlayer команда будет искать файл `intlayer.config.{ts,js,json,cjs,mjs}` в базовой директории.
+
+  > Пример: `npx intlayer build --base-dir ./src`
+
+- **`--env`**: Укажите окружение (например, `development`, `production`). Полезно, если вы используете переменные окружения в вашем файле конфигурации intlayer.
+
+  > Пример: `npx intlayer build --env production`
+
+- **`--env-file`**: Укажите пользовательский файл окружения для загрузки переменных. Полезно, если вы используете переменные окружения в вашем файле конфигурации intlayer.
+
+  > Пример: `npx intlayer build --env-file .env.production.local`
+
+- **`--with`**: Запустить команду параллельно с процессом сборки.
+
+  > Пример: `npx intlayer build --with "next dev --turbopack"`
+
+- **`--skip-prepare`**: Пропустить этап подготовки.
+
+  > Пример: `npx intlayer build --skip-prepare`
+
+- **`--no-cache`**: Отключить кэш.
+
+  > Пример: `npx intlayer build --no-cache`

package/docs/ru/cli/configuration.md

@@ -0,0 +1,63 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: Управление конфигурацией
+description: Узнайте, как получить и отправить вашу конфигурацию Intlayer в CMS.
+keywords:
+  - Конфигурация
+  - Настройка
+  - CLI
+  - Intlayer
+  - CMS
+slugs:
+  - doc
+  - concept
+  - cli
+  - configuration
+---
+
+# Управление конфигурацией
+
+## Получение конфигурации
+
+Команда `configuration get` получает текущую конфигурацию для Intlayer, в частности настройки локали. Это полезно для проверки вашей настройки.
+
+```bash
+npx intlayer configuration get
+```
+
+## Псевдонимы:
+
+- `npx intlayer config get`
+- `npx intlayer conf get`
+
+## Аргументы:
+
+- **`--env`**: Укажите окружение (например, `development`, `production`).
+- **`--env-file`**: Укажите пользовательский файл окружения для загрузки переменных.
+- **`--base-dir`**: Укажите базовый каталог для проекта.
+- **`--verbose`**: Включить подробное логирование для отладки. (по умолчанию true при использовании CLI)
+- **`--no-cache`**: Отключить кэш.
+
+## Отправка конфигурации
+
+Команда `configuration push` загружает вашу конфигурацию в Intlayer CMS и редактор. Этот шаг необходим для включения использования удалённых словарей в визуальном редакторе Intlayer.
+
+```bash
+npx intlayer configuration push
+```
+
+## Псевдонимы:
+
+- `npx intlayer config push`
+- `npx intlayer conf push`
+
+## Аргументы:
+
+- **`--env`**: Укажите окружение (например, `development`, `production`).
+- **`--env-file`**: Укажите пользовательский файл окружения для загрузки переменных.
+- **`--base-dir`**: Укажите базовый каталог для проекта.
+- **`--verbose`**: Включить подробное логирование для отладки. (по умолчанию true при использовании CLI)
+- **`--no-cache`**: Отключить кэш.
+
+Отправляя конфигурацию, ваш проект полностью интегрируется с Intlayer CMS, что обеспечивает бесшовное управление словарями между командами.

package/docs/ru/cli/debug.md

@@ -0,0 +1,46 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: Отладка команды Intlayer
+description: Узнайте, как отлаживать и устранять проблемы с Intlayer CLI.
+keywords:
+  - Отладка
+  - Устранение проблем
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - debug
+---
+
+# Отладка команды intlayer
+
+## 1. **Убедитесь, что используете последнюю версию**
+
+Выполните:
+
+```bash
+npx intlayer --version                  # версия intlayer для текущей локали
+npx intlayer@latest --version           # последняя доступная версия intlayer
+```
+
+## 2. **Проверьте, зарегистрирована ли команда**
+
+Вы можете проверить с помощью:
+
+```bash
+npx intlayer --help                     # Показывает список доступных команд и информацию по использованию
+npx intlayer dictionary build --help    # Показывает список доступных опций для команды
+```
+
+## 3. **Перезапустите терминал**
+
+Иногда для распознавания новых команд требуется перезапуск терминала.
+
+## 4. **Очистите кэш npx (если вы застряли на старой версии)**
+
+```bash
+npx clear-npx-cache
+```

package/docs/ru/cli/doc-review.md

@@ -0,0 +1,43 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: Проверка документа
+description: Узнайте, как проверять файлы документации на качество, согласованность и полноту для разных локалей.
+keywords:
+  - Проверка
+  - Документ
+  - Документация
+  - AI
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - doc-review
+---
+
+# Проверка документа
+
+Команда `doc review` анализирует файлы документации на качество, согласованность и полноту для разных локалей.
+
+```bash
+npx intlayer doc review
+```
+
+Её можно использовать для проверки уже переведённых файлов и для проверки корректности перевода.
+
+В большинстве случаев,
+
+- предпочтительно использовать `doc translate`, когда переведённая версия этого файла недоступна.
+- предпочтительно использовать `doc review`, когда переведённая версия этого файла уже существует.
+
+> Обратите внимание, что процесс проверки потребляет больше входных токенов, чем процесс перевода, для полной проверки одного и того же файла. Однако процесс проверки оптимизирует количество проверяемых частей и пропускает те, которые не изменились.
+
+## Аргументы:
+
+Команда `doc review` принимает те же аргументы, что и `doc translate`, позволяя вам проверять конкретные файлы документации и применять проверки качества.
+
+Если вы активировали одну из опций git, команда будет проверять только ту часть файлов, которая изменяется. Скрипт будет обрабатывать файл по частям (чанкам) и проверять каждый из них. Если в чанке нет изменений, скрипт пропустит его, чтобы ускорить процесс проверки и снизить стоимость использования API AI-провайдера.
+
+Для полного списка аргументов смотрите документацию команды [Translate Document](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/cli/doc-translate.md).

package/docs/ru/cli/doc-translate.md

@@ -0,0 +1,132 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: Перевод документа
+description: Узнайте, как автоматически переводить файлы документации с помощью сервисов AI-перевода.
+keywords:
+  - Перевод
+  - Документ
+  - Документация
+  - AI
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - doc-translate
+---
+
+# Перевод документа
+
+Команда `doc translate` автоматически переводит файлы документации с базового языка на целевые языки с использованием сервисов AI-перевода.
+
+```bash
+npx intlayer doc translate
+```
+
+## Аргументы:
+
+**Опции списка файлов:**
+
+- **`--doc-pattern [docPattern...]`**: Глобальные шаблоны для выбора файлов документации, которые нужно перевести.
+
+  > Пример: `npx intlayer doc translate --doc-pattern "docs/**/*.md" "src/**/*.mdx"`
+
+- **`--excluded-glob-pattern [excludedGlobPattern...]`**: Глобальные шаблоны для исключения файлов из перевода.
+
+  > Пример: `npx intlayer doc translate --excluded-glob-pattern "docs/internal/**"`
+
+- **`--skip-if-modified-before [skipIfModifiedBefore]`**: Пропустить файл, если он был изменён до указанного времени.
+  - Может быть абсолютным временем, например "2025-12-05" (строка или Date)
+  - Может быть относительным временем в миллисекундах `1 * 60 * 60 * 1000` (1 час)
+  - Эта опция проверяет время обновления файла с помощью метода `fs.stat`. Поэтому она может быть затронута Git или другими инструментами, которые изменяют файл.
+
+  > Пример: `npx intlayer doc translate --skip-if-modified-before "2025-12-05"`
+
+- **`--skip-if-modified-after [skipIfModifiedAfter]`**: Пропустить файл, если он был изменён в течение указанного времени.
+  - Может быть абсолютным временем, например "2025-12-05" (строка или Date)
+  - Может быть относительным временем в миллисекундах `1 * 60 * 60 * 1000` (1 час)
+  - Эта опция проверяет время обновления файла с помощью метода `fs.stat`. Поэтому она может быть затронута Git или другими инструментами, которые изменяют файл.
+
+  > Пример: `npx intlayer doc translate --skip-if-modified-after "2025-12-05"`
+
+- **`--skip-if-exists`**: Пропустить файл, если он уже существует.
+
+  > Пример: `npx intlayer doc translate --skip-if-exists`
+
+**Опции вывода записей:**
+
+- **`--locales [locales...]`**: Целевые локали для перевода документации.
+
+  > Пример: `npx intlayer doc translate --locales fr es de`
+
+- **`--base-locale [baseLocale]`**: Исходная локаль для перевода.
+
+  > Пример: `npx intlayer doc translate --base-locale en`
+
+**Опции обработки файлов:**
+
+- **`--nb-simultaneous-file-processed [nbSimultaneousFileProcessed]`**: Количество файлов, обрабатываемых одновременно для перевода.
+
+  > Пример: `npx intlayer doc translate --nb-simultaneous-file-processed 5`
+
+**Опции ИИ:**
+
+- **`--model [model]`**: Модель ИИ, используемая для перевода (например, `gpt-3.5-turbo`).
+- **`--provider [provider]`**: Провайдер ИИ, используемый для перевода.
+- **`--temperature [temperature]`**: Параметр температуры для модели ИИ.
+- **`--api-key [apiKey]`**: Предоставьте свой собственный API-ключ для сервиса ИИ.
+- **`--application-context [applicationContext]`**: Предоставьте дополнительный контекст для перевода ИИ.
+- **`--custom-prompt [prompt]`**: Настройка базового запроса, используемого для перевода. (Примечание: для большинства случаев рекомендуется использовать опцию `--custom-instructions`, так как она обеспечивает лучший контроль над поведением перевода.)
+
+  > Пример: `npx intlayer doc translate --model deepseek-chat --provider deepseek --temperature 0.5 --api-key sk-1234567890 --application-context "Мое приложение — магазин для кошек"`
+
+**Опции переменных окружения:**
+
+- **`--env`**: Указать окружение (например, `development`, `production`).
+- **`--env-file [envFile]`**: Указать пользовательский файл окружения для загрузки переменных.
+- **`--base-dir`**: Указать базовую директорию проекта.
+- **`--no-cache`**: Отключить кэш.
+
+  > Пример: `npx intlayer doc translate --base-dir ./docs --env-file .env.production.local`
+
+**Опции логирования:**
+
+- **`--verbose`**: Включить подробное логирование для отладки. (по умолчанию включено при использовании CLI)
+
+  > Пример: `npx intlayer doc translate --verbose`
+
+**Опции пользовательских инструкций:**
+
+- **`--custom-instructions [customInstructions]`**: Пользовательские инструкции, добавляемые в запрос. Полезно для применения специфических правил касательно форматирования, перевода URL и т.д.
+  - Может быть абсолютное время, например "2025-12-05" (строка или объект Date)
+  - Может быть относительное время в миллисекундах `1 * 60 * 60 * 1000` (1 час)
+  - Эта опция проверяет время обновления файла с помощью метода `fs.stat`. Поэтому может быть затронута Git или другими инструментами, которые изменяют файл.
+
+  > Пример: `npx intlayer doc translate --custom-instructions "Избегайте перевода URL и сохраняйте формат markdown"`
+
+  > Пример: `npx intlayer doc translate --custom-instructions "$(cat ./instructions.md)"`
+
+**Опции Git:**
+
+- **`--git-diff`**: Запускать только для словарей, которые содержат изменения от базовой ветки (по умолчанию `origin/main`) до текущей ветки (по умолчанию: `HEAD`).
+- **`--git-diff-base`**: Указать базовую ссылку для git diff (по умолчанию `origin/main`).
+- **`--git-diff-current`**: Указать текущую ссылку для git diff (по умолчанию `HEAD`).
+- **`--uncommitted`**: Включать незафиксированные изменения.
+- **`--unpushed`**: Включать изменения, не отправленные в удалённый репозиторий.
+- **`--untracked`**: Включать неотслеживаемые файлы.
+
+  > Пример: `npx intlayer doc translate --git-diff --git-diff-base origin/main --git-diff-current HEAD`
+
+  > Пример: `npx intlayer doc translate --uncommitted --unpushed --untracked`
+
+> Обратите внимание, что путь к выходному файлу будет определяться путем замены следующих шаблонов
+>
+> - `/{{baseLocale}}/` на `/{{locale}}/` (Unix)
+> - `\{{baseLocale}}\` на `\{{locale}}\` (Windows)
+> - `_{{baseLocale}}.` на `_{{locale}}.`
+> - `{{baseLocale}}_` на `{{locale}}_`
+> - `.{{baseLocaleName}}.` на `.{{localeName}}.`
+>
+> Если шаблон не найден, к расширению файла будет добавлено `.{{locale}}`. Например, `./my/file.md` будет переведен в `./my/file.fr.md` для французской локали.

package/docs/ru/cli/editor.md

@@ -0,0 +1,28 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: Команды редактора
+description: Узнайте, как использовать команды редактора Intlayer.
+keywords:
+  - Редактор
+  - Визуальный редактор
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - editor
+---
+
+# Команды редактора
+
+Команда `editor` оборачивает команды `intlayer-editor`.
+
+> Чтобы иметь возможность использовать команду `editor`, должен быть установлен пакет `intlayer-editor`. (См. [Визуальный редактор Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/intlayer_visual_editor.md))
+
+```json fileName="package.json"
+"scripts": {
+  "intlayer:editor:start": "npx intlayer editor start --with 'next dev --turbopack'"
+}
+```