@intlayer/docs 5.5.10 → 5.5.12

package/frequent_questions/pt/build_error_CI_CD.md

@@ -0,0 +1,75 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Erro de Build em CI/CD
+description: Aprenda como corrigir erros de build que ocorrem em ambientes CI/CD.
+keywords:
+  - build
+  - erro
+  - ci
+  - cd
+  - pipeline
+  - intlayer
+  - dicionários
+  - next.js
+  - prebuild
+  - automação
+slugs:
+  - doc
+  - faq
+  - erro-build-ci-cd
+---
+
+# Erro no build em CI/CD
+
+Se você receber um erro como este no Next.js:
+
+```text
+Error: An error occurred in the Server Components render. The specific message is omitted in production builds to avoid leaking sensitive details. A digest property is included on this error instance which may provide additional details about the nature of the error
+```
+
+Aqui estão algumas soluções:
+
+## 1. Dicionários ausentes
+
+Certifique-se de que os dicionários sejam construídos na etapa de build.
+
+É frequente que o build funcione localmente, mas não no CI/CD. A razão é que localmente o diretório `.intlayer` está presente, mas no CI/CD não está, pois é excluído do build.
+
+Você pode corrigir isso adicionando um script de prebuild no `package.json` do seu projeto.
+
+```json5 fileName=package.json
+{
+  // ...
+  "scripts": {
+    "prebuild": "npx intlayer dictionaries build", // Será executado antes do build
+    "build": "next build",
+  },
+}
+```
+
+> Note que se você usar a função `withIntlayer`, ou o plugin bundler equivalente para seu framework, o script de prebuild será executado antes do build.
+
+## 2. Variáveis de ambiente ausentes no momento do build / execução
+
+Em um container, ou plataforma de implantação automática, é recomendado excluir o arquivo `.env` do build.
+
+```text fileName=".gitignore or .dockerignore"
+# Variáveis de ambiente
+.env
+**/.env
+.env.*
+**/.env.*
+```
+
+Se suas variáveis de ambiente não estiverem disponíveis no momento do build, um erro será lançado.
+
+```ts
+import { Metadata } from "next";
+
+export const generateMetadata = async ({ params }): Promise<Metadata> => ({
+  metadataBase: new URL(process.env.NEXT_PUBLIC_URL),
+});
+```
+
+Provavelmente não está relacionado ao Intlayer. Então, verifique suas variáveis de ambiente no momento do build na sua plataforma CI/CD.

package/frequent_questions/pt/customized_locale_list.md

@@ -0,0 +1,65 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Como personalizar a lista de idiomas?
+description: Aprenda como personalizar a lista de idiomas.
+keywords:
+  - idiomas
+  - lista
+  - intlayer
+  - configuração
+  - availableLocales
+  - defaultLocale
+  - useLocale
+  - hook
+  - idioma
+  - lista
+slugs:
+  - doc
+  - faq
+  - lista-de-idiomas-personalizada
+---
+
+# É possível bloquear um tipo de idioma, como o inglês? Estou adicionando inglês nos meus dicionários, mas ainda não quero que o inglês esteja disponível no site
+
+Sim, você pode bloquear um tipo de idioma, como o inglês, usando a opção `availableLocales` na configuração do Intlayer.
+
+```ts
+import { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  locales: [Locales.FRENCH, Locales.SPANISH, Locales.ENGLISH],
+  availableLocales: [Locales.FRENCH, Locales.SPANISH],
+  defaultLocale: Locales.FRENCH,
+};
+```
+
+ou
+
+```ts
+import { IntlayerConfig } from "intlayer";
+
+const locales = [Locales.FRENCH, Locales.SPANISH, Locales.ENGLISH];
+
+const config: IntlayerConfig = {
+  locales,
+  availableLocales: locales.filter((locale) => locale !== Locales.ENGLISH),
+  defaultLocale: Locales.FRENCH,
+};
+```
+
+Esta configuração irá alterar os tipos da sua função `t()` para incluir apenas os idiomas disponíveis.
+
+A opção availableLocales é opcional, se você não a fornecer, todos os idiomas estarão disponíveis.
+
+Tenha cuidado, todos os idiomas incluídos na opção `availableLocales` devem estar incluídos na opção `locales`.
+
+Note que se você usar o hook `useLocale`, a opção `availableLocales` será usada para definir o acesso à lista de idiomas.
+
+```ts
+import { useLocale } from "intlayer";
+
+const { availableLocales } = useLocale();
+
+console.log(availableLocales); // [Locales.FRENCH, Locales.SPANISH]
+```

package/frequent_questions/pt/domain_routing.md

@@ -0,0 +1,114 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Como configurar roteamento baseado em domínio?
+description: Aprenda como configurar roteamento baseado em domínio.
+keywords:
+  - domínio
+  - roteamento
+  - intlayer
+  - configuração
+  - middleware
+  - react-router
+  - vue-router
+  - next.js
+  - vite
+  - framework
+slugs:
+  - doc
+  - faq
+  - roteamento-por-dominio
+---
+
+# Como configurar **roteamento baseado em domínio** com Intlayer em vez de caminhos `/[locale]/`?
+
+## Resposta rápida
+
+O roteamento baseado em domínio é mais simples do que o roteamento baseado em caminho (`example.com/[locale]/`) porque você pode pular toda a configuração de middleware e roteamento. Basta implantar seu app em cada domínio de idioma e definir uma variável de ambiente por domínio.
+
+## Passo a passo
+
+1. **Implante uma vez por domínio** (`example.com`, `exemple.fr`, `ejemplo.es`, …).
+2. Para cada implantação, defina `LOCALE` (e as variáveis de ambiente usuais do Intlayer) para o idioma que aquele domínio deve servir.
+3. Referencie essa variável como `defaultLocale` no seu `intlayer.config.[ts|js]`.
+
+```ts
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: process.env.LOCALE, // 👈 o domínio decide o idioma
+  },
+  // ... resto da sua configuração
+};
+
+export default config;
+```
+
+É só isso — funciona da mesma forma para **Next.js**, **Vite + React**, **Vite + Vue**, etc.
+
+## E se todos os domínios acessarem a **mesma** implantação?
+
+Se todos os domínios apontarem para o mesmo pacote de aplicação, você precisará detectar o host em tempo de execução e passar o idioma manualmente através do provedor.
+
+### Para Next.js
+
+```tsx
+// src/IntlayerProvider.tsx
+import {
+  IntlayerClientProvider,
+  type IntlayerClientProviderProps,
+} from "next-intlayer";
+import { IntlayerServerProvider } from "next-intlayer/server";
+import type { FC } from "react";
+
+export const IntlayerProvider: FC<IntlayerClientProviderProps> = ({
+  children,
+  locale,
+}) => {
+  const resolvedLocale = locale ?? getLocaleFromHostname();
+  return (
+    <IntlayerServerProvider locale={resolvedLocale}>
+      <IntlayerClientProvider locale={resolvedLocale}>
+        {children}
+      </IntlayerClientProvider>
+    </IntlayerServerProvider>
+  );
+};
+```
+
+### Para Vue
+
+```ts
+import { createApp } from "vue";
+import { installIntlayer } from "vue-intlayer";
+import App from "./App.vue";
+import { router } from "./routes";
+
+const app = createApp(App);
+app.use(router);
+installIntlayer(app, getLocaleFromHostname());
+app.mount("#app");
+```
+
+Substitua `getLocaleFromHostname()` pela sua própria lógica de busca.
+
+## Atualize seu seletor de idioma
+
+Ao usar roteamento baseado em domínio, mudar de idioma significa navegar para outro domínio:
+
+```ts
+const { locale } = useLocale();
+
+function changeLanguage(target: Locale) {
+  window.location.href = domainForLocale[target];
+}
+```
+
+## Benefícios do roteamento baseado em domínio
+
+1. **Configuração mais simples**: Não é necessário configurar `intlayerMiddleware`, `generateStaticParams`, `react-router` ou `vue-router`
+2. **Melhor SEO**: Cada idioma possui seu próprio domínio
+3. **URLs mais limpas**: Sem prefixo de localidade no caminho
+4. **Manutenção mais fácil**: Cada implantação de idioma é independente

