@intlayer/docs 8.12.5-canary.0 → 9.0.0-canary.3

package/docs/pt/releases/v9.md

@@ -0,0 +1,232 @@
+---
+createdAt: 2026-06-14
+updatedAt: 2026-06-14
+title: Novo Intlayer v9 - O que há de novo?
+description: Descubra o que há de novo no Intlayer v9. Apresentando pacotes de compatibilidade drop-in para bibliotecas i18n populares e suporte para Collections, Variants e Dynamic Records.
+keywords:
+  - Intlayer
+  - Compatibility
+  - Migration
+  - Collections
+  - Variants
+  - Dynamic Records
+  - i18next
+  - next-intl
+  - vue-i18n
+slugs:
+  - doc
+  - releases
+  - v9
+author: aymericzip
+---
+
+# Novo Intlayer v9 - O que há de novo?
+
+Bem-vindo ao Intlayer v9! Este grande lançamento marca um marco enorme na simplificação do caminho de migração para o Intlayer com **Compat Adapter Packages** para as principais bibliotecas de i18n (`react-i18next`, `next-intl`, `vue-i18n`, etc.) e adiciona suporte para estruturas de conteúdo ricas: **Collections**, **Variants** e **Dynamic Records**.
+
+## Tabela de conteúdos
+
+<TOC levels={[2]} maxDepth={1} />
+
+---
+
+## Compat Adapter Packages
+
+Migrar para o Intlayer a partir de bibliotecas i18n populares agora é mais fácil do que nunca. Criamos cinco pacotes de compatibilidade que expõem as **mesmas APIs públicas** que as bibliotecas i18n padrão, mas delegam todo o trabalho de tradução para o Intlayer em runtime.
+
+### Expor a Mesma API Pública com Strict Typing
+
+Ao substituir os imports, você obtém todos os benefícios do Intlayer (incluindo type safety em tempo de compilação contra seus dicionários reais) com o mínimo de alterações no código:
+
+- `@intlayer/i18next`
+- `@intlayer/react-i18next`
+- `@intlayer/next-intl`
+- `@intlayer/next-i18next`
+- `@intlayer/vue-i18n`
+
+Por exemplo, basta alterar:
+
+```ts
+import { useTranslation } from "react-i18next";
+```
+
+para:
+
+```ts
+import { useTranslation } from "@intlayer/react-i18next";
+```
+
+Suas chaves agora serão **strictly typed** (fortemente tipadas) contra seus dicionários Intlayer, oferecendo auto-complete completo de dot-path na sua IDE!
+
+### Plugins de Alias de Bundler (Vite, Next.js, Turbopack)
+
+Para permitir a migração sem reescrever todas as suas declarações de import manualmente, cada pacote de compatibilidade inclui um **plugin de bundler personalizado** (Vite ou Next.js) sob o subcaminho `/plugin`.
+
+Esses plugins reescrevem automaticamente os imports existentes (ex: `react-i18next` ou `next-intl`) para seus equivalentes `@intlayer/*` em tempo de build.
+
+#### Exemplo de Next.js (Webpack / Turbopack)
+
+Em vez de `withIntlayer`, envolva sua configuração do Next.js com o plugin de compatibilidade:
+
+```ts fileName="next.config.ts"
+import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";
+import type { NextConfig } from "next";
+
+const withIntlayer = createNextI18nPlugin();
+const nextConfig: NextConfig = {};
+
+export default withIntlayer(nextConfig);
+```
+
+#### Exemplo de Vite (React, Vue, Solid, Svelte)
+
+```ts fileName="vite.config.ts"
+import vueI18nVitePlugin from "@intlayer/vue-i18n/plugin";
+
+export default defineConfig({
+  plugins: [vueI18nVitePlugin()],
+});
+```
+
+---
+
+## Mutualized Runtime Resolver
+
+Todos os adaptadores de compatibilidade agora roteiam a resolução de tradução através de um único parser de runtime altamente otimizado: `@intlayer/core/messageFormat`.
+
+- **Interpolate Message**: Resolve `{{var}}` padrão (espaços em branco e dot-paths), argumentos formatados em ICU (`{v, number, percent}` etc.) e templates simples `{var}`.
+- **Message Node Resolver**: Resolve nós aninhados: `insert()`, `plural()` (regras de plural CLDR), `enu()` (enumeração), `gender()`, tags HTML, arrays e nós de funções chamáveis.
+- **Tokenized Tag Parser**: Suporta tags XML/HTML inline e tags numeradas (ex: `<1>children</1>`) para habilitar renderização de rich-text nativamente.
+
+---
+
+## Especificação de Recursos: Collections, Variants & Dynamic Records
+
+O Intlayer v9 vai além de objetos estáticos de chave-valor, permitindo que os dicionários declarem estruturas de layout dinâmicas que são totalmente tipadas de ponta a ponta.
+
+### 1. Collections
+
+Defina uma lista gerenciada por CMS de itens ordenados (ex: FAQs, produtos ou listas de blog):
+
+```ts fileName="faq.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "faq",
+  content: [
+    {
+      question: t({
+        pt: "O que é o Intlayer?",
+        en: "What is Intlayer?",
+        fr: "Qu'est-ce qu'Intlayer ?",
+      }),
+      answer: t({
+        pt: "Um kit de ferramentas i18n.",
+        en: "An i18n toolkit.",
+        fr: "Une boîte à outils i18n.",
+      }),
+    },
+  ],
+} satisfies Dictionary;
+```
+
+#### Uso:
+
+```ts
+// Buscar todos os itens
+const allFaqs = useIntlayer("faq"); // -> { question: string, answer: string }[]
+
+// Buscar um único item por índice
+const faq = useIntlayer("faq", { item: 1 }); // -> { question: string, answer: string }
+```
+
+### 2. Variants
+
+Entregue testes A/B, cabeçalhos sazonais, feature flags ou landing pages personalizadas:
+
+```ts fileName="hero.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "hero-banner",
+  variant: "default",
+  content: {
+    control: t({ pt: "Bem-vindo", en: "Welcome", fr: "Bienvenue" }),
+    black_friday: t({
+      pt: "Compre agora",
+      en: "Shop now",
+      fr: "Acheter maintenant",
+    }),
+  },
+} satisfies Dictionary;
+```
+
+#### Uso:
+
+```ts
+const banner = useIntlayer("hero-banner", { variant: "black_friday" });
+```
+
+### 3. Dynamic Records
+
+Defina dicionários cujas entradas são carregadas dinamicamente em runtime via IDs de consulta:
+
+```ts fileName="product.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "product-copy",
+  meta: {
+    id: "prod_123",
+    category: "books",
+  },
+  content: {
+    title: t({ pt: "Código Limpo", en: "Clean Code", fr: "Code Propre" }),
+  },
+} satisfies Dictionary;
+```
+
+#### Uso:
+
+```ts
+// Busca apenas o item solicitado dinamicamente (requer Suspense)
+const product = useIntlayer("product-copy", {
+  id: "prod_123",
+  category: "books",
+});
+```
+
+---
+
+## Carregamento Dinâmico & Otimizações de Tamanho de Bundle
+
+Para manter os bundles extremamente pequenos, o Intlayer v9 suporta dynamic lazy loading.
+
+Na sua configuração, defina `importMode` como `'dynamic'` ou `'fetch'`:
+
+```ts fileName="intlayer.config.ts"
+export default {
+  dictionary: {
+    importMode: "dynamic", // "static" | "dynamic" | "fetch"
+  },
+};
+```
+
+Em tempo de build, o `@intlayer/swc` e o `@intlayer/babel` escaneiam seus arquivos e substituem as chamadas de `useIntlayer` / `getIntlayer` por wrappers tree-shakeable (`useDictionary` / `useDictionaryDynamic`). Apenas o conteúdo necessário para o item da coleção, variante ou locale selecionado é carregado, evitando que seu bundle de produção contenha traduções não utilizadas.
+
+---
+
+## Notas de migração da v8
+
+Se você estiver atualizando da v8, observe que a v9 não inclui breaking changes. Mas aqui estão as principais mudanças:
+
+- **Locales & Dialects**: Se estiver usando dependências externas de i18n, adicione seus respectivos plugins de compatibilidade na sua configuração ou setup do bundler para reescrever os imports automaticamente.
+- **Custom Selectors**: Ao chamar `useIntlayer`, o segundo parâmetro agora é reservado para um objeto de opções contendo `{ locale, item, variant, id }`. Se você passava anteriormente uma string de locale diretamente, ainda pode fazer isso, mas o uso do objeto de opções é recomendado para seleções avançadas.
+
+---
+
+## Links úteis
+
+- [Guia de Compat Adapter Packages](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/compat/index.md)
+- [Dicionários Dinâmicos - Collections, Variants & Dynamic Records](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/dynamic_dictionaries/index.md)
+- [Referência de Configuração](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/configuration.md)

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

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-11
-updatedAt: 2025-11-22
+updatedAt: 2026-06-17
 title: Проверка документа
 description: Узнайте, как проверять файлы документации на качество, согласованность и полноту для разных локалей.
 keywords:
@@ -15,6 +15,10 @@ slugs:
   - concept
   - cli
   - doc-review
+history:
+  - version: 9.0.0
+    date: 2026-06-17
+    changes: "Добавить опцию --log"
 author: aymericzip
 ---
 
@@ -55,8 +59,110 @@ bun x intlayer doc review
 
 ## Аргументы:
 
-Команда `doc review` принимает те же аргументы, что и `doc translate`, позволяя вам проверять конкретные файлы документации и применять проверки качества.
+**Опции списка файлов:**
 
-Если вы активировали одну из опций git, команда будет проверять только ту часть файлов, которая изменяется. Скрипт будет обрабатывать файл по частям (чанкам) и проверять каждый из них. Если в чанке нет изменений, скрипт пропустит его, чтобы ускорить процесс проверки и снизить стоимость использования API AI-провайдера.
+- **`--doc-pattern [docPattern...]`**: Глобальные шаблоны для выбора файлов документации, которые нужно проверить.
 
-Для полного списка аргументов смотрите документацию команды [Translate Document](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/cli/doc-translate.md).
+  > Пример: `npx intlayer doc review --doc-pattern "docs/**/*.md" "src/**/*.mdx"`
+
+- **`--excluded-glob-pattern [excludedGlobPattern...]`**: Глобальные шаблоны для исключения файлов из проверки.
+
+  > Пример: `npx intlayer doc review --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 review --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 review --skip-if-modified-after "2025-12-05"`
+
+- **`--skip-if-exists`**: Пропустить файл, если он уже существует.
+
+  > Пример: `npx intlayer doc review --skip-if-exists`
+
+**Опции режима проверки:**
+
+- **`--log`**: Режим только логирования. Не переводить с помощью ИИ; вместо этого логировать блоки, требующие внимания (с номерами строк и содержимым) для базовой и целевой локалей, чтобы помочь другому агенту сгенерировать переводы.
+
+  > Пример: `npx intlayer doc review --log`
+
+**Опции вывода записей:**
+
+- **`--locales [locales...]`**: Целевые локали для проверки документации.
+
+  > Пример: `npx intlayer doc review --locales fr es de`
+
+- **`--base-locale [baseLocale]`**: Исходная локаль (базовый документ) для сравнения.
+
+  > Пример: `npx intlayer doc review --base-locale en`
+
+**Опции обработки файлов:**
+
+- **`--nb-simultaneous-file-processed [nbSimultaneousFileProcessed]`**: Количество файлов, обрабатываемых одновременно для проверки.
+
+  > Пример: `npx intlayer doc review --nb-simultaneous-file-processed 5`
+
+**Опции ИИ:**
+
+- **`--model [model]`**: Модель ИИ, используемая для проверки (например, `gpt-3.5-turbo`).
+- **`--provider [provider]`**: Провайдер ИИ, используемый для проверки.
+- **`--temperature [temperature]`**: Параметр температуры для модели ИИ.
+- **`--api-key [apiKey]`**: Предоставьте свой собственный API-ключ для сервиса ИИ.
+- **`--application-context [applicationContext]`**: Предоставьте дополнительный контекст для проверки ИИ.
+- **`--data-serialization [dataSerialization]`**: Формат сериализации данных для использования в функциях ИИ Intlayer. Опции: `json` (стандартный, надежный), `toon` (меньше токенов, менее стабильный).
+- **`--custom-prompt [prompt]`**: Настройка базового запроса, используемого для проверки. (Примечание: для большинства случаев рекомендуется использовать опцию `--custom-instructions`, так как она обеспечивает лучший контроль.)
+
+  > Пример: `npx intlayer doc review --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 review --base-dir ./docs --env-file .env.production.local`
+
+**Опции логирования:**
+
+- **`--verbose`**: Включить подробное логирование для отладки. (по умолчанию включено при использовании CLI)
+
+  > Пример: `npx intlayer doc review --verbose`
+
+**Опции пользовательских инструкций:**
+
+- **`--custom-instructions [customInstructions]`**: Пользовательские инструкции, добавляемые в запрос. Полезно для применения специфических правил касательно форматирования, перевода URL и т.д.
+
+  > Пример: `npx intlayer doc review --custom-instructions "Избегайте перевода URL и сохраняйте формат markdown"`
+
+  > Пример: `npx intlayer doc review --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 review --git-diff --git-diff-base origin/main --git-diff-current HEAD`
+
+  > Пример: `npx intlayer doc review --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/index.md

@@ -17,7 +17,7 @@ slugs:
   - concept
   - cli
 history:
-  - version: 8.13.0
+  - version: 9.0.0
     date: 2026-06-11
     changes: "Добавлена команда scan"
   - version: 8.6.4

package/docs/ru/cli/scan.md

@@ -18,7 +18,7 @@ slugs:
   - cli
   - scan
 history:
-  - version: 8.13.0
+  - version: 9.0.0
     date: 2026-06-11
     changes: "Добавлена команда scan"
 author: aymericzip

package/docs/ru/configuration.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-13
-updatedAt: 2026-05-12
+updatedAt: 2026-06-17
 title: Конфигурация (Configuration)
 description: Узнайте, как настроить Intlayer для вашего приложения. Разберитесь в различных параметрах и опциях, доступных для настройки Intlayer в соответствии с вашими потребностями.
 keywords:
@@ -14,6 +14,9 @@ slugs:
   - concept
   - configuration
 history:
+  - version: 8.10.0
+    date: 2026-06-17
+    changes: "Добавлена опция `format` в конфигурацию словаря"
   - version: 8.9.4
     date: 2026-05-12
     changes: "Добавлена поддержка провайдера LM Studio"
@@ -135,6 +138,7 @@ Intlayer принимает форматы файлов конфигурации
 ````typescript fileName="intlayer.config.ts" codeFormat="typescript"
 import { Locales, type IntlayerConfig } from "intlayer";
 import { nextjsRewrite } from "intlayer/routing";
+import { syncJSON } from "@intlayer/sync-json-plugin";
 import { z } from "zod";
 
 /**
@@ -582,10 +586,38 @@ const config: IntlayerConfig = {
     }),
   },
 
+  /**
+   * Конфигурация словаря.
+   */
+  dictionary: {
+    /**
+     * Управляет способом импорта словарей.
+     * - "static": Статически импортируется во время сборки.
+     * - "dynamic": Динамически импортируется с помощью Suspense.
+     * - "fetch": Динамически загружается через API живой синхронизации.
+     */
+    importMode: "static",
+
+    /**
+     * Формат сообщений по умолчанию для всех словарей в проекте.
+     * - 'intlayer': Собственный формат intlayer (по умолчанию).
+     * - 'icu': Формат сообщений ICU.
+     * - 'i18next': Формат i18next.
+     * - 'vue-i18n': Формат Vue I18n.
+     * - 'po': Формат GNU Gettext PO.
+     */
+    format: "icu",
+  },
+
   /**
    * Конфигурация плагинов.
    */
-  plugins: [],
+  plugins: [
+    syncJSON({
+      format: "icu",
+      source: ({ locale }) => `./messages/${locale}.json`,
+    }),
+  ],
 };
 
 export default config;
@@ -862,6 +894,7 @@ export default config;
 | `contentAutoTransformation` | Автоматически преобразует строки контента в типизированные узлы (markdown, HTML или вставка).                                                            | `boolean` &#124; <br/> `{ markdown?: boolean; html?: boolean; insertion?: boolean }`                            | `false`        | `true`                                                                                      | • Markdown : `### Title` → `md('### Title')`.<br/>• HTML : `<div>Title</div>` → `html('<div>Title</div>')`.<br/>• Вставка : `Hello {{name}}` → `insert('Hello {{name}}')`.                                                                                                                                                                                                                      |
 | `location`                  | Указывает, где хранятся файлы словарей и как они синхронизируются с CMS.                                                                                 | `'local'` &#124; <br/> `'remote'` &#124; <br/> `'hybrid'` &#124; <br/> `'plugin'` &#124; <br/> `string`         | `'local'`      | `'hybrid'`                                                                                  | • `'local'`: управление только локально.<br/>• `'remote'`: управление только удаленно (CMS).<br/>• `'hybrid'`: управление и локально, и удаленно.<br/>• `'plugin'` или кастомная строка: управление плагином или кастомным источником.                                                                                                                                                          |
 | `importMode`                | Управляет способом импорта словарей.                                                                                                                     | `'static'` &#124; <br/> `'dynamic'` &#124; <br/> `'fetch'`                                                      | `'static'`     | `'dynamic'`                                                                                 | • `'static'`: статический импорт.<br/>• `'dynamic'`: динамический импорт через Suspense.<br/>• `'fetch'`: получение через Live Sync API; откат к `'dynamic'` при неудаче.<br/>• Требует плагины `@intlayer/babel` и `@intlayer/swc`.<br/>• Ключи должны быть объявлены статически.<br/>• Игнорируется, если `optimize` выключен.<br/>• Не влияет на `getIntlayer`, `getDictionary` и т.д.       |
+| `format`                    | Формат сообщений по умолчанию для всех словарей в проекте.                                                                                               | `'intlayer'` &#124; <br/> `'icu'` &#124; <br/> `'i18next'` &#124; <br/> `'vue-i18n'` &#124; <br/> `'po'`        | `'intlayer'`   | `'icu'`                                                                                     | • `'intlayer'`: Собственный формат intlayer.<br/>• `'icu'`: Формат сообщений ICU.<br/>• `'i18next'`: Формат i18next.<br/>• `'vue-i18n'`: Формат Vue I18n.<br/>• `'po'`: Формат GNU Gettext PO.                                                                                                                                                                                                  |
 | `priority`                  | Приоритет словаря. Более высокие значения побеждают более низкие при разрешении конфликтов между словарями.                                              | `number`                                                                                                        | `undefined`    | `1`                                                                                         |                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `live`                      | Устарело - используйте `importMode: 'fetch'`. Указывало, должен ли контент словаря получаться динамически через Live Sync API.                           | `boolean`                                                                                                       | `undefined`    |                                                                                             | Переименовано в `importMode: 'fetch'` в v8.0.0.                                                                                                                                                                                                                                                                                                                                                 |
 | `schema`                    | Генерируется автоматически Intlayer для валидации JSON-схемы.                                                                                            | `'https://intlayer.org/schema.json'`                                                                            | авто-генерация |                                                                                             | Не редактируйте вручную.                                                                                                                                                                                                                                                                                                                                                                        |