@intlayer/docs 9.3.3 → 9.4.0

package/docs/pt/migration_from_nuxtjs_i18n_to_intlayer.md

@@ -46,7 +46,7 @@ Intlayer também é a solução **desenvolvida mais ativamente** no ecossistema
 
 <Accordion header="Agentes de IA">
 
-A co-localização do conteúdo **reduz o contexto necessário** para Modelos de Linguagem de Grande Escala (LLMs). O Intlayer também oferece um conjunto de ferramentas como uma **CLI** para testar traduções ausentes, **[LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/lsp.md)**, **[MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/mcp_server.md)** e **[Habilidades de Agente](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/agent_skills.md)** para tornar a Experiência do Desenvolvedor (DX) muito mais suave para agentes de IA.
+A co-localização do conteúdo **reduz o contexto necessário** para Modelos de Linguagem de Grande Escala (LLMs). O Intlayer também oferece um conjunto de ferramentas como uma **CLI** para testar traduções ausentes, **[LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/lsp.md)**, **[MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/mcp_server.md)** e **[Agent Skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/agent_skills.md)** para tornar a Experiência do Desenvolvedor (DX) muito mais suave para agentes de IA.
 
 </Accordion>
 

package/docs/pt/migration_from_react-i18next_to_intlayer.md

@@ -46,7 +46,7 @@ Intlayer também é a solução **desenvolvida mais ativamente** no ecossistema
 
 <Accordion header="Agentes de IA">
 
-A co-localização do conteúdo **reduz o contexto necessário** para Modelos de Linguagem de Grande Escala (LLMs). O Intlayer também oferece um conjunto de ferramentas como uma **CLI** para testar traduções ausentes, **[LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/lsp.md)**, **[MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/mcp_server.md)** e **[Habilidades de Agente](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/agent_skills.md)** para tornar a Experiência do Desenvolvedor (DX) muito mais suave para agentes de IA.
+A co-localização do conteúdo **reduz o contexto necessário** para Modelos de Linguagem de Grande Escala (LLMs). O Intlayer também oferece um conjunto de ferramentas como uma **CLI** para testar traduções ausentes, **[LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/lsp.md)**, **[MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/mcp_server.md)** e **[Agent Skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/agent_skills.md)** para tornar a Experiência do Desenvolvedor (DX) muito mais suave para agentes de IA.
 
 </Accordion>
 

package/docs/pt/migration_from_vue-i18n_to_intlayer.md

@@ -45,7 +45,7 @@ Intlayer também é a solução **desenvolvida mais ativamente** no ecossistema
 
 <Accordion header="Agentes de IA">
 
-A co-localização do conteúdo **reduz o contexto necessário** para Modelos de Linguagem de Grande Escala (LLMs). O Intlayer também oferece um conjunto de ferramentas como uma **CLI** para testar traduções ausentes, **[LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/lsp.md)**, **[MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/mcp_server.md)** e **[Habilidades de Agente](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/agent_skills.md)** para tornar a Experiência do Desenvolvedor (DX) muito mais suave para agentes de IA.
+A co-localização do conteúdo **reduz o contexto necessário** para Modelos de Linguagem de Grande Escala (LLMs). O Intlayer também oferece um conjunto de ferramentas como uma **CLI** para testar traduções ausentes, **[LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/lsp.md)**, **[MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/mcp_server.md)** e **[Agent Skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/agent_skills.md)** para tornar a Experiência do Desenvolvedor (DX) muito mais suave para agentes de IA.
 
 </Accordion>
 

package/docs/pt/packages/elysia-intlayer/exports.md

@@ -0,0 +1,136 @@
+---
+createdAt: 2026-08-24
+updatedAt: 2026-08-24
+title: Documentação do pacote elysia-intlayer
+description: Plugin Elysia para o Intlayer, fornecendo funções de tradução e detecção de locale.
+keywords:
+  - elysia-intlayer
+  - elysia
+  - plugin
+  - internacionalização
+  - i18n
+slugs:
+  - doc
+  - packages
+  - elysia-intlayer
+  - exports
+history:
+  - version: 9.4.0
+    date: 2026-08-24
+    changes: "Documentação unificada para todas as exportações"
+author: aymericzip
+---
+
+# Pacote elysia-intlayer
+
+O pacote `elysia-intlayer` fornece um plugin para aplicações Elysia para tratar da internacionalização. Ele deteta o locale do utilizador e injeta um objeto `intlayer` no contexto da rota.
+
+## Instalação
+
+```bash packageManager="npm"
+npm install intlayer elysia-intlayer
+```
+
+```bash packageManager="pnpm"
+pnpm add intlayer elysia-intlayer
+```
+
+```bash packageManager="yarn"
+yarn add intlayer elysia-intlayer
+```
+
+```bash packageManager="bun"
+bun add intlayer elysia-intlayer
+```
+
+> `elysia` é uma peer dependency (`>=1.0.0`). O Elysia tem como alvo o runtime **Bun**.
+
+## Exportações
+
+### Plugin
+
+Importação:
+
+```ts
+import { intlayer } from "elysia-intlayer";
+```
+
+| Função     | Descrição                                                                                                                                                                                                                                                                                                                          | Documento Relacionado                                                                                          |
+| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `intlayer` | Plugin Elysia que integra o Intlayer na sua aplicação Elysia. Trata da deteção do locale a partir do storage (cookies, headers) e depois de `Accept-Language`, injeta um objeto `intlayer` que expõe `locale`, `t`, `getIntlayer` e `getDictionary` no contexto da rota, e configura o contexto de request do `AsyncLocalStorage`. | [intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/packages/elysia-intlayer/intlayer.md) |
+
+### Funções
+
+Importação:
+
+```ts
+import { t, getIntlayer, getDictionary } from "elysia-intlayer";
+```
+
+| Função          | Descrição                                                                                                                                                                                                                                                           | Documento Relacionado                                                                                  |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `t`             | Função de tradução global que obtém o conteúdo para o locale atual no Elysia. Usa `AsyncLocalStorage` para aceder ao contexto de request configurado pelo plugin `intlayer` e recorre ao locale por omissão fora dele. Também acessível através de `intlayer.t`.    | [translation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/dictionary/translation.md) |
+| `getIntlayer`   | Obtém um dicionário pela sua chave a partir da declaração gerada e devolve o seu conteúdo para o locale atual. Versão otimizada de `getDictionary`. Usa `AsyncLocalStorage` para aceder ao contexto da request. Também acessível através de `intlayer.getIntlayer`. | -                                                                                                      |
+| `getDictionary` | Processa objetos de dicionário e devolve o conteúdo para o locale atual. Processa traduções `t()`, enumerações, markdown, HTML, etc. Usa `AsyncLocalStorage` para aceder ao contexto da request. Também acessível através de `intlayer.getDictionary`.              | -                                                                                                      |
+
+### Tipos
+
+Importação:
+
+```ts
+import type { IntlayerContext, TranslateFunction } from "elysia-intlayer";
+```
+
+| Tipo                | Descrição                                                                                                                                                          |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `IntlayerContext`   | Forma do objeto `intlayer` injetado em cada contexto de rota: `locale`, `locale_storage`, `locale_detected`, `defaultLocale`, `t`, `getIntlayer`, `getDictionary`. |
+| `TranslateFunction` | Assinatura da função de tradução, que traduz um locale map no conteúdo correspondente ao locale da request atual.                                                  |
+
+## Uso
+
+```ts fileName="src/index.ts"
+import { Elysia } from "elysia";
+import { getDictionary, getIntlayer, intlayer, t } from "elysia-intlayer";
+import dictionaryExample from "./index.content";
+
+const app = new Elysia()
+  // Carregue o plugin de internacionalização
+  .use(intlayer())
+  // Ler a locale e os helpers do contexto da rota
+  .get("/", ({ intlayer }) => ({
+    locale: intlayer!.locale,
+    greeting: intlayer!.t({
+      pt: "Olá",
+      en: "Hello",
+      fr: "Bonjour",
+      es: "Hola",
+    }),
+    content: intlayer!.getIntlayer("index").exampleOfContent,
+  }))
+  // Ou usar os helpers standalone, vinculados à requisição atual
+  .get("/t_example", () =>
+    t({
+      pt: "Exemplo de conteúdo retornado em português",
+      en: "Example of returned content in English",
+      fr: "Exemple de contenu renvoyé en français",
+      es: "Ejemplo de contenido devuelto en español",
+    })
+  )
+  .get("/getIntlayer_example", () => getIntlayer("index").exampleOfContent)
+  .get(
+    "/getDictionary_example",
+    () => getDictionary(dictionaryExample).exampleOfContent
+  )
+  .listen(3000);
+
+console.log(
+  `🦊 Elysia is running at ${app.server?.hostname}:${app.server?.port}`
+);
+```
+
+> O plugin registra seu contexto por meio de um `derive` **global**, que o Elysia tipa como `Partial<{ intlayer: IntlayerContext }>`. Em tempo de execução o valor está sempre presente para as rotas registradas após `.use(intlayer())`, portanto use a non-null assertion (`intlayer!.locale`) — ou optional chaining — para satisfazer o TypeScript no modo `strict`.
+
+## Documentação relacionada
+
+- [Elysia i18n - Guia completo para traduzir sua aplicação](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_with_elysia.md)
+- [Configuração](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/configuration.md)

package/docs/pt/packages/elysia-intlayer/intlayer.md

@@ -0,0 +1,139 @@
+---
+createdAt: 2026-08-24
+updatedAt: 2026-08-24
+title: Documentação do Plugin intlayer para Elysia | elysia-intlayer
+description: Veja como utilizar o plugin intlayer do pacote elysia-intlayer
+keywords:
+  - intlayer
+  - elysia
+  - plugin
+  - Intlayer
+  - Internacionalização
+  - Documentação
+slugs:
+  - doc
+  - packages
+  - elysia-intlayer
+  - intlayer
+history:
+  - version: 9.4.0
+    date: 2026-08-24
+    changes: "Inicialização da documentação"
+author: aymericzip
+---
+
+# Documentação do Plugin intlayer para Elysia
+
+O plugin `intlayer` para Elysia deteta o locale do utilizador e injeta um objeto `intlayer` no contexto da rota. Também permite o uso de funções de tradução globais dentro do contexto da request.
+
+## Uso
+
+```ts fileName="src/index.ts"
+import { Elysia } from "elysia";
+import { intlayer } from "elysia-intlayer";
+
+const app = new Elysia().use(intlayer()).get("/", ({ intlayer }) =>
+  intlayer!.t({
+    pt: "Olá",
+    en: "Hello",
+    fr: "Bonjour",
+    es: "Hola",
+  })
+);
+```
+
+> O plugin registra seu contexto por meio de um `derive` **global**, que o Elysia tipa como `Partial<{ intlayer: IntlayerContext }>`. Em tempo de execução o valor está sempre presente para as rotas registradas após `.use(intlayer())`, portanto use a non-null assertion (`intlayer!.t`) — ou optional chaining — para satisfazer o TypeScript no modo `strict`.
+
+Os mesmos helpers estão disponíveis como exports autónomos, para que possa chamá-los sem desestruturar o contexto da rota:
+
+```ts fileName="src/index.ts"
+import { Elysia } from "elysia";
+import { intlayer, t } from "elysia-intlayer";
+
+const app = new Elysia().use(intlayer()).get("/", () =>
+  t({
+    pt: "Olá",
+    en: "Hello",
+    fr: "Bonjour",
+    es: "Hola",
+  })
+);
+```
+
+## Descrição
+
+O plugin realiza as seguintes tarefas:
+
+1. **Detecção de locale**: Lê o locale definido explicitamente pelo cliente a partir do storage (cookie, header) e, em seguida, recorre ao locale negociado a partir do header `Accept-Language`.
+2. **Injeção no contexto**: Adiciona uma propriedade `intlayer` ao contexto de rota do Elysia (veja a tabela Contexto da rota abaixo).
+3. **Gerenciamento de contexto**: Utiliza `AsyncLocalStorage` para gerir um contexto assíncrono, permitindo que as funções globais do Intlayer (`t`, `getIntlayer`, `getDictionary`) acedam ao locale específico da request sem terem de passar o objeto de contexto.
+4. **Preparação dos dicionários**: Chama `prepareIntlayer` quando o plugin é criado, de modo que os dicionários são construídos na inicialização da aplicação.
+
+### Contexto da rota
+
+| Propriedade       | Tipo                   | Descrição                                                                                      |
+| ----------------- | ---------------------- | ---------------------------------------------------------------------------------------------- |
+| `locale`          | `Locale`               | O locale a usar nesta request, com `locale_storage` a ter precedência sobre `locale_detected`. |
+| `locale_storage`  | `Locale` (opcional)    | O locale explicitamente pedido pelo cliente através de um cookie ou de um header.              |
+| `locale_detected` | `Locale`               | O locale negociado a partir dos headers da request.                                            |
+| `defaultLocale`   | `Locale`               | O locale configurado como fallback no `intlayer.config.ts`.                                    |
+| `t`               | `TranslateFunction`    | Uma função de tradução.                                                                        |
+| `getIntlayer`     | `typeof getIntlayer`   | Uma função para obter dicionários pela sua chave.                                              |
+| `getDictionary`   | `typeof getDictionary` | Uma função para processar objetos de dicionário.                                               |
+
+> Ao contrário dos plugins Intlayer baseados em Node, `elysia-intlayer` apoia-se em `AsyncLocalStorage` em vez de `cls-hooked`, porque `cls-hooked` depende de `async_hooks.createHook`, que o Bun não implementa.
+
+O contexto da request é libertado assim que a resposta é mapeada, para que os helpers autónomos nunca sejam resolvidos contra uma request já terminada. Quando chamados fora de uma request tratada pelo plugin, recorrem ao locale por omissão configurado.
+
+## Ordem de resolução da locale
+
+Por padrão, o plugin resolve a locale nesta ordem:
+
+1. O cookie `INTLAYER_LOCALE`.
+2. O header `x-intlayer-locale`.
+3. A negociação do header `Accept-Language`.
+4. A `defaultLocale` configurada.
+
+```bash
+# Negociada a partir de `Accept-Language`
+curl -H "Accept-Language: fr" http://localhost:3000/
+# Bonjour
+
+# O cookie tem precedência sobre `Accept-Language`
+curl -H "Accept-Language: fr" -H "Cookie: INTLAYER_LOCALE=es" http://localhost:3000/
+# Hola
+
+# O header tem precedência sobre `Accept-Language`
+curl -H "Accept-Language: fr" -H "x-intlayer-locale: es" http://localhost:3000/
+# Hola
+```
+
+## Configuração
+
+O plugin lê o seu ficheiro `intlayer.config.ts`. Pode personalizar o cookie e o header usados para a deteção do locale:
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  routing: {
+    storage: [
+      { type: "header", name: "my-locale-header" },
+      { type: "cookie", name: "my-locale-cookie" },
+    ],
+  },
+};
+
+export default config;
+```
+
+> Para mais informações sobre a configuração, visite a [documentação de configuração](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/configuration.md).
+
+## Documentação relacionada
+
+- [Documentação do pacote elysia-intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/packages/elysia-intlayer/exports.md)
+- [Elysia i18n - Guia completo para traduzir sua aplicação](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_with_elysia.md)

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

@@ -0,0 +1,155 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: Documentação da Função getDictionary | intlayer
+description: Veja como usar a função getDictionary para o pacote intlayer
+keywords:
+  - getDictionary
+  - dictionary
+  - interpreter
+  - content
+  - Intlayer
+  - intlayer
+  - Internationalization
+  - Documentation
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - getDictionary
+history:
+  - version: 9.4.0
+    date: 2026-08-23
+    changes: "Documentação inicial"
+author: aymericzip
+---
+
+# Documentação: Função `getDictionary` em `intlayer`
+
+## Description
+
+A função `getDictionary` interpreta um objeto de dicionário **que você passa você mesmo** e retorna seu conteúdo resolvido para um local específico. Ela percorre o conteúdo em uma única passagem e aplica cada plugin de interpretador conforme necessário, resolvendo traduções `t()`, enumerações, condições, inserções, aninhamento, markdown, HTML e nós de arquivo.
+
+Diferentemente de [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/packages/intlayer/getIntlayer.md), que procura um dicionário por chave no registro gerado, `getDictionary` recebe o próprio dicionário. Isso o torna a ferramenta certa para conteúdo construído em tempo de execução, buscado de uma API ou CMS, ou declarado inline em um teste.
+
+**Principais Características:**
+
+- Funciona com qualquer objeto seguindo a estrutura de dicionário (`{ key, content }`)
+- Também aceita um grupo de dicionário qualificado (coleções, variantes) junto com um seletor
+- Totalmente tipado: o objeto retornado espelha o `content` que você passou
+- Aceita plugins de interpretador personalizados
+
+---
+
+## Function Signature
+
+```typescript
+getDictionary(
+  dictionary: Dictionary | QualifiedDictionaryGroup, // Obrigatório
+  localeOrSelector?: LocalesValues | DictionarySelector, // Opcional
+  plugins?: Plugins[]                                // Opcional
+): DeepTransformContent<...>
+```
+
+---
+
+## Parâmetros
+
+- `dictionary: Dictionary | QualifiedDictionaryGroup`
+  - **Descrição**: O dicionário (ou grupo de dicionários qualificados) a ser interpretado.
+  - **Tipo**: `Dictionary | QualifiedDictionaryGroup`
+  - **Obrigatório**: Sim
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **Descrição**: A localidade para interpretar o conteúdo, ou um objeto seletor (`{ item }`, `{ variant }`, opcionalmente com `locale`). Veja [dicionários dinâmicos](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/dynamic_dictionaries/index.md).
+  - **Tipo**: `LocalesValues | DictionarySelector`
+  - **Obrigatório**: Não (Opcional) — padrão é o `defaultLocale` configurado.
+
+- `plugins: Plugins[]`
+  - **Descrição**: Um array de transformadores de nó definindo como nós reconhecidos são interpretados. Se omitido, o conjunto padrão de plugins do interpretador é usado.
+  - **Tipo**: `Plugins[]`
+  - **Obrigatório**: Não (Opcional)
+
+### Retorna
+
+- **Tipo**: O conteúdo interpretado do dicionário.
+- **Descrição**: O `content` que você passou, com cada nó do Intlayer resolvido para a localidade solicitada. Para um grupo de coleção sem um seletor `item`, um array ordenado de entradas interpretadas é retornado; `null` é retornado quando o seletor não visa nada.
+
+---
+
+## Exemplo de Uso
+
+### Uso Básico
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getDictionary, t } from "intlayer";
+
+const content = getDictionary(
+  {
+    key: "my_key",
+    content: {
+      greeting: t({
+        pt: "Olá",
+        en: "Hello",
+        fr: "Bonjour",
+      }),
+    },
+  },
+  "pt"
+);
+
+console.log(content.greeting); // "Olá"
+```
+
+### Interpretando conteúdo obtido em tempo de execução
+
+```typescript
+import { getDictionary, type Dictionary } from "intlayer";
+
+const remoteDictionary: Dictionary = await fetch("/api/cms/banner").then(
+  (res) => res.json()
+);
+
+const banner = getDictionary(remoteDictionary, "fr");
+```
+
+### Com um seletor
+
+```typescript
+import { getDictionary } from "intlayer";
+
+// Um grupo de dicionário qualificado é resolvido para uma única entrada…
+const secondItem = getDictionary(blogPostGroup, { item: 2, locale: "fr" });
+
+// …ou para um array ordenado quando nenhum `item` é fornecido
+const allItems = getDictionary(blogPostGroup, { locale: "fr" });
+```
+
+---
+
+## Funções Relacionadas
+
+- [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/packages/intlayer/getIntlayer.md): Mesma interpretação, mas o dicionário é procurado por chave no registro gerado.
+- [`getDictionaryAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/packages/intlayer/getDictionaryAsync.md): Equivalente para mapas de loader por locale.
+- [`useDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/packages/react-intlayer/useDictionary.md): O equivalente do React hook, lendo o locale do provider.
+
+---
+
+## TypeScript
+
+```typescript
+function getDictionary<
+  const T extends Dictionary | QualifiedDictionaryGroup,
+  const A extends LocalesValues | DictionarySelector = DeclaredLocales,
+>(
+  dictionary: T,
+  localeOrSelector?: A,
+  plugins?: Plugins[]
+): DeepTransformContent<
+  ResolveQualifiedDictionaryContent<T, A>,
+  IInterpreterPluginState,
+  ExtractSelectorLocale<A>
+>;
+```

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

@@ -0,0 +1,166 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: Documentação da Função getDictionaryAsync | intlayer
+description: Veja como usar a função getDictionaryAsync para o pacote intlayer
+keywords:
+  - getDictionaryAsync
+  - dictionary
+  - dynamic dictionaries
+  - loader map
+  - bundle optimization
+  - Intlayer
+  - intlayer
+  - Internationalization
+  - Documentation
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - getDictionaryAsync
+history:
+  - version: 9.4.0
+    date: 2026-08-23
+    changes: "Initial documentation"
+author: aymericzip
+---
+
+# Documentação: Função `getDictionaryAsync` em `intlayer`
+
+## Descrição
+
+A função `getDictionaryAsync` carrega um **único chunk de locale** de um dicionário e retorna seu conteúdo interpretado.
+
+É a contrapartida de [`getDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/packages/intlayer/getDictionary.md) para os mapas de loader por locale emitidos em `.intlayer/dynamic_dictionaries/`: em vez de receber um dicionário contendo cada locale, ele recebe o mapa de loader e aguarda apenas o chunk que o locale solicitado necessita.
+
+> No código da aplicação você normalmente chama [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/packages/intlayer/getIntlayerAsync.md), não esta função. Os [plugins de build](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/bundle_optimization.md) reescrevem cada chamada `getIntlayerAsync('key', locale)` em uma `getDictionaryAsync(loaderMap, 'key', locale)`. `getDictionaryAsync` é exportado para loaders customizados e para ferramentas que constroem seus próprios mapas de loader.
+
+**Características principais:**
+
+- Carrega apenas o chunk de locale que é solicitado
+- Suporta mapas de loader simples (`locale → loader`) e qualificados (`locale → qualifierId → loader`)
+- Deduplica carregamentos simultâneos do mesmo chunk e cacheia o conteúdo resolvido
+- Carregamentos falhados são removidos do cache para que uma chamada posterior tente novamente o chunk
+
+---
+
+## Assinatura da Função
+
+```typescript
+getDictionaryAsync(
+  dictionaryLoaders: PlainDynamicLoaderMap | QualifiedDynamicLoaderMap, // Obrigatório
+  key: string,                                           // Obrigatório
+  localeOrSelector?: LocalesValues | DictionarySelector, // Opcional
+  plugins?: Plugins[]                                    // Opcional
+): Promise<DeepTransformContent<...>>
+```
+
+---
+
+## Parâmetros
+
+- `dictionaryLoaders: PlainDynamicLoaderMap | QualifiedDynamicLoaderMap`
+  - **Description**: O mapa de loader por locale. Mapas simples associam um locale com um loader; mapas qualificados (usados por coleções e variantes) associam um locale com um id de qualificador, depois com um loader. Para um mapa qualificado, apenas o(s) chunk(s) que o seletor alvo carrega(m).
+  - **Type**: `PlainDynamicLoaderMap<T> | QualifiedDynamicLoaderMap`
+  - **Required**: Sim
+
+- `key: string`
+  - **Description**: A chave do dicionário, usada para nomear o cache do chunk.
+  - **Type**: `string`
+  - **Required**: Sim
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **Description**: O locale para interpretar o conteúdo com, ou um objeto seletor (`{ item }`, `{ variant }`, opcionalmente com `locale`). Veja [dynamic dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/dynamic_dictionaries/index.md).
+  - **Type**: `LocalesValues | DictionarySelector`
+  - **Required**: Não (Opcional) — padrão para o `defaultLocale` configurado.
+
+- `plugins: Plugins[]`
+  - **Description**: Node transformers. Padrão para o conjunto de intérprete base.
+  - **Type**: `Plugins[]`
+  - **Required**: Não (Opcional)
+
+### Retorna
+
+- **Type**: `Promise<Content>` — uma promise resolvendo para o conteúdo interpretado do chunk carregado.
+- **Description**: Resolve para `null` quando o map não emite nenhum chunk para a locale solicitada nem para nenhum de seus fallbacks, espelhando como uma coordenada qualificada ausente é resolvida.
+
+---
+
+## Exemplo de Uso
+
+### Com um mapa de loader gerado
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getDictionaryAsync } from "intlayer";
+import appLoaderMap from "../.intlayer/dynamic_dictionaries/app";
+
+const { title } = await getDictionaryAsync(appLoaderMap, "app", "fr");
+```
+
+### Com um mapa de carregador personalizado
+
+```typescript
+import { getDictionaryAsync } from "intlayer";
+
+const loaderMap = {
+  en: () => import("./banner.en.json").then((mod) => mod.default),
+  fr: () => import("./banner.fr.json").then((mod) => mod.default),
+};
+
+const banner = await getDictionaryAsync(loaderMap, "banner", "fr");
+```
+
+### Com um seletor em um mapa qualificado
+
+```typescript
+import { getDictionaryAsync } from "intlayer";
+
+const promoBanner = await getDictionaryAsync(bannerLoaderMap, "banner", {
+  variant: "black-friday",
+  locale: "fr",
+});
+```
+
+---
+
+## Notas de Comportamento
+
+### Caching e deduplicação
+
+O cache armazena a **promise** de cada tripla `key + locale + selector`, então chamadas concorrentes para o mesmo chunk aguardam um único carregamento. Um carregamento rejeitado é removido do cache, então um chunk que falha é retentado na próxima chamada em vez de repetir a mesma falha para sempre.
+
+### Fallback de locale
+
+Um mapa de loader simples é percorrido ao longo da mesma cadeia de fallback que o modo síncrono: a locale solicitada primeiro, depois seus fallbacks, depois `null` se nenhum emitir um chunk.
+
+---
+
+## Funções Relacionadas
+
+- [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/packages/intlayer/getIntlayerAsync.md): A função que as aplicações chamam; os plugins de build reescrevem-na em `getDictionaryAsync`.
+- [`getDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/packages/intlayer/getDictionary.md): Equivalente síncrono que recebe um dicionário completo.
+- [Dicionários dinâmicos](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/dynamic_dictionaries/index.md): Coleções e variantes, e os mapas de loader que geram.
+
+---
+
+## TypeScript
+
+```typescript
+function getDictionaryAsync<
+  const T extends Dictionary,
+  const A extends LocalesValues | DictionarySelector = DeclaredLocales,
+>(
+  dictionaryLoaders: PlainDynamicLoaderMap<T> | QualifiedDynamicLoaderMap,
+  key: string,
+  localeOrSelector?: A,
+  plugins?: Plugins[]
+): Promise<
+  DeepTransformContent<
+    T["content"],
+    IInterpreterPluginState,
+    ExtractSelectorLocale<A>
+  >
+>;
+```

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

@@ -31,6 +31,8 @@ author: aymericzip
 
 A função `getEnumeration` recupera o conteúdo correspondente a uma quantidade específica com base em condições predefinidas em um objeto de enumeração. As condições são definidas como chaves, e sua prioridade é determinada pela ordem no objeto.
 
+Para mais detalhes sobre como declarar enumerações, consulte a [documentação de Enumeration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/dictionary/enumeration.md).
+
 ## Parâmetros
 
 - `enumerationContent: QuantityContent<Content>`