package/frequent_questions/pt/esbuild_error.md

@@ -0,0 +1,30 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Erro ESBuild
+description: Aprenda como corrigir erros do ESBuild.
+keywords:
+  - esbuild
+  - erro
+  - intlayer
+  - plugin
+  - framework
+  - next.js
+  - vite
+  - react-native
+  - lynx
+slugs:
+  - doc
+  - faq
+  - erro-esbuild
+---
+
+# Erro ESBuild
+
+Se você encontrar um erro do ESBuild durante o processo de build, é provável que o plugin Intlayer não tenha sido configurado corretamente.
+
+O ESBuild é responsável por ler os arquivos de declaração de conteúdo (`.content.{ts,js,mjs,cjs,json}`) e gerar os dicionários correspondentes na pasta `.intlayer/dictionary`. Além disso, ele lê o arquivo de configuração (`intlayer.config.ts`).
+
+O Intlayer fornece plugins para integrar com seus bundlers. Ele é projetado para criar aliases de componentes que devem ser executados apenas no lado do servidor.
+
+Se você estiver usando um framework como Next.js (Webpack / Turbopack), Vite, React Native, Lynx, etc., o Intlayer oferece um plugin que você pode usar para integrar o Intlayer em sua aplicação. Portanto, consulte a documentação específica do seu framework para aprender como integrar o plugin.

package/frequent_questions/pt/get_locale_cookie.md

@@ -0,0 +1,143 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Como recuperar a localidade dos cookies / cabeçalhos?
+description: Aprenda como recuperar a localidade dos cookies / cabeçalhos.
+keywords:
+  - cookie
+  - cabeçalhos
+  - intlayer
+  - localidade
+  - hook
+  - useLocale
+  - useLocaleCookie
+  - next.js
+  - react-intlayer
+  - vue-intlayer
+slugs:
+  - doc
+  - faq
+  - get-locale-cookie
+---
+
+# Como recuperar a localidade dos cookies / cabeçalhos
+
+## Usando Hooks (Recomendado)
+
+Para a maioria dos casos de uso, é recomendado recuperar a localidade atual usando o hook `useLocale` porque ele é resolvido automaticamente. Isso funciona de forma semelhante ao composable `useLocale` no Vue.js.
+
+```ts
+import { useLocale } from "next-intlayer";
+// or import { useLocale } from "react-intlayer";
+// or import { useLocale } from "vue-intlayer";
+
+// Uso no lado do cliente
+const { locale } = useLocale();
+```
+
+Para componentes no servidor, você pode importá-lo de:
+
+```tsx
+import { useLocale } from "next-intlayer/server";
+
+const Test = () => {
+  const { locale } = useLocale();
+  return <>{locale}</>;
+};
+
+const Page = async ({ params }) => {
+  const { locale } = await params;
+
+  return (
+    <IntlayerServerProvider locale={locale}>
+      <Test />
+    </IntlayerServerProvider>
+  );
+};
+```
+
+Também existe um hook `useLocaleCookie` que resolve apenas o valor do cookie.
+
+## Configuração Manual do Cookie
+
+Você pode declarar um nome personalizado para o cookie como
+
+```ts
+import { type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  middleware: {
+    cookieName: "myCustomLocaleCookie", // o padrão é 'intlayer-locale'
+  },
+};
+
+export default config;
+```
+
+// recuperá-lo como
+
+### Lado do cliente
+
+```ts
+// Usando o nome padrão do cookie
+const locale = document.cookie
+  .split("; ")
+  .find((row) => row.startsWith("intlayer-locale="))
+  ?.split("=")[1];
+
+// Usando nome personalizado do cookie
+const locale = document.cookie
+  .split("; ")
+  .find((row) => row.startsWith("myCustomLocaleCookie="))
+  ?.split("=")[1];
+```
+
+### Lado do servidor (Next.js)
+
+```ts
+import { cookies } from "next/headers";
+
+// Usando o nome padrão do cookie
+const locale = cookies().get("intlayer-locale")?.value;
+
+// Usando nome personalizado do cookie
+const locale = cookies().get("myCustomLocaleCookie")?.value;
+```
+
+### Se a localidade ainda não estiver definida
+
+A localidade é definida como um cookie somente quando o usuário seleciona explicitamente a localidade. Por padrão, para novos visitantes, a localidade é interpretada a partir dos campos dos cabeçalhos.
+
+Você pode detectar a localidade preferida do usuário a partir dos cabeçalhos da requisição. Aqui está um exemplo de como lidar com isso:
+
+```ts
+/**
+ * Detecta a localidade a partir dos cabeçalhos da requisição
+ *
+ * O cabeçalho accept-language é o mais importante para a detecção da localidade.
+ * Ele contém uma lista de códigos de idioma com valores de qualidade (q-values) que indicam
+ * as línguas preferidas do usuário em ordem de preferência.
+ *
+ * Exemplo: "en-US,en;q=0.9,fr;q=0.8,es;q=0.7"
+ * - en-US é o idioma principal (q=1.0 é implícito)
+ * - en é a segunda escolha (q=0.9)
+ * - fr é a terceira escolha (q=0.8)
+ * - es é a quarta escolha (q=0.7)
+ */
+import { localeDetector } from "@intlayer/core";
+
+/**
+ * Exemplo de cabeçalhos negociadores que os navegadores normalmente enviam
+ * Esses cabeçalhos ajudam a determinar o idioma preferido do usuário
+ */
+const exampleNegotiatorHeaders: Record<string, string> = {
+  "accept-language": "en-US,en;q=0.9,fr;q=0.8,es;q=0.7",
+  "accept":
+    "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
+  "user-agent":
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
+};
+
+// Exemplo de uso:
+const detectedLocale = localeDetector(exampleNegotiatorHeaders);
+```

package/frequent_questions/pt/intlayer_command_undefined.md

