@intlayer/docs 8.0.0 → 8.0.1-canary.1

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

@@ -0,0 +1,50 @@
+---
+createdAt: 2026-01-30
+updatedAt: 2026-01-30
+title: Documentação do Pacote adonis-intlayer
+description: Middleware AdonisJS para Intlayer, fornecendo funções de tradução e detecção de locale.
+keywords:
+  - adonis-intlayer
+  - adonisjs
+  - middleware
+  - internacionalização
+  - i18n
+slugs:
+  - doc
+  - packages
+  - adonis-intlayer
+  - exports
+history:
+  - version: 8.0.0
+    date: 2026-01-30
+    changes: Documentação inicial
+---
+
+# Pacote adonis-intlayer
+
+O pacote `adonis-intlayer` fornece um middleware para aplicações AdonisJS para lidar com a internacionalização. Ele detecta o locale do usuário e fornece funções de tradução.
+
+## Instalação
+
+```bash
+npm install adonis-intlayer
+```
+
+## Exportações
+
+### Middleware
+
+O pacote fornece um middleware AdonisJS para lidar com a internacionalização.
+
+| Função               | Descrição                                                                                                                                                                                                                                                                               | Doc Relacionada                                                                                                |
+| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `IntlayerMiddleware` | Middleware AdonisJS que detecta o locale do usuário e preenche o contexto da solicitação com dados do Intlayer. Ele também define um namespace CLS (Async Local Storage) para acesso ao ciclo de vida da solicitação, permitindo o uso de funções globais como `t`, `getIntlayer`, etc. | [intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/packages/adonis-intlayer/intlayer.md) |
+
+### Funções
+
+| Função          | Descrição                                                                                                                                                                                                                  | Doc Relacionada                                                                                        |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `t`             | Função de tradução que recupera conteúdo para o locale atual. Funciona dentro do ciclo de vida da solicitação gerenciado pelo middleware `intlayer`. Usa CLS (Async Local Storage) para acessar o contexto da solicitação. | [translation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/dictionary/translation.md) |
+| `getIntlayer`   | Recupera um dicionário por sua chave da declaração gerada e retorna seu conteúdo para o locale especificado. Versão otimizada do `getDictionary`. Usa CLS para acessar o contexto da solicitação.                          | -                                                                                                      |
+| `getDictionary` | Processa objetos de dicionário e retorna conteúdo para o locale especificado. Processa traduções `t()`, enumerações, markdown, HTML, etc. Usa CLS para acessar o contexto da solicitação.                                  | -                                                                                                      |
+| `getLocale`     | Recupera o locale atual do contexto da solicitação usando CLS.                                                                                                                                                             | -                                                                                                      |

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

@@ -0,0 +1,54 @@
+---
+createdAt: 2026-01-30
+updatedAt: 2026-01-30
+title: Documentação do Middleware intlayer para AdonisJS | adonis-intlayer
+description: Veja como usar o middleware intlayer para o pacote adonis-intlayer
+keywords:
+  - intlayer
+  - adonisjs
+  - middleware
+  - Intlayer
+  - Internacionalização
+  - Documentação
+slugs:
+  - doc
+  - packages
+  - adonis-intlayer
+  - intlayer
+history:
+  - version: 8.0.0
+    date: 2026-01-30
+    changes: Documentação inicial
+---
+
+# Documentação do Middleware intlayer para AdonisJS
+
+O middleware `intlayer` para AdonisJS detecta o locale do usuário e fornece funções de tradução por meio do contexto da solicitação. Ele também permite o uso de funções de tradução globais dentro do fluxo da solicitação.
+
+## Uso
+
+```ts fileName="start/kernel.ts"
+router.use([() => import("adonis-intlayer/middleware")]);
+```
+
+```ts fileName="start/routes.ts"
+import router from "@adonisjs/core/services/router";
+import { t } from "adonis-intlayer";
+
+router.get("/", async () => {
+  return t({
+    en: "Hello",
+    fr: "Bonjour",
+  });
+});
+```
+
+## Descrição
+
+O middleware realiza as seguintes tarefas:
+
+1. **Detecção de Locale**: Ele analisa a solicitação (cabeçalhos, cookies, etc.) para determinar o locale de preferência do usuário.
+2. **Configuração de Contexto**: Ele preenche o contexto da solicitação com informações de locale.
+3. **Async Local Storage**: Ele usa `cls-hooked` para gerenciar um contexto assíncrono, permitindo que funções globais do Intlayer como `t`, `getIntlayer` e `getDictionary` acessem o locale específico da solicitação sem passá-lo manualmente.
+
+> Nota: Para usar cookies para detecção de locale, certifique-se de que `@adonisjs/cookie` esteja configurado e sendo usado em sua aplicação.

