@intlayer/docs 9.4.0-canary.0 → 9.4.1

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>`

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

@@ -0,0 +1,197 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: Documentação da Função getIntlayer | intlayer
+description: Veja como usar a função getIntlayer para o pacote intlayer
+keywords:
+  - getIntlayer
+  - dictionary
+  - content
+  - selector
+  - Intlayer
+  - intlayer
+  - Internationalization
+  - Documentation
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - getIntlayer
+history:
+  - version: 9.4.0
+    date: 2026-08-23
+    changes: "Initial documentation"
+author: aymericzip
+---
+
+# Documentação: Função `getIntlayer` em `intlayer`
+
+## Descrição
+
+A função `getIntlayer` seleciona um dicionário pela sua chave e retorna seu conteúdo interpretado para uma determinada localidade. É o equivalente agnóstico de framework do hook `useIntlayer`: mesmo conteúdo, mesmos seletores, mas utilizável em qualquer lugar onde um contexto React não está disponível — scripts Node, funções de servidor, carregadores de rotas, construtores de metadados, manipuladores Express/Fastify, testes.
+
+Ela lê os dicionários gerados pelo Intlayer em `.intlayer/`, então o argumento `key` é digitado e autocompletado a partir de suas próprias declarações de conteúdo, e o objeto retornado é totalmente digitado até cada folha.
+
+**Principais Recursos:**
+
+- Chaves de dicionário digitadas e conteúdo retornado digitado
+- Interpreta cada nó de conteúdo (`t()`, `enu()`, `cond()`, `insert()`, `nest()`, `md()`, `html()`, `file()`, `gender()`)
+- Aceita uma localidade ou um objeto seletor (coleções, variantes)
+- Os resultados são memorizados por `key + locale + selector`
+- Retorna a um proxy seguro em desenvolvimento quando um dicionário está faltando, em vez de travar
+
+---
+
+## Assinatura da Função
+
+```typescript
+getIntlayer(
+  key: DictionaryKeys,                        // Obrigatório
+  localeOrSelector?: LocalesValues | DictionarySelector, // Opcional
+  plugins?: Plugins[]                         // Opcional
+): DeepTransformContent<...>
+```
+
+---
+
+## Parâmetros
+
+- `key: DictionaryKeys`
+  - **Description**: A chave do dicionário a ler, conforme declarado nos seus arquivos de conteúdo.
+  - **Type**: `DictionaryKeys` — uma união de cada chave de dicionário declarada.
+  - **Required**: Yes
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **Description**: O locale para interpretar o conteúdo, ou um objeto seletor para [dicionários dinâmicos](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/dynamic_dictionaries/index.md).
+    - `'fr'` — um locale
+    - `{ item: 2 }` — um item de [coleção](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/dynamic_dictionaries/collections.md) (omita `item` para obter cada item como um array)
+    - `{ variant: 'black-friday' }` — uma [variante](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/dynamic_dictionaries/variants.md) nomeada (omita para a variante `default`)
+    - `{ variant: { id: 'prod_abc', userId: '123' } }` — uma variante estruturada
+    - Qualquer seletor pode levar um locale: `{ item: 2, locale: 'fr' }`
+  - **Type**: `LocalesValues | DictionarySelector`
+  - **Required**: No (Optional) — padrão para o `defaultLocale` configurado.
+
+- `plugins: Plugins[]`
+  - **Description**: Transformadores de nó personalizados que substituem os plugins do interpretador base. Uso avançado apenas; omita para manter o comportamento padrão.
+  - **Type**: `Plugins[]`
+  - **Required**: No (Optional)
+
+### Retorna
+
+- **Tipo**: O conteúdo interpretado do dicionário, tipado a partir da sua declaração.
+- **Descrição**: Um objeto simples espelhando o campo `content` do seu dicionário, onde cada nó Intlayer foi resolvido para seu valor final para a locale solicitada.
+
+---
+
+## Exemplo de Uso
+
+### Uso Básico
+
+```typescript fileName="src/app.content.ts" codeFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const appContent = {
+  key: "app",
+  content: {
+    title: t({
+      pt: "Olá",
+      en: "Hello",
+      fr: "Bonjour",
+    }),
+  },
+} satisfies Dictionary;
+
+export default appContent;
+```
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getIntlayer } from "intlayer";
+
+const { title } = getIntlayer("app", "pt"); // "Olá"
+```
+
+### Sem um locale
+
+Omitir o locale interpreta o conteúdo com o `defaultLocale` declarado em sua [configuração](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/configuration.md).
+
+```typescript
+import { getIntlayer } from "intlayer";
+
+const { title } = getIntlayer("app"); // Interpretado com o locale padrão
+```
+
+### Dentro de um manipulador de servidor
+
+```typescript fileName="src/routes/greeting.ts" codeFormat="typescript"
+import { getIntlayer, getLocale } from "intlayer";
+
+export const greetingHandler = async (request: Request) => {
+  const locale = await getLocale({
+    getHeader: (name) => request.headers.get(name) ?? undefined,
+  });
+
+  const { title } = getIntlayer("app", locale);
+
+  return Response.json({ title });
+};
+```
+
+### Com um seletor (coleções e variantes)
+
+```typescript
+import { getIntlayer } from "intlayer";
+
+// Um único item da coleção
+const secondPost = getIntlayer("blog-post", { item: 2, locale: "fr" });
+
+// Cada item da coleção, como um array ordenado
+const allPosts = getIntlayer("blog-post", { locale: "fr" });
+
+// Uma variante nomeada
+const banner = getIntlayer("banner", { variant: "black-friday", locale: "fr" });
+```
+
+---
+
+## Notas de Comportamento
+
+### Armazenamento em cache
+
+Os resultados são memoizados em um cache de nível de módulo com chave `key + locale + selector`. Chamar `getIntlayer("app", "fr")` repetidamente interpreta o dicionário uma vez e retorna o mesmo objeto depois.
+
+### Dicionários faltantes
+
+Em desenvolvimento, solicitar uma chave que não possui um dicionário gerado registra um aviso uma vez e retorna um proxy de fallback seguro: ler `content.title` fornece a string `"app.title"` em vez de lançar um erro. Isso mantém uma página utilizável enquanto a declaração faltante é corrigida. Execute a compilação do Intlayer (ou o servidor de desenvolvimento) para que o dicionário seja gerado.
+
+### Tamanho do bundle
+
+`getIntlayer` lê o dicionário mesclado, que contém **todos** os locales. Em bundles de cliente, os [plugins de build](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/bundle_optimization.md) reescrevem a chamada para que apenas o conteúdo necessário seja enviado. Quando você lê conteúdo fora da renderização (metadados, loaders, funções de servidor) e deseja um único locale carregado sob demanda, use [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/packages/intlayer/getIntlayerAsync.md) em vez disso.
+
+---
+
+## Funções Relacionadas
+
+- [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/packages/intlayer/getIntlayerAsync.md): Contraparte assíncrona que carrega um único chunk de locale.
+- [`getDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/packages/intlayer/getDictionary.md): Interpreta um objeto de dicionário que você passa você mesmo, em vez de um procurado por chave.
+- [`useIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/packages/react-intlayer/useIntlayer.md): O equivalente do React hook, lendo o locale do provider.
+
+---
+
+## TypeScript
+
+```typescript
+function getIntlayer<
+  const T extends DictionaryKeys,
+  const A extends LocalesValues | DictionarySelector = DeclaredLocales,
+>(
+  key: T,
+  localeOrSelector?: A,
+  plugins?: Plugins[]
+): DeepTransformContent<
+  DictionaryRegistryResult<T, A>,
+  IInterpreterPluginState,
+  ExtractSelectorLocale<A>
+>;
+```

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