@@ -0,0 +1,157 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Comando Intlayer indefinido
+description: Aprenda como corrigir o erro de comando intlayer indefinido.
+keywords:
+  - intlayer
+  - comando
+  - indefinido
+  - erro
+  - vscode
+  - extensão
+  - plugin
+  - framework
+  - next.js
+  - vite
+slugs:
+  - doc
+  - faq
+  - comando-intlayer-indefinido
+---
+
+# Comando Intlayer indefinido
+
+## Visão geral
+
+A CLI do Intlayer oferece uma maneira conveniente de controlar seu conteúdo intlayer, incluindo a construção de dicionários, envio de traduções e mais. No entanto, ela não é essencial para o funcionamento do seu projeto. Se você estiver usando o plugin bundler (como `withIntlayer()` para Next.js ou `intlayerPlugin()` para Vite), o Intlayer construirá automaticamente os dicionários durante a compilação do app ou na inicialização do servidor de desenvolvimento. No modo de desenvolvimento, ele também observará as mudanças e reconstruirá automaticamente os arquivos de declaração de conteúdo.
+
+Você pode acessar os comandos do intlayer de diferentes maneiras:
+
+- Usando o comando CLI `intlayer` diretamente
+- Usando a [extensão VSCode](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/vs_code_extension.md)
+- Usando o SDK `@intlayer/cli`
+
+## Problema
+
+Ao tentar usar o comando `intlayer`, você pode encontrar este erro:
+
+```bash
+'intlayer' não é reconhecido como um comando interno ou externo,
+programa operável ou arquivo em lote.
+```
+
+## Soluções
+
+Tente estas soluções na ordem:
+
+1. **Verifique se o comando está instalado**
+
+```bash
+npx intlayer -h
+```
+
+Saída esperada:
+
+```bash
+Usage: intlayer [options] [command]
+
+Intlayer CLI
+
+Options:
+    -V, --version            output the version number
+    -h, --help               display help for command
+
+Commands:
+    dictionary|dictionaries  Dictionaries operations
+    configuration|config     Configuration operations
+    help [command]           display help for command
+```
+
+2. **Instale o pacote intlayer-cli globalmente**
+
+```bash
+npm install intlayer-cli -g -g
+```
+
+> Não deve ser necessário se você já instalou o pacote `intlayer`
+
+3. **Instale o pacote globalmente**
+
+```bash
+npm install intlayer -g
+```
+
+4. **Reinicie seu terminal**
+   Às vezes, é necessário reiniciar o terminal para reconhecer novos comandos.
+
+5. **Limpe e reinstale**
+   Se as soluções acima não funcionarem:
+
+```bash
+rm -rf node_modules package-lock.json
+npm install
+```
+
+6. **Verifique os arquivos de instalação**
+   Se o problema persistir, verifique se estes arquivos existem:
+
+   - `node_modules/intlayer/dist/cjs/cli.cjs`
+   - `node_modules/intlayer/package.json` (deve conter um campo `bin` referenciando `./dist/cjs/cli.cjs`)
+
+7. **Verifique a variável de ambiente PATH**
+   Certifique-se de que o diretório global bin do npm está no seu PATH:
+
+```bash
+# Para sistemas baseados em Unix (macOS/Linux)
+echo $PATH
+# Deve incluir algo como /usr/local/bin ou ~/.npm-global/bin
+
+# Para Windows
+echo %PATH%
+# Deve incluir o diretório bin global do npm
+```
+
+8. **Use npx com o caminho completo**
+   Se o comando ainda não for encontrado, tente usar o npx com o caminho completo:
+
+```bash
+npx ./node_modules/intlayer/ dictionaries build
+```
+
+9. **Verifique instalações conflitantes**
+
+```bash
+# Liste todos os pacotes instalados globalmente
+npm list -g --depth=0
+
+# Remova quaisquer instalações globais conflitantes
+npm uninstall -g intlayer
+npm uninstall -g intlayer-cli
+# Depois reinstale
+npm install -g intlayer
+```
+
+10. **Verifique as versões do Node.js e npm**
+    Certifique-se de que está usando versões compatíveis:
+
+```bash
+node --version
+npm --version
+```
+
+    Se estiver usando uma versão desatualizada, considere atualizar o Node.js e o npm.
+
+11. **Verifique problemas de permissão**
+    Se você estiver recebendo erros de permissão:
+
+    ```bash
+    # Para sistemas baseados em Unix
+    sudo npm install -g intlayer
+
+    # Ou altere o diretório padrão do npm
+    mkdir ~/.npm-global
+    npm config set prefix '~/.npm-global'
+    # Adicione ao seu ~/.profile ou ~/.bashrc:
+    export PATH=~/.npm-global/bin:$PATH
+    ```

package/frequent_questions/pt/locale_incorect_in_url.md

@@ -0,0 +1,74 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Locale Incorreto Recuperado da URL
+description: Aprenda como corrigir o locale incorreto recuperado da URL.
+keywords:
+  - locale
+  - url
+  - intlayer
+  - next.js
+  - vite
+  - framework
+  - middleware
+  - configuração
+  - prefixDefault
+  - noPrefix
+slugs:
+  - doc
+  - faq
+  - locale-incoreto-na-url
+---
+
+# Locale Incorreto Recuperado da URL
+
+## Descrição do Problema
+
+Ao tentar acessar o parâmetro locale da URL, você pode encontrar um problema onde o valor do locale está incorreto:
+
+```js
+const { locale } = await params;
+console.log(locale); // retorna "about" ao invés do locale esperado
+```
+
+## Solução
+
+### 1. Verifique a Estrutura dos Arquivos
+
+Certifique-se de que o caminho do roteador da sua aplicação Next.js segue esta estrutura:
+
+```bash
+src/app/[locale]/about/page.tsx
+```
+
+### 2. Verifique a Configuração do Middleware
+
+O problema geralmente ocorre quando o middleware não está presente ou não é acionado. O arquivo do middleware deve estar localizado em:
+
+```bash
+src/middleware.ts
+```
+
+Este middleware é responsável por reescrever as rotas quando `prefixDefault` está definido como `false`. Por exemplo, ele reescreve `/en/about` para `/about`.
+
+### 3. Padrões de URL Baseados na Configuração
+
+#### Configuração Padrão (`prefixDefault: false`, `noPrefix: false`)
+
+- Inglês: `/about`
+- Francês: `/fr/about`
+- Espanhol: `/es/about`
+
+#### Com `prefixDefault: true`
+
+- Inglês: `/en/about`
+- Francês: `/fr/about`
+- Espanhol: `/es/about`
+
+#### Com `noPrefix: true`
+
+- Inglês: `/about`
+- Francês: `/about`
+- Espanhol: `/about`
+
+Para mais detalhes sobre essas opções de configuração, consulte a [Documentação de Configuração](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/configuration.md).

package/frequent_questions/pt/static_rendering.md

@@ -0,0 +1,46 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Renderização Estática vs Dinâmica com i18n no Next.js
+description: Aprenda como usar renderização estática vs dinâmica com i18n no Next.js.
+keywords:
+  - estático
+  - dinâmico
+  - renderização
+  - i18n
+  - next.js
+  - next-intl
+  - intlayer
+  - framework
+  - middleware
+  - configuração
+slugs:
+  - doc
+  - faq
+  - renderizacao-estatica
+---
+
+# Renderização Estática vs Dinâmica com i18n no Next.js
+
+## O problema com o **next-intl**
+
+- **O que acontece?**
+  Quando você usa `useTranslations`, `getTranslations` ou qualquer helper do next-intl _dentro de um Componente de Servidor_ em um app com rotas i18n (`/en/…`, `/fr/…`), o Next.js marca toda a rota como **dinâmica**. ([Next Intl][1])
+
+- **Por quê?**
+  next-intl busca a localidade atual a partir de um cabeçalho disponível apenas na requisição (`x-next-intl-locale`) via `headers()`. Como `headers()` é uma **API dinâmica**, qualquer componente que a utilize perde a otimização estática. ([Next Intl][1], [Next.js][2])
+
+- **Solução oficial (boilerplate)**
+
+  1. Exporte `generateStaticParams` com todas as localidades suportadas.
+  2. Chame `setRequestLocale(locale)` em **todos** os layouts/páginas _antes_ de chamar `useTranslations`. ([Next Intl][1])
+     Isso remove a dependência do cabeçalho, mas agora você tem código extra para manter e uma API instável em produção.
+
+## Como o **intlayer** evita o problema
+
+**Escolhas de design**
+
+1. **Apenas parâmetro de rota** – A localidade vem do segmento de URL `[locale]` que o Next.js já passa para cada página.
+2. **Pacotes em tempo de compilação** – As traduções são importadas como módulos ES regulares, portanto são otimizadas (tree-shaken) e incorporadas no momento da compilação.
+3. **Sem APIs dinâmicas** – `useT()` lê do contexto React, não de `headers()` ou `cookies()`.
+4. **Configuração zero** – Uma vez que suas páginas estejam sob `app/[locale]/`, o Next.js pré-renderiza automaticamente um arquivo HTML por localidade.