package/docs/pt/packages/adonis-intlayer/t.md

@@ -0,0 +1,149 @@
+---
+createdAt: 2026-01-30
+updatedAt: 2026-01-30
+title: Documentação da Função t | adonis-intlayer
+description: Veja como usar a função t para o pacote adonis-intlayer
+keywords:
+  - t
+  - tradução
+  - Intlayer
+  - Internacionalização
+  - Documentação
+  - AdonisJS
+  - JavaScript
+slugs:
+  - doc
+  - packages
+  - adonis-intlayer
+  - t
+history:
+  - version: 8.0.0
+    date: 2026-01-30
+    changes: Documentação inicial
+---
+
+# Documentação: Função `t` no `adonis-intlayer`
+
+A função `t` no pacote `adonis-intlayer` é o utilitário principal para fornecer respostas localizadas em sua aplicação AdonisJS. Ela simplifica a internacionalização (i18n) selecionando dinamicamente o conteúdo com base no idioma de preferência do usuário.
+
+---
+
+## Visão Geral
+
+A função `t` é usada para definir e recuperar traduções para um determinado conjunto de idiomas. Ela determina automaticamente o idioma apropriado a ser retornado com base nas configurações de solicitação do cliente, como o cabeçalho `Accept-Language`. Se o idioma preferido não estiver disponível, ela recorre graciosamente ao locale padrão especificado em sua configuração.
+
+---
+
+## Principais Recursos
+
+- **Localização Dinâmica**: Seleciona automaticamente a tradução mais apropriada para o cliente.
+- **Fallback para o Locale Padrão**: Recorre a um locale padrão se o idioma preferido do cliente não estiver disponível, garantindo a continuidade na experiência do usuário.
+- **Contexto Assíncrono**: Funciona perfeitamente dentro do ciclo de vida da solicitação AdonisJS usando Async Local Storage.
+- **Suporte ao TypeScript**: Garante a segurança de tipos para suas traduções.
+
+---
+
+## Assinatura da Função
+
+```typescript
+t(translations: Record<string, any>): any;
+```
+
+### Parâmetros
+
+- `translations`: Um objeto onde as chaves são códigos de locale (ex: `en`, `fr`, `es`) e os valores são o conteúdo traduzido correspondente.
+
+### Retornos
+
+- O conteúdo que representa o idioma preferido do cliente.
+
+---
+
+## Carregando o Middleware
+
+Para garantir que a função `t` funcione corretamente, você **deve** registrar o middleware `intlayer` em sua aplicação AdonisJS.
+
+```typescript fileName="start/kernel.ts"
+router.use([() => import("adonis-intlayer/middleware")]);
+```
+
+---
+
+## Exemplos de Uso
+
+### Exemplo Básico
+
+```typescript fileName="start/routes.ts"
+import router from "@adonisjs/core/services/router";
+import { t } from "adonis-intlayer";
+
+router.get("/", async () => {
+  return t({
+    en: "Welcome!",
+    fr: "Bienvenue!",
+    es: "¡Bienvenido!",
+  });
+});
+```
+
+### Uso em Controllers
+
+```typescript fileName="app/controllers/example_controller.ts"
+import type { HttpContext } from "@adonisjs/core/http";
+import { t } from "adonis-intlayer";
+
+export default class ExampleController {
+  async index({ response }: HttpContext) {
+    return response.send(
+      t({
+        en: "Hello from controller",
+        fr: "Bonjour desde o controlador",
+      })
+    );
+  }
+}
+```
+
+---
+
+## Tópicos Avançados
+
+### Mecanismo de Fallback
+
+Se um locale preferido não estiver disponível, a função `t` recorrerá ao locale padrão definido em seu `intlayer.config.ts`.
+
+```typescript
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.RUSSIAN,
+      Locales.JAPANESE,
+      Locales.FRENCH,
+      Locales.KOREAN,
+      Locales.CHINESE,
+      Locales.SPANISH,
+      Locales.GERMAN,
+      Locales.ARABIC,
+      Locales.ITALIAN,
+      Locales.ENGLISH_UNITED_KINGDOM,
+      Locales.PORTUGUESE,
+      Locales.HINDI,
+      Locales.TURKISH,
+      Locales.POLISH,
+      Locales.INDONESIAN,
+      Locales.VIETNAMESE,
+      Locales.UKRAINIAN,
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+### Integração com TypeScript
+
+A função `t` é segura em termos de tipo quando usada com dicionários definidos. Para mais detalhes, consulte a [documentação do TypeScript](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/configuration.md).

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

@@ -0,0 +1,59 @@
+---
+createdAt: 2026-01-29
+updatedAt: 2026-01-29
+title: Documentação do Pacote hono-intlayer
+description: Middleware Hono para Intlayer, fornecendo funções de tradução e detecção de localidade.
+keywords:
+  - hono-intlayer
+  - hono
+  - middleware
+  - internacionalização
+  - i18n
+slugs:
+  - doc
+  - packages
+  - hono-intlayer
+  - exports
+history:
+  - version: 8.0.0
+    date: 2026-01-29
+    changes: Documentação unificada para todas as exportações
+---
+
+# Pacote hono-intlayer
+
+O pacote `hono-intlayer` fornece um middleware para aplicações Hono para lidar com a internacionalização. Ele detecta a localidade do usuário e preenche o objeto de contexto.
+
+## Instalação
+
+```bash
+npm install hono-intlayer
+```
+
+## Exportações
+
+### Middleware
+
+Importar:
+
+```tsx
+import { intlayer } from "hono-intlayer";
+```
+
+| Função     | Descrição                                                                                                                                                                                                                                                                                                  | Doc Relacionada                                                                                              |
+| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `intlayer` | Middleware Hono que integra o Intlayer na sua aplicação Hono. Lida com a detecção de localidade a partir do armazenamento (cookies, cabeçalhos), preenche o contexto com `t`, `getIntlayer` e `getDictionary` e configura o namespace CLS para acesso programático durante o ciclo de vida da solicitação. | [intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/packages/hono-intlayer/intlayer.md) |
+
+### Funções
+
+Importar:
+
+```tsx
+import { t, getIntlayer, getDictionary } from "hono-intlayer";
+```
+
+| Função          | Descrição                                                                                                                                                                                                                                              | Doc Relacionada                                                                                     |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
+| `t`             | Função de tradução global que recupera conteúdo para a localidade atual no Hono. Utiliza CLS (Async Local Storage) e deve ser usada dentro de um contexto de solicitação gerenciado pelo middleware `intlayer`. Também pode ser acessada via contexto. | [tradução](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/dictionary/translation.md) |
+| `getIntlayer`   | Recupera um dicionário por sua chave da declaração gerada e retorna seu conteúdo para a localidade especificada. Versão otimizada do `getDictionary`. Usa CLS para acessar o contexto da solicitação. Também pode ser acessada via contexto.           | -                                                                                                   |
+| `getDictionary` | Processa objetos de dicionário e retorna o conteúdo para a localidade especificada. Processa traduções `t()`, enumerações, markdown, HTML, etc. Usa CLS para acessar o contexto da solicitação. Também pode ser acessada via contexto.                 | -                                                                                                   |

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

@@ -0,0 +1,60 @@
+---
+createdAt: 2026-01-29
+updatedAt: 2026-01-29
+title: Documentação do Middleware Hono intlayer | hono-intlayer
+description: Veja como usar o middleware intlayer para o pacote hono-intlayer
+keywords:
+  - intlayer
+  - hono
+  - middleware
+  - Intlayer
+  - Internacionalização
+  - Documentação
+slugs:
+  - doc
+  - packages
+  - hono-intlayer
+  - intlayer
+history:
+  - version: 8.0.0
+    date: 2026-01-29
+    changes: Inicialização da doc
+---
+
+# Documentação do Middleware Hono intlayer
+
+O middleware `intlayer` para Hono detecta a localidade do usuário e preenche o objeto de contexto com funções Intlayer. Ele também permite o uso de funções de tradução globais dentro do contexto da solicitação.
+
+## Uso
+
+```ts
+import { Hono } from "hono";
+import { intlayer } from "hono-intlayer";
+
+const app = new Hono();
+
+app.use("*", intlayer());
+
+app.get("/", async (c) => {
+  const t = c.get("t");
+  const content = t({
+    en: "Hello",
+    fr: "Bonjour",
+    pt: "Olá",
+  });
+
+  return c.text(content);
+});
+```
+
+## Descrição
+
+O middleware executa as seguintes tarefas:
+
+1. **Detecção de Localidade**: Analisa a solicitação (cabeçalhos, cookies, etc.) para determinar a localidade preferida do usuário.
+2. **Preenchimento do Contexto**: Adiciona dados do Intlayer ao contexto Hono, acessíveis via `c.get()`. Isso inclui:
+   - `locale`: A localidade detectada.
+   - `t`: Uma função de tradução.
+   - `getIntlayer`: Uma função para recuperar dicionários.
+   - `getDictionary`: Uma função para processar objetos de dicionário.
+3. **Gerenciamento de Contexto**: Usa `cls-hooked` para gerenciar um contexto assíncrono, permitindo que as funções globais do Intlayer (`t`, `getIntlayer`, `getDictionary`) acessem a localidade específica da solicitação sem passar o objeto de contexto.

package/docs/pt/packages/hono-intlayer/t.md

@@ -0,0 +1,268 @@
+---
+createdAt: 2024-12-02
+updatedAt: 2025-06-29
+title: Documentação da Função t | hono-intlayer
+description: Veja como usar a função t para o pacote hono-intlayer
+keywords:
+  - t
+  - tradução
+  - Intlayer
+  - Internacionalização
+  - Documentação
+  - Hono
+  - JavaScript
+slugs:
+  - doc
+  - packages
+  - hono-intlayer
+  - t
+history:
+  - version: 5.5.10
+    date: 2025-06-29
+    changes: Inicialização do histórico
+---
+
+# Documentação: Função `t` no `hono-intlayer`
+
+A função `t` no pacote `hono-intlayer` é o utilitário principal para fornecer respostas localizadas na sua aplicação Hono. Ela simplifica a internacionalização (i18n) selecionando dinamicamente o conteúdo com base no idioma de preferência do usuário.
+
+---
+
+## Visão Geral
+
+A função `t` é usada para definir e recuperar traduções para um determinado conjunto de idiomas. Ela determina automaticamente o idioma apropriado a ser retornado com base nas configurações de solicitação do cliente, como o cabeçalho `Accept-Language`. Se o idioma preferido não estiver disponível, ela recorre graciosamente ao local padrão especificado na sua configuração.
+
+---
+
+## Principais Recursos
+
+- **Localização Dinâmica**: Seleciona automaticamente a tradução mais apropriada para o cliente.
+- **Fallback para o Local Padrão**: Recorre a um local padrão se o idioma preferido do cliente não estiver disponível, garantindo continuidade na experiência do usuário.
+- **Leve e Rápido**: Projetado para aplicações de alto desempenho, garantindo uma sobrecarga mínima.
+- **Suporte ao Modo Estrito**: Reforça a adesão estrita aos locais declarados para um comportamento confiável.
+
+---
+
+## Assinatura da Função
+
+```typescript
+t(translations: Record<string, string>): string;
+```
+
+### Parâmetros
+
+- `translations`: Um objeto onde as chaves são códigos de localidade (ex: `en`, `fr`, `pt`) e os valores são as strings traduzidas correspondentes.
+
+### Retorno
+
+- Uma string representando o conteúdo no idioma de preferência do cliente.
+
+---
+
+## Carregando o Manipulador de Solicitação de Internacionalização
+
+Para garantir que a funcionalidade de internacionalização fornecida pelo `hono-intlayer` funcione corretamente, você **deve** carregar o middleware de internacionalização no início da sua aplicação Hono. Isso habilita a função `t` e garante o tratamento adequado da detecção de localidade e tradução.
+
+Coloque o middleware `app.use("*", intlayer())` **antes de quaisquer rotas** na sua aplicação para garantir que todas as rotas se beneficiem da internacionalização:
+
+```typescript {6} fileName="src/index.ts" codeFormat="typescript"
+import { Hono } from "hono";
+import { intlayer } from "hono-intlayer";
+
+const app = new Hono();
+
+// Carregar manipulador de solicitação de internacionalização
+app.use("*", intlayer());
+
+// Defina suas rotas após carregar o middleware
+app.get("/", (c) => {
+  return c.text(
+    t({
+      en: "Hello, World!",
+      fr: "Bonjour le monde!",
+      es: "¡Hola, Mundo!",
+      pt: "Olá, Mundo!",
+    })
+  );
+});
+```
+
+```javascript {6} fileName="src/index.mjs" codeFormat="esm"
+import { Hono } from "hono";
+import { intlayer } from "hono-intlayer";
+
+const app = new Hono();
+
+// Carregar manipulador de solicitação de internacionalização
+app.use("*", intlayer());
+
+// Defina suas rotas após carregar o middleware
+app.get("/", (c) => {
+  return c.text(
+    t({
+      en: "Hello, World!",
+      fr: "Bonjour le monde!",
+      es: "¡Hola, Mundo!",
+      pt: "Olá, Mundo!",
+    })
+  );
+});
+```
+
+```javascript {6} fileName="src/index.cjs" codeFormat="commonjs"
+const { Hono } = require("hono");
+const { intlayer, t } = require("hono-intlayer");
+
+const app = new Hono();
+
+// Carregar manipulador de solicitação de internacionalização
+app.use("*", intlayer());
+
+// Defina suas rotas após carregar o middleware
+app.get("/", (c) => {
+  return c.text(
+    t({
+      en: "Hello, World!",
+      fr: "Bonjour le monde!",
+      es: "¡Hola, Mundo!",
+      pt: "Olá, Mundo!",
+    })
+  );
+});
+```
+
+### Por que isso é Obrigatório
+
+- **Detecção de Localidade**: O middleware `intlayer` processa as solicitações recebidas para detectar a localidade preferida do usuário com base em cabeçalhos, cookies ou outros métodos configurados.
+- **Contexto de Tradução**: Configura o contexto necessário para que a função `t` opere corretamente, garantindo que as traduções sejam retornadas no idioma correto.
+- **Prevenção de Erros**: Sem este middleware, o uso da função `t` resultará em erros de tempo de execução porque as informações de localidade necessárias não estarão disponíveis.
+
+---
+
+## Exemplos de Uso
+
+### Exemplo Básico
+
+Sirva conteúdo localizado em diferentes idiomas:
+
+```typescript fileName="src/index.ts" codeFormat="typescript"
+app.get("/", (c) => {
+  return c.text(
+    t({
+      en: "Welcome!",
+      fr: "Bienvenue!",
+      pt: "Bem-vindo!",
+    })
+  );
+});
+```
+
+**Solicitações do Cliente:**
+
+- Um cliente com `Accept-Language: fr` receberá `Bienvenue!`.
+- Um cliente com `Accept-Language: pt` receberá `Bem-vindo!`.
+- Um cliente com `Accept-Language: de` receberá `Welcome!` (localidade padrão).
+
+### Tratamento de Erros
+
+Forneça mensagens de erro em vários idiomas:
+
+```typescript fileName="src/index.ts" codeFormat="typescript"
+app.get("/error", (c) => {
+  return c.text(
+    t({
+      en: "An unexpected error occurred.",
+      fr: "Une erreur inattendue s'est produite.",
+      pt: "Ocorreu um erro inesperado.",
+    }),
+    500
+  );
+});
+```
+
+---
+
+### Usando Variantes de Localidade
+
+Especifique traduções para variantes específicas de localidade:
+
+```typescript fileName="src/index.ts" codeFormat="typescript"
+app.get("/greet", (c) => {
+  return c.text(
+    t({
+      en: "Hello!",
+      "en-GB": "Hello, mate!",
+      fr: "Bonjour!",
+      pt: "Olá!",
+    })
+  );
+});
+```
+
+---
+
+## Tópicos Avançados
+
+### Mecanismo de Fallback
+
+Se uma localidade preferida estiver indisponível, a função `t` recorrerá à localidade padrão definida na configuração:
+
+```typescript {5-6} fileName="intlayer.config.ts" codeFormat="typescript"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.PORTUGUESE],
+    defaultLocale: Locales.ENGLISH,
+  },
+} satisfies IntlayerConfig;
+
+export default config;
+```
+
+---
+
+### Execução do Modo Estrito
+
+Configure a função `t` para reforçar a adesão estrita aos locais declarados:
+
+| Modo        | Comportamento                                                                              |
+| ----------- | ------------------------------------------------------------------------------------------ |
+| `strict`    | Todos os locais declarados devem ter traduções fornecidas. Locais ausentes lançarão erros. |
+| `inclusive` | Locais declarados devem ter traduções. Locais ausentes acionam avisos, mas são aceitos.    |
+| `loose`     | Qualquer local existente é aceito, mesmo que não seja declarado.                           |
+
+---
+
+### Integração com TypeScript
+
+A função `t` é type-safe quando usada com TypeScript. Defina um objeto de traduções type-safe:
+
+```typescript fileName="src/index.ts" codeFormat="typescript"
+import { type LanguageContent } from "hono-intlayer";
+
+const translations: LanguageContent<string> = {
+  en: "Good morning!",
+  fr: "Bonjour!",
+  pt: "Bom dia!",
+};
+
+app.get("/morning", (c) => {
+  return c.text(t(translations));
+});
+```
+
+---
+
+### Erros Comuns e Solução de Problemas
+
+| Problema                   | Causa                                    | Solução                                                                          |
+| -------------------------- | ---------------------------------------- | -------------------------------------------------------------------------------- |
+| Função `t` não funciona    | Middleware não carregado                 | Certifique-se de que `app.use("*", intlayer())` seja adicionado antes das rotas. |
+| Erro de traduções ausentes | Modo estrito ativado sem todos os locais | Forneça todas as traduções necessárias.                                          |
+
+---
+
+## Conclusão
+
+A função `t` é uma ferramenta poderosa para a internacionalização de back-end. Ao usá-la de forma eficaz, você pode criar uma aplicação mais inclusiva e amigável para um público global. Para uso avançado e opções de configuração detalhadas, consulte a [documentação](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md).