@@ -0,0 +1,141 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: getIntlayerAsync Function Documentation | intlayer
+description: Veja como usar a função getIntlayerAsync para o pacote intlayer
+keywords:
+  - getIntlayerAsync
+  - dictionary
+  - dynamic import
+  - metadata
+  - bundle optimization
+  - Intlayer
+  - intlayer
+  - Internationalization
+  - Documentation
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - getIntlayerAsync
+history:
+  - version: 9.4.0
+    date: 2026-08-23
+    changes: "Initial documentation"
+author: aymericzip
+---
+
+# Documentação: Função `getIntlayerAsync` em `intlayer`
+
+## Descrição
+
+A função `getIntlayerAsync` seleciona um dicionário pela sua chave e resolve seu conteúdo para uma localidade específica, **carregando apenas essa localidade**.
+
+É o equivalente assíncrono de [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/packages/intlayer/getIntlayer.md), destinado aos locais onde um dicionário é lido fora da renderização — construtores de rota `head` / metadados, loaders, funções de servidor.
+
+Enquanto `getIntlayer` carrega o dicionário mesclado contendo cada localidade, os [plugins de build](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/bundle_optimization.md) (`@intlayer/babel`, `@intlayer/swc`) reescrevem esta chamada em `getDictionaryAsync(loaderMap, key, locale)`, apontando para os chunks por localidade em `.intlayer/dynamic_dictionaries/`. O bundle portanto nunca carrega mais do que a localidade realmente solicitada.
+
+Sem esses plugins — uma build não otimizada — a chamada é resolvida através do registro de dicionário síncrono: o mesmo conteúdo, sem a divisão por localidade.
+
+**Principais Funcionalidades:**
+
+- As mesmas chaves digitadas, seletores e conteúdo retornado que `getIntlayer`
+- Carrega apenas o chunk da localidade solicitada em builds otimizadas
+- Chamadas simultâneas para o mesmo chunk compartilham um único carregamento
+- Seguro de usar em construtores de metadados `async`, loaders e funções de servidor
+
+---
+
+## Function Signature
+
+```typescript
+getIntlayerAsync(
+  key: DictionaryKeys,                        // Obrigatório
+  localeOrSelector?: LocalesValues | DictionarySelector, // Opcional
+  plugins?: Plugins[]                         // Opcional
+): Promise<DeepTransformContent<...>>
+```
+
+---
+
+## Parâmetros
+
+- `key: DictionaryKeys`
+  - **Description**: A chave do dicionário a ser lida, conforme declarado em seus arquivos de conteúdo.
+  - **Type**: `DictionaryKeys` — uma união de todas as chaves de dicionário declaradas.
+  - **Required**: Yes
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **Description**: A localidade para interpretar o conteúdo, ou um objeto seletor para [dicionários dinâmicos](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/dynamic_dictionaries/index.md).
+    - `'fr'` — uma localidade
+    - `{ item: 2 }` — um item de [coleção](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/dynamic_dictionaries/collections.md) (omita `item` para obter todos os itens como um array)
+    - `{ variant: 'black-friday' }` — uma [variante](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/dynamic_dictionaries/variants.md) nomeada (omita para a `default`)
+    - `{ variant: { id: 'prod_abc', userId: '123' } }` — uma variante estruturada
+    - Qualquer seletor pode carregar uma localidade: `{ item: 2, locale: 'fr' }`
+  - **Type**: `LocalesValues | DictionarySelector`
+  - **Required**: No (Optional) — defaults to the configured `defaultLocale`.
+
+- `plugins: Plugins[]`
+  - **Description**: Transformadores de nó customizados que substituem os plugins do interpretador base. Apenas para uso avançado.
+  - **Type**: `Plugins[]`
+  - **Required**: No (Optional)
+
+### Retorna
+
+- **Type**: `Promise<Content>` — uma promessa que resolve para o conteúdo interpretado do dicionário, tipado a partir da sua declaração.
+
+---
+
+## Exemplo de Uso
+
+### Uso Básico
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getIntlayerAsync } from "intlayer";
+
+const { title } = await getIntlayerAsync("app", "fr"); // "Bonjour"
+```
+
+---
+
+## `getIntlayer` vs `getIntlayerAsync`
+
+|                    | [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/packages/intlayer/getIntlayer.md) | `getIntlayerAsync`                                        |
+| ------------------ | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
+| Returns            | O conteúdo                                                                                                      | Uma promise do conteúdo                                   |
+| Dictionary loaded  | O dicionário mesclado (todos os locales)                                                                        | O chunk do locale solicitado apenas                       |
+| Best suited for    | Renderização, caminhos de código síncronos                                                                      | Metadata, loaders, funções de servidor                    |
+| Requires a plugin? | Não                                                                                                             | Não — a divisão por locale necessita dos plugins de build |
+
+Both accept the same arguments and return the same content: switching from one to the other only changes **when** and **how much** is loaded.
+
+---
+
+## Funções Relacionadas
+
+- [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/packages/intlayer/getIntlayer.md): Equivalente síncrono que lê o dicionário mesclado.
+- [`getDictionaryAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/packages/intlayer/getDictionaryAsync.md): A função de nível inferior que os plugins de build reescrevem esta chamada em.
+- [`getLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/packages/intlayer/getLocale.md): Detecta o locale de uma requisição de entrada.
+
+---
+
+## TypeScript
+
+```typescript
+function getIntlayerAsync<
+  const T extends DictionaryKeys,
+  const A extends LocalesValues | DictionarySelector = DeclaredLocales,
+>(
+  key: T,
+  localeOrSelector?: A,
+  plugins?: Plugins[]
+): Promise<
+  DeepTransformContent<
+    DictionaryRegistryResult<T, A>,
+    IInterpreterPluginState,
+    ExtractSelectorLocale<A>
+  >
+>;
+```