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

package/docs/pl/releases/v9.md

@@ -0,0 +1,232 @@
+---
+createdAt: 2026-06-14
+updatedAt: 2026-06-14
+title: Nowy Intlayer v9 - Co nowego?
+description: Odkryj nowości w Intlayer v9. Przedstawiamy pakiety kompatybilności typu drop-in dla popularnych bibliotek i18n oraz wsparcie dla Kolekcji (Collections), Wariantów (Variants) i Dynamicznych Rekordów (Dynamic Records).
+keywords:
+  - Intlayer
+  - Kompatybilność
+  - Migracja
+  - Kolekcje
+  - Warianty
+  - Dynamiczne Rekordy
+  - i18next
+  - next-intl
+  - vue-i18n
+slugs:
+  - doc
+  - releases
+  - v9
+author: aymericzip
+---
+
+# Nowy Intlayer v9 - Co nowego?
+
+Witaj w Intlayer v9! To główne wydanie (major release) stanowi ogromny krok milowy w upraszczaniu ścieżki migracji do Intlayer dzięki **pakietom kompatybilności (Compat Adapter Packages)** dla najpopularniejszych bibliotek i18n (takich jak `react-i18next`, `next-intl`, `vue-i18n` itp.) oraz wprowadza wsparcie dla bogatych struktur treści: **Kolekcji (Collections)**, **Wariantów (Variants)** i **Dynamicznych Rekordów (Dynamic Records)**.
+
+## Spis treści
+
+<TOC levels={[2]} maxDepth={1} />
+
+---
+
+## Pakiety kompatybilności (Compat Adapter Packages)
+
+Migracja do Intlayer z popularnych bibliotek i18n jest teraz łatwiejsza niż kiedykolwiek. Stworzyliśmy pięć pakietów kompatybilności (compat packages), które udostępniają **dokładnie to samo publiczne API** co standardowe biblioteki i18n, ale delegują całą pracę związaną z tłumaczeniami do Intlayer w czasie działania aplikacji (runtime).
+
+### To samo publiczne API ze ścisłym typowaniem (Strict Typing)
+
+Zastępując importy, zyskujesz wszystkie zalety Intlayer (w tym bezpieczeństwo typów w czasie kompilacji - compile-time type safety - w oparciu o Twoje rzeczywiste słowniki) przy minimalnych zmianach w kodzie:
+
+- `@intlayer/i18next`
+- `@intlayer/react-i18next`
+- `@intlayer/next-intl`
+- `@intlayer/next-i18next`
+- `@intlayer/vue-i18n`
+
+Na przykład, po prostu zmień:
+
+```ts
+import { useTranslation } from "react-i18next";
+```
+
+na:
+
+```ts
+import { useTranslation } from "@intlayer/react-i18next";
+```
+
+Twoje klucze będą teraz **ściśle typowane** (strictly typed) w oparciu o słowniki Intlayer, oferując pełne autouzupełnianie ścieżek kropkowych (dot-path) w Twoim IDE!
+
+### Pluginy aliasów dla bundlerów (Vite, Next.js, Turbopack)
+
+Aby umożliwić migrację bez konieczności ręcznego przepisywania wszystkich importów, każdy pakiet adaptera kompatybilności zawiera **dedykowany plugin dla bundlera** (Vite lub Next.js) w podścieżce `/plugin`.
+
+Pluginy te automatycznie przepisują istniejące importy (np. `react-i18next` lub `next-intl`) na ich odpowiedniki `@intlayer/*` w czasie budowania (build time).
+
+#### Przykład dla Next.js (Webpack / Turbopack)
+
+Zamiast `withIntlayer`, owiń swoją konfigurację Next.js pluginem kompatybilności:
+
+```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);
+```
+
+#### Przykład dla Vite (React, Vue, Solid, Svelte)
+
+```ts fileName="vite.config.ts"
+import vueI18nVitePlugin from "@intlayer/vue-i18n/plugin";
+
+export default defineConfig({
+  plugins: [vueI18nVitePlugin()],
+});
+```
+
+---
+
+## Wspólny parser czasu działania (Mutualized Runtime Resolver)
+
+Wszystkie adaptery kompatybilności kierują teraz proces rozwiązywania tłumaczeń przez jeden, wysoce zoptymalizowany parser czasu działania (runtime parser): `@intlayer/core/messageFormat`.
+
+- **Interpolacja wiadomości (Interpolate Message)**: Obsługuje standardowe szablony `{{var}}` (ze spacjami i ścieżkami kropkowymi), argumenty formatowane w standardzie ICU (`{v, number, percent}` itp.) oraz proste szablony `{var}`.
+- **Rozwiązywanie węzłów wiadomości (Message Node Resolver)**: Obsługuje zagnieżdżone węzły: `insert()`, `plural()` (reguły liczby mnogiej CLDR), `enu()` (wyliczenia), `gender()`, tagi HTML, tablice oraz węzły funkcji wywoływalnych (callable functions).
+- **Parser tagów tokenizowanych (Tokenized Tag Parser)**: Wspiera wbudowane tagi XML/HTML oraz tagi numerowane (np. `<1>children</1>`), aby zapewnić renderowanie bogatego tekstu (rich-text) po wyjęciu z pudełka.
+
+---
+
+## Specyfikacja funkcji: Kolekcje, Warianty i Dynamiczne Rekordy
+
+Intlayer v9 wykracza poza statyczne obiekty klucz-wartość, umożliwiając słownikom deklarowanie dynamicznych struktur układu, które są w pełni typowane od początku do końca (end-to-end).
+
+### 1. Kolekcje (Collections)
+
+Zdefiniuj zarządzaną przez CMS uporządkowaną lista elementów (np. FAQ, produkty lub listy blogów):
+
+```ts fileName="faq.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "faq",
+  content: [
+    {
+      question: t({
+        pl: "Co to jest Intlayer?",
+        en: "What is Intlayer?",
+        fr: "Qu'est-ce qu'Intlayer ?",
+      }),
+      answer: t({
+        pl: "Zestaw narzędzi i18n.",
+        en: "An i18n toolkit.",
+        fr: "Une boîte à outils i18n.",
+      }),
+    },
+  ],
+} satisfies Dictionary;
+```
+
+#### Użycie:
+
+```ts
+// Pobierz wszystkie elementy
+const allFaqs = useIntlayer("faq"); // -> { question: string, answer: string }[]
+
+// Pobierz pojedynczy element po indeksie
+const faq = useIntlayer("faq", { item: 1 }); // -> { question: string, answer: string }
+```
+
+### 2. Warianty (Variants)
+
+Dostarczaj testy A/B, nagłówki sezonowe, flagi funkcji (feature flags) lub niestandardowe strony docelowe (landing pages):
+
+```ts fileName="hero.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "hero-banner",
+  variant: "default",
+  content: {
+    control: t({ pl: "Witaj", en: "Welcome", fr: "Bienvenue" }),
+    black_friday: t({
+      pl: "Kup teraz",
+      en: "Shop now",
+      fr: "Acheter maintenant",
+    }),
+  },
+} satisfies Dictionary;
+```
+
+#### Użycie:
+
+```ts
+const banner = useIntlayer("hero-banner", { variant: "black_friday" });
+```
+
+### 3. Dynamiczne Rekordy (Dynamic Records)
+
+Definiuj słowniki, których wpisy są ładowane dynamicznie w czasie działania aplikacji (runtime) za pomocą identyfikatorów zapytań (query IDs):
+
+```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({ pl: "Czysty kod", en: "Clean Code", fr: "Code Propre" }),
+  },
+} satisfies Dictionary;
+```
+
+#### Użycie:
+
+```ts
+// Pobiera dynamicznie tylko żądany element (wymaga Suspense)
+const product = useIntlayer("product-copy", {
+  id: "prod_123",
+  category: "books",
+});
+```
+
+---
+
+## Dynamiczne ładowanie i optymalizacja rozmiaru paczki (Bundle Size)
+
+Aby zachować niezwykle mały rozmiar paczek (bundles), Intlayer v9 wspiera dynamiczne leniwe ładowanie (lazy loading).
+
+W swojej konfiguracji ustaw `importMode` na `'dynamic'` lub `'fetch'`:
+
+```ts fileName="intlayer.config.ts"
+export default {
+  dictionary: {
+    importMode: "dynamic", // "static" | "dynamic" | "fetch"
+  },
+};
+```
+
+W czasie budowania (build time), `@intlayer/swc` oraz `@intlayer/babel` skanują Twoje pliki i zastępują wywołania `useIntlayer` / `getIntlayer` opakowaniami wspierającymi tree-shaking (`useDictionary` / `useDictionaryDynamic`). Ładowana jest tylko treść wymagana dla wybranego elementu kolekcji, wariantu lub języka (locale), co zapobiega dołączaniu nieużywanych tłumaczeń do Twojej paczki produkcyjnej (production bundle).
+
+---
+
+## Uwagi dotyczące migracji z wersji v8
+
+Jeśli aktualizujesz aplikację z wersji v8, pamiętaj, że wersja v9 nie zawiera zmian wprowadzających niekompatybilność wsteczną (breaking changes). Oto jednak kluczowe zmiany:
+
+- **Języki i dialekty (Locales & Dialects)**: Jeśli używasz zewnętrznych zależności i18n, dodaj odpowiednie pluginy adapterów kompatybilności w swojej konfiguracji lub konfiguracji bundlera, aby automatycznie przepisywać importy.
+- **Niestandardowe selektory (Custom Selectors)**: Podczas wywoływania `useIntlayer`, drugi parametr jest teraz zarezerwowany dla obiektu opcji zawierającego `{ locale, item, variant, id }`. Jeśli wcześniej przekazywałeś bezpośrednio ciąg znaków języka (locale string), nadal możesz to robić, jednak zaleca się używanie obiektu opcji przy bardziej zaawansowanych wyborach.
+
+---
+
+## Przydatne linki
+
+- [Przewodnik po pakietach kompatybilności (Compat Adapter Packages)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/compat/index.md)
+- [Dynamiczne słowniki - Kolekcje, Warianty i Dynamiczne Rekordy](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/dynamic_dictionaries/index.md)
+- [Dokumentacja konfiguracji](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/configuration.md)

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

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-11
-updatedAt: 2025-11-22
+updatedAt: 2026-06-17
 title: Revisar Documento
 description: Aprenda como revisar arquivos de documentação para qualidade, consistência e completude em diferentes locais.
 keywords:
@@ -15,6 +15,10 @@ slugs:
   - concept
   - cli
   - doc-review
+history:
+  - version: 9.0.0
+    date: 2026-06-17
+    changes: "Adicionar opção --log"
 author: aymericzip
 ---
 
@@ -55,8 +59,110 @@ Para a maioria dos casos de uso,
 
 ## Argumentos:
 
-O comando `doc review` aceita os mesmos argumentos que o `doc translate`, permitindo que você revise arquivos de documentação específicos e aplique verificações de qualidade.
+**Opções de lista de arquivos:**
 
-Se você ativou uma das opções do git, o comando revisará apenas a parte dos arquivos que está sendo alterada. O script processará dividindo o arquivo em chunks e revisará cada chunk. Se não houver alterações no chunk, o script o pulará para acelerar o processo de revisão e limitar o custo da API do Provedor de IA.
+- **`--doc-pattern [docPattern...]`**: Padrões glob para corresponder aos arquivos de documentação a serem revisados.
 
-Para uma lista completa de argumentos, consulte a documentação do comando [Translate Document](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/cli/doc-translate.md).
+  > Exemplo: `npx intlayer doc review --doc-pattern "docs/**/*.md" "src/**/*.mdx"`
+
+- **`--excluded-glob-pattern [excludedGlobPattern...]`**: Padrões glob para excluir da revisão.
+
+  > Exemplo: `npx intlayer doc review --excluded-glob-pattern "docs/internal/**"`
+
+- **`--skip-if-modified-before [skipIfModifiedBefore]`**: Pular o arquivo se ele foi modificado antes do tempo especificado.
+  - Pode ser um tempo absoluto como "2025-12-05" (string ou Date)
+  - Pode ser um tempo relativo em ms `1 * 60 * 60 * 1000` (1 hora)
+  - Esta opção verifica o tempo de atualização do arquivo usando o método `fs.stat`. Portanto, pode ser impactada pelo Git ou outras ferramentas que modificam o arquivo.
+
+  > Exemplo: `npx intlayer doc review --skip-if-modified-before "2025-12-05"`
+
+- **`--skip-if-modified-after [skipIfModifiedAfter]`**: Pular o arquivo se ele foi modificado dentro do tempo especificado.
+  - Pode ser um tempo absoluto como "2025-12-05" (string ou Date)
+  - Pode ser um tempo relativo em ms `1 * 60 * 60 * 1000` (1 hora)
+  - Esta opção verifica o tempo de atualização do arquivo usando o método `fs.stat`. Portanto, pode ser impactada pelo Git ou outras ferramentas que modificam o arquivo.
+
+  > Exemplo: `npx intlayer doc review --skip-if-modified-after "2025-12-05"`
+
+- **`--skip-if-exists`**: Pular o arquivo se ele já existir.
+
+  > Exemplo: `npx intlayer doc review --skip-if-exists`
+
+**Opções de modo de revisão:**
+
+- **`--log`**: Modo apenas de registro (log-only). Não traduz com IA; em vez disso, registra os blocos que precisam de atenção (com números de linha e conteúdo) para as localidades base e de destino, a fim de ajudar outro agente a gerar as traduções.
+
+  > Exemplo: `npx intlayer doc review --log`
+
+**Opções de saída da entrada:**
+
+- **`--locales [locales...]`**: Locais de destino para revisar a documentação.
+
+  > Exemplo: `npx intlayer doc review --locales fr es de`
+
+- **`--base-locale [baseLocale]`**: Local de origem (documento base) para comparar.
+
+  > Exemplo: `npx intlayer doc review --base-locale en`
+
+**Opções de processamento de arquivos:**
+
+- **`--nb-simultaneous-file-processed [nbSimultaneousFileProcessed]`**: Número de arquivos para processar simultaneamente para a revisão.
+
+  > Exemplo: `npx intlayer doc review --nb-simultaneous-file-processed 5`
+
+**Opções de IA:**
+
+- **`--model [model]`**: O modelo de IA a ser usado para a revisão (exemplo: `gpt-3.5-turbo`).
+- **`--provider [provider]`**: O provedor de IA a ser usado para a revisão.
+- **`--temperature [temperature]`**: Configuração de temperatura para o modelo de IA.
+- **`--api-key [apiKey]`**: Forneça sua própria chave de API para o serviço de IA.
+- **`--application-context [applicationContext]`**: Forneça contexto adicional para a revisão de IA.
+- **`--data-serialization [dataSerialization]`**: O formato de serialização de dados a ser usado nas funcionalidades de IA do Intlayer. Opções: `json` (padrão, confiável), `toon` (menos tokens, menos consistente).
+- **`--custom-prompt [prompt]`**: Personalize o prompt base usado para a revisão. (Nota: Para a maioria dos casos de uso, a opção `--custom-instructions` é recomendada, pois oferece melhor controle.)
+
+  > Exemplo: `npx intlayer doc review --model deepseek-chat --provider deepseek --temperature 0.5 --api-key sk-1234567890 --application-context "Minha aplicação é uma loja de gatos"`
+
+**Opções de variáveis de ambiente:**
+
+- **`--env`**: Especifica o ambiente (exemplo: `development`, `production`).
+- **`--env-file [envFile]`**: Fornece um arquivo de ambiente personalizado para carregar variáveis.
+- **`--base-dir`**: Especifica o diretório base do projeto.
+- **`--no-cache`**: Desativa o cache.
+
+  > Exemplo: `npx intlayer doc review --base-dir ./docs --env-file .env.production.local`
+
+**Opções de log:**
+
+- **`--verbose`**: Ativa o log detalhado para depuração. (padrão para true usando CLI)
+
+  > Exemplo: `npx intlayer doc review --verbose`
+
+**Opções de instruções personalizadas:**
+
+- **`--custom-instructions [customInstructions]`**: Instruções personalizadas adicionadas ao prompt. Útil para aplicar regras específicas relacionadas à formatação, tradução de URLs, etc.
+
+  > Exemplo: `npx intlayer doc review --custom-instructions "Evite traduzir URLs e mantenha o formato markdown"`
+
+  > Exemplo: `npx intlayer doc review --custom-instructions "$(cat ./instructions.md)"`
+
+**Opções do Git:**
+
+- **`--git-diff`**: Executa apenas em arquivos que incluem alterações da base (padrão `origin/main`) para o branch atual (padrão: `HEAD`).
+- **`--git-diff-base`**: Especifica a referência base para o git diff (padrão `origin/main`).
+- **`--git-diff-current`**: Especifica a referência atual para o git diff (padrão: `HEAD`).
+- **`--uncommitted`**: Inclui alterações não comitadas.
+- **`--unpushed`**: Inclui alterações não enviadas.
+- **`--untracked`**: Inclui arquivos não rastreados.
+
+  > Exemplo: `npx intlayer doc review --git-diff --git-diff-base origin/main --git-diff-current HEAD`
+
+  > Exemplo: `npx intlayer doc review --uncommitted --unpushed --untracked`
+
+> Note que o caminho do arquivo de saída será determinado substituindo os seguintes padrões:
+>
+> - `/{{baseLocale}}/` por `/{{locale}}/` (Unix)
+> - `\{{baseLocale}}\` por `\{{locale}}\` (Windows)
+> - `_{{baseLocale}}.` por `_{{locale}}.`
+> - `{{baseLocale}}_` por `{{locale}}_`
+> - `.{{baseLocaleName}}.` por `.{{localeName}}.`
+>
+> Se o padrão não for encontrado, o arquivo de saída adicionará `.{{locale}}` na extensão do arquivo. `./my/file.md` será revisado e atualizado para `./my/file.fr.md` para o idioma francês.

package/docs/pt/cli/index.md

@@ -17,7 +17,7 @@ slugs:
   - concept
   - cli
 history:
-  - version: 8.13.0
+  - version: 9.0.0
     date: 2026-06-11
     changes: "Adicionar comando scan"
   - version: 8.6.4

package/docs/pt/cli/scan.md

@@ -18,7 +18,7 @@ slugs:
   - cli
   - scan
 history:
-  - version: 8.13.0
+  - version: 9.0.0
     date: 2026-06-11
     changes: "Adicionar comando scan"
 author: aymericzip

package/docs/pt/configuration.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-13
-updatedAt: 2026-05-12
+updatedAt: 2026-06-17
 title: Configuração (Configuration)
 description: Saiba como configurar o Intlayer para a sua aplicação. Entenda as várias configurações e opções disponíveis para personalizar o Intlayer conforme as suas necessidades.
 keywords:
@@ -14,6 +14,9 @@ slugs:
   - concept
   - configuration
 history:
+  - version: 8.10.0
+    date: 2026-06-17
+    changes: "Adicionada a opção `format` à configuração do dicionário"
   - version: 8.9.4
     date: 2026-05-12
     changes: "Adicionar suporte para o provedor LM Studio"
@@ -135,6 +138,7 @@ O Intlayer aceita os formatos de ficheiro de configuração JSON, JS, MJS e TS:
 ````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";
 
 /**
@@ -585,10 +589,38 @@ const config: IntlayerConfig = {
     }),
   },
 
+  /**
+   * Configuração do dicionário.
+   */
+  dictionary: {
+    /**
+     * Controla como os dicionários são importados.
+     * - "static": Importado estaticamente no momento da build.
+     * - "dynamic": Importado dinamicamente usando Suspense.
+     * - "fetch": Buscado dinamicamente via API de sincronização ao vivo.
+     */
+    importMode: "static",
+
+    /**
+     * O formato de mensagem padrão para todos os dicionários no projeto.
+     * - 'intlayer': Formato nativo do intlayer (padrão).
+     * - 'icu': Formato de mensagem ICU.
+     * - 'i18next': Formato i18next.
+     * - 'vue-i18n': Formato Vue I18n.
+     * - 'po': Formato GNU Gettext PO.
+     */
+    format: "icu",
+  },
+
   /**
    * Configuração de plugins.
    */
-  plugins: [],
+  plugins: [
+    syncJSON({
+      format: "icu",
+      source: ({ locale }) => `./messages/${locale}.json`,
+    }),
+  ],
 };
 
 export default config;
@@ -857,20 +889,21 @@ Definições relacionadas à forma como o conteúdo é gerido dentro da aplicaç
 
 Parâmetros que controlam as operações do dicionário, incluindo o comportamento de preenchimento automático (auto-fill) e geração de conteúdo.
 
-| Campo                       | Descrição                                                                                                                                              | Tipo                                                                                                            | Padrão      | Exemplo                                                                                     | Nota                                                                                                                                                                                                                                                                                                                                                                                                    |
-| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `fill`                      | Controla como os ficheiros de saída do preenchimento automático (tradução por IA) são gerados.                                                         | `boolean` &#124; <br/> `FilePathPattern` &#124; <br/> `Partial<Record<Locale, boolean &#124; FilePathPattern>>` | `true`      | `{ en: '/locales/en/{{key}}.json', fr: ({ key }) => '/locales/fr/${key}.json', es: false }` | • `true`: caminho padrão (mesmo ficheiro que a origem).<br/>• `false`: desativar.<br/>• Padrão string/função gera ficheiros por idioma.<br/>• Objeto por idioma: cada idioma corresponde ao seu próprio padrão; `false` ignora esse idioma.<br/>• Incluir `{{locale}}` ativa a geração por idioma.<br/>• `fill` ao nível do dicionário tem sempre precedência sobre esta definição global.              |
-| `description`               | Ajuda o editor e o CMS a compreender o propósito do dicionário. Também usado como contexto para a geração de traduções assistida por IA.               | `string`                                                                                                        | `undefined` | `'Secção do perfil do utilizador'`                                                          |                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `locale`                    | Transforma o dicionário num formato por idioma. Cada campo declarado torna-se um nó de tradução. Se ausente, o dicionário é tratado como multi-idioma. | `LocalesValues`                                                                                                 | `undefined` | `'en'`                                                                                      | Use isto quando o dicionário for específico de um único idioma em vez de conter traduções para vários.                                                                                                                                                                                                                                                                                                  |
-| `contentAutoTransformation` | Transforma automaticamente as strings de conteúdo em nós tipados (markdown, HTML ou inserção).                                                         | `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/>• Inserção : `Olá {{name}}` → `insert('Olá {{name}}')`.                                                                                                                                                                                                                                 |
-| `location`                  | Indica onde os ficheiros do dicionário estão armazenados e como são sincronizados com o CMS.                                                           | `'local'` &#124; <br/> `'remote'` &#124; <br/> `'hybrid'` &#124; <br/> `'plugin'` &#124; <br/> `string`         | `'local'`   | `'hybrid'`                                                                                  | • `'local'`: gerido apenas localmente.<br/>• `'remote'`: gerido apenas remotamente (CMS).<br/>• `'hybrid'`: gerido local e remotamente.<br/>• `'plugin'` ou string personalizada: gerido por um plugin ou fonte personalizada.                                                                                                                                                                          |
-| `importMode`                | Controla como os dicionários são importados.                                                                                                           | `'static'` &#124; <br/> `'dynamic'` &#124; <br/> `'fetch'`                                                      | `'static'`  | `'dynamic'`                                                                                 | • `'static'`: importado estaticamente.<br/>• `'dynamic'`: importado dinamicamente usando Suspense.<br/>• `'fetch'`: recuperado via Live Sync API; fallback para `'dynamic'` se falhar.<br/>• Requer plugins `@intlayer/babel` e `@intlayer/swc`.<br/>• Chaves devem ser declaradas estaticamente.<br/>• Ignorado se `optimize` estiver desativado.<br/>• Não afeta `getIntlayer`, `getDictionary`, etc. |
-| `priority`                  | Prioridade do dicionário. Valores mais altos vencem valores mais baixos na resolução de conflitos entre dicionários.                                   | `number`                                                                                                        | `undefined` | `1`                                                                                         |                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `live`                      | Depreciado - use `importMode: 'fetch'` em vez disso. Indicava se o conteúdo do dicionário devia ser recuperado dinamicamente via API Live Sync.        | `boolean`                                                                                                       | `undefined` |                                                                                             | Renomeado para `importMode: 'fetch'` na v8.0.0.                                                                                                                                                                                                                                                                                                                                                         |
-| `schema`                    | Gerado automaticamente pelo Intlayer para validação de esquema JSON.                                                                                   | `'https://intlayer.org/schema.json'`                                                                            | auto-gerado |                                                                                             | Não editar manualmente.                                                                                                                                                                                                                                                                                                                                                                                 |
-| `title`                     | Ajuda a identificar o dicionário no editor e CMS.                                                                                                      | `string`                                                                                                        | `undefined` | `'Perfil do Utilizador'`                                                                    |                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `tags`                      | Categoriza dicionários e fornece contexto ou instruções para o editor e IA.                                                                            | `string[]`                                                                                                      | `undefined` | `['utilizador', 'perfil']`                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `version`                   | Versão do dicionário remoto; ajuda a rastrear a versão atualmente em uso.                                                                              | `string`                                                                                                        | `undefined` | `'1.0.0'`                                                                                   | • Gestível no CMS.<br/>• Não editar localmente.                                                                                                                                                                                                                                                                                                                                                         |
+| Campo                       | Descrição                                                                                                                                              | Tipo                                                                                                            | Padrão       | Exemplo                                                                                     | Nota                                                                                                                                                                                                                                                                                                                                                                                                    |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `fill`                      | Controla como os ficheiros de saída do preenchimento automático (tradução por IA) são gerados.                                                         | `boolean` &#124; <br/> `FilePathPattern` &#124; <br/> `Partial<Record<Locale, boolean &#124; FilePathPattern>>` | `true`       | `{ en: '/locales/en/{{key}}.json', fr: ({ key }) => '/locales/fr/${key}.json', es: false }` | • `true`: caminho padrão (mesmo ficheiro que a origem).<br/>• `false`: desativar.<br/>• Padrão string/função gera ficheiros por idioma.<br/>• Objeto por idioma: cada idioma corresponde ao seu próprio padrão; `false` ignora esse idioma.<br/>• Incluir `{{locale}}` ativa a geração por idioma.<br/>• `fill` ao nível do dicionário tem sempre precedência sobre esta definição global.              |
+| `description`               | Ajuda o editor e o CMS a compreender o propósito do dicionário. Também usado como contexto para a geração de traduções assistida por IA.               | `string`                                                                                                        | `undefined`  | `'Secção do perfil do utilizador'`                                                          |                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `locale`                    | Transforma o dicionário num formato por idioma. Cada campo declarado torna-se um nó de tradução. Se ausente, o dicionário é tratado como multi-idioma. | `LocalesValues`                                                                                                 | `undefined`  | `'en'`                                                                                      | Use isto quando o dicionário for específico de um único idioma em vez de conter traduções para vários.                                                                                                                                                                                                                                                                                                  |
+| `contentAutoTransformation` | Transforma automaticamente as strings de conteúdo em nós tipados (markdown, HTML ou inserção).                                                         | `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/>• Inserção : `Olá {{name}}` → `insert('Olá {{name}}')`.                                                                                                                                                                                                                                 |
+| `location`                  | Indica onde os ficheiros do dicionário estão armazenados e como são sincronizados com o CMS.                                                           | `'local'` &#124; <br/> `'remote'` &#124; <br/> `'hybrid'` &#124; <br/> `'plugin'` &#124; <br/> `string`         | `'local'`    | `'hybrid'`                                                                                  | • `'local'`: gerido apenas localmente.<br/>• `'remote'`: gerido apenas remotamente (CMS).<br/>• `'hybrid'`: gerido local e remotamente.<br/>• `'plugin'` ou string personalizada: gerido por um plugin ou fonte personalizada.                                                                                                                                                                          |
+| `importMode`                | Controla como os dicionários são importados.                                                                                                           | `'static'` &#124; <br/> `'dynamic'` &#124; <br/> `'fetch'`                                                      | `'static'`   | `'dynamic'`                                                                                 | • `'static'`: importado estaticamente.<br/>• `'dynamic'`: importado dinamicamente usando Suspense.<br/>• `'fetch'`: recuperado via Live Sync API; fallback para `'dynamic'` se falhar.<br/>• Requer plugins `@intlayer/babel` e `@intlayer/swc`.<br/>• Chaves devem ser declaradas estaticamente.<br/>• Ignorado se `optimize` estiver desativado.<br/>• Não afeta `getIntlayer`, `getDictionary`, etc. |
+| `format`                    | O formato de mensagem padrão para todos os dicionários no projeto.                                                                                     | `'intlayer'` &#124; <br/> `'icu'` &#124; <br/> `'i18next'` &#124; <br/> `'vue-i18n'` &#124; <br/> `'po'`        | `'intlayer'` | `'icu'`                                                                                     | • `'intlayer'`: Formato nativo intlayer.<br/>• `'icu'`: Formato de mensagem ICU.<br/>• `'i18next'`: Formato i18next.<br/>• `'vue-i18n'`: Formato Vue I18n.<br/>• `'po'`: Formato GNU Gettext PO.                                                                                                                                                                                                        |
+| `priority`                  | Prioridade do dicionário. Valores mais altos vencem valores mais baixos na resolução de conflitos entre dicionários.                                   | `number`                                                                                                        | `undefined`  | `1`                                                                                         |                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `live`                      | Depreciado - use `importMode: 'fetch'` em vez disso. Indicava se o conteúdo do dicionário devia ser recuperado dinamicamente via API Live Sync.        | `boolean`                                                                                                       | `undefined`  |                                                                                             | Renomeado para `importMode: 'fetch'` na v8.0.0.                                                                                                                                                                                                                                                                                                                                                         |
+| `schema`                    | Gerado automaticamente pelo Intlayer para validação de esquema JSON.                                                                                   | `'https://intlayer.org/schema.json'`                                                                            | auto-gerado  |                                                                                             | Não editar manualmente.                                                                                                                                                                                                                                                                                                                                                                                 |
+| `title`                     | Ajuda a identificar o dicionário no editor e CMS.                                                                                                      | `string`                                                                                                        | `undefined`  | `'Perfil do Utilizador'`                                                                    |                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `tags`                      | Categoriza dicionários e fornece contexto ou instruções para o editor e IA.                                                                            | `string[]`                                                                                                      | `undefined`  | `['utilizador', 'perfil']`                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `version`                   | Versão do dicionário remoto; ajuda a rastrear a versão atualmente em uso.                                                                              | `string`                                                                                                        | `undefined`  | `'1.0.0'`                                                                                   | • Gestível no CMS.<br/>• Não editar localmente.                                                                                                                                                                                                                                                                                                                                                         |
 
 **Exemplo de `fill`**: