@intlayer/docs 7.0.4-canary.0 → 7.0.4

package/blog/pt/intlayer_with_next-i18next.md

@@ -1,363 +1,142 @@
 ---
 createdAt: 2025-08-23
-updatedAt: 2025-08-23
+updatedAt: 2025-10-29
 title: Intlayer e next-i18next
-description: Integre o Intlayer com o next-i18next para um aplicativo Next.js
+description: Integre o Intlayer com next-i18next para uma solução abrangente de internacionalização Next.js
 keywords:
   - i18next
   - next-i18next
   - Intlayer
   - Internacionalização
-  - Blogumentação
+  - Blog
   - Next.js
   - JavaScript
   - React
 slugs:
   - blog
   - intlayer-with-next-i18next
+history:
+  - version: 7.0.0
+    date: 2025-10-29
+    changes: Mudança para o plugin syncJSON e reescrita abrangente
 ---
 
-# Next.js Internacionalização (i18n) com next-i18next e Intlayer
+# Internacionalização (i18n) Next.js com next-i18next e Intlayer
 
-Tanto next-i18next quanto Intlayer são frameworks de internacionalização (i18n) de código aberto projetados para aplicações Next.js. Eles são amplamente utilizados para gerenciar traduções, localização e troca de idiomas em projetos de software.
+## Índice
 
-Ambas as soluções incluem três noções principais:
+<TOC/>
 
-1. **Declaração de Conteúdo**: O método para definir o conteúdo traduzível de sua aplicação.
-   - Nomeado `resource` no caso do `i18next`, a declaração de conteúdo é um objeto JSON estruturado contendo pares chave-valor para traduções em um ou mais idiomas. Veja a [documentação do i18next](https://www.i18next.com/translation-function/essentials) para mais informações.
-   - Nomeada `content declaration file` no caso do `Intlayer`, a declaração de conteúdo pode ser um arquivo JSON, JS ou TS exportando os dados estruturados. Veja a [documentação do Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/doc/concept/content) para mais informações.
+## O que é next-i18next?
 
-2. **Utilitários**: Ferramentas para construir e interpretar declarações de conteúdo na aplicação, como `getI18n()`, `useCurrentLocale()`, ou `useChangeLocale()` para next-i18next, e `useIntlayer()` ou `useLocale()` para Intlayer.
+**next-i18next** é um dos frameworks de internacionalização (i18n) mais populares para aplicações Next.js. Construído sobre o poderoso ecossistema **i18next**, ele oferece uma solução abrangente para gerenciar traduções, localização e troca de idiomas em projetos Next.js.
 
-3. **Plugins e Middleware**: Recursos para gerenciar redirecionamento de URL, otimização de pacotes e mais, como `next-i18next/middleware` para next-i18next ou `intlayerMiddleware` para Intlayer.
+No entanto, o next-i18next apresenta alguns desafios:
 
-## Intlayer vs. i18next: Principais Diferenças
+- **Configuração complexa**: Configurar o next-i18next requer múltiplos arquivos de configuração e uma configuração cuidadosa das instâncias i18n no lado do servidor e do cliente.
+- **Traduções dispersas**: Os arquivos de tradução geralmente são armazenados em diretórios separados dos componentes, dificultando a manutenção da consistência.
+- **Gerenciamento manual de namespaces**: Os desenvolvedores precisam gerenciar manualmente os namespaces e garantir o carregamento adequado dos recursos de tradução.
+- **Segurança de tipos limitada**: O suporte ao TypeScript requer configuração adicional e não fornece geração automática de tipos para traduções.
 
-Para explorar as diferenças entre i18next e Intlayer, confira nosso post de blog [next-i18next vs. next-intl vs. Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pt/i18next_vs_next-intl_vs_intlayer.md).
+## O que é o Intlayer?
 
-## Como Gerar Dicionários do next-i18next com Intlayer
+**Intlayer** é uma biblioteca inovadora e de código aberto para internacionalização, projetada para resolver as limitações das soluções tradicionais de i18n. Ela oferece uma abordagem moderna para o gerenciamento de conteúdo em aplicações Next.js.
 
-### Por que Usar Intlayer com next-i18next?
+Veja uma comparação concreta com o next-intl em nosso post no blog [next-i18next vs. next-intl vs. Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pt/next-i18next_vs_next-intl_vs_intlayer.md).
 
-Os arquivos de declaração de conteúdo do Intlayer geralmente oferecem uma melhor experiência de desenvolvedor. Eles são mais flexíveis e manuteníveis devido a duas principais vantagens:
+## Por que combinar o Intlayer com o next-i18next?
 
-1. **Colocação Flexível**: Um arquivo de declaração de conteúdo do Intlayer pode ser colocado em qualquer lugar na árvore de arquivos da aplicação, simplificando o gerenciamento de componentes duplicados ou excluídos sem deixar declarações de conteúdo não utilizadas.
+Embora o Intlayer forneça uma excelente solução i18n independente (veja nosso [guia de integração com Next.js](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_with_nextjs_16.md)), você pode querer combiná-lo com o next-i18next por várias razões:
 
-   Estruturas de arquivos de exemplo:
+1. **Base de código existente**: Você possui uma implementação estabelecida do next-i18next e deseja migrar gradualmente para a melhor experiência de desenvolvedor do Intlayer.
+2. **Requisitos legados**: Seu projeto requer compatibilidade com plugins ou fluxos de trabalho existentes do i18next.
+3. **Familiaridade da equipe**: Sua equipe está confortável com o next-i18next, mas deseja um melhor gerenciamento de conteúdo.
 
-   ```bash codeFormat="typescript"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.ts # Arquivo de declaração de conteúdo
-               └── index.tsx
-   ```
+**Para isso, o Intlayer pode ser implementado como um adaptador para o next-i18next para ajudar a automatizar suas traduções JSON em CLI ou pipelines CI/CD, testar suas traduções e muito mais.**
 
-   ```bash codeFormat="esm"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.mjs # Arquivo de declaração de conteúdo
-               └── index.mjx
-   ```
+Este guia mostra como aproveitar o sistema superior de declaração de conteúdo do Intlayer enquanto mantém a compatibilidade com o next-i18next.
 
-   ```bash codeFormat="cjs"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.cjs # Arquivo de declaração de conteúdo
-               └── index.cjx
-   ```
+---
 
-   ```bash codeFormat="json"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.json # Arquivo de declaração de conteúdo
-               └── index.jsx
-   ```
+## Guia Passo a Passo para Configurar o Intlayer com next-i18next
 
-2. **Traduções Centralizadas**: O Intlayer armazena todas as traduções em um único arquivo, garantindo que nenhuma tradução esteja ausente. Ao usar TypeScript, traduções faltantes são automaticamente detectadas e relatadas como erros.
+### Passo 1: Instalar Dependências
 
-### Instalação
+Instale os pacotes necessários usando seu gerenciador de pacotes preferido:
 
 ```bash packageManager="npm"
-npm install intlayer i18next next-i18next i18next-resources-to-backend
-```
-
-```bash packageManager="yarn"
-yarn add intlayer i18next next-i18next i18next-resources-to-backend
+npm install intlayer @intlayer/sync-json-plugin
 ```
 
 ```bash packageManager="pnpm"
-pnpm add intlayer i18next next-i18next i18next-resources-to-backend
+pnpm add intlayer @intlayer/sync-json-plugin
 ```
 
-### Configurando o Intlayer para Exportar Dicionários do i18next
-
-> Exportar recursos do i18next não garante compatibilidade 1:1 com outras estruturas. É recomendável aderir a uma configuração baseada no Intlayer para minimizar problemas.
-
-Para exportar recursos do i18next, configure o Intlayer em um arquivo `intlayer.config.ts`. Configurações de exemplo:
-
-```typescript fileName="intlayer.config.ts" codeFormat="typescript"
-import { Locales, type IntlayerConfig } from "intlayer";
+```bash packageManager="yarn"
+yarn add intlayer @intlayer/sync-json-plugin
+```
 
-const config: IntlayerConfig = {
-  internationalization: {
-    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
-    defaultLocale: Locales.ENGLISH,
-  },
-  content: {
-    dictionaryOutput: ["i18next"],
-    i18nextResourcesDir: "./i18next/resources",
-  },
-};
+**Explicações dos pacotes:**
 
-export default config;
-```
+- **intlayer**: Biblioteca principal para declaração e gerenciamento de conteúdo
+- **next-intlayer**: Camada de integração Next.js com plugins de build
+- **i18next**: Framework principal de i18n
+- **next-i18next**: Wrapper Next.js para i18next
+- **i18next-resources-to-backend**: Carregamento dinâmico de recursos para i18next
+- **@intlayer/sync-json-plugin**: Plugin para sincronizar declarações de conteúdo do Intlayer para o formato JSON do i18next
 
-```javascript fileName="intlayer.config.mjs" codeFormat="esm"
-import { Locales } from "intlayer";
+### Passo 2: Implemente o plugin Intlayer para encapsular o JSON
 
-/** @type {import('intlayer').IntlayerConfig} */
-const config = {
-  internationalization: {
-    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
-    defaultLocale: Locales.ENGLISH,
-  },
-  content: {
-    dictionaryOutput: ["i18next"],
-    i18nextResourcesDir: "./i18next/resources",
-  },
-};
+Crie um arquivo de configuração do Intlayer para definir os locais suportados:
 
-export default config;
-```
+**Se você também quiser exportar dicionários JSON para o i18next**, adicione o plugin `syncJSON`:
 
-```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
-const { Locales } = require("intlayer");
+```typescript fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
 
-/** @type {import('intlayer').IntlayerConfig} */
-const config = {
+const config: IntlayerConfig = {
   internationalization: {
     locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
     defaultLocale: Locales.ENGLISH,
   },
-  content: {
-    dictionaryOutput: ["i18next"],
-    i18nextResourcesDir: "./i18next/resources",
-  },
-};
-
-module.exports = config;
-```
-
-### Importando Dicionários na Sua Configuração do i18next
-
-Para importar os recursos gerados em sua configuração do i18next, use `i18next-resources-to-backend`. Abaixo estão exemplos:
-
-```typescript fileName="i18n/client.ts" codeFormat="typescript"
-import i18next from "i18next";
-import resourcesToBackend from "i18next-resources-to-backend";
-
-i18next.use(
-  resourcesToBackend(
-    (language: string, namespace: string) =>
-      import(`../i18next/resources/${language}/${namespace}.json`)
-  )
-);
-```
-
-```javascript fileName="i18n/client.mjs" codeFormat="esm"
-import i18next from "i18next";
-import resourcesToBackend from "i18next-resources-to-backend";
-
-i18next.use(
-  resourcesToBackend(
-    (language, namespace) =>
-      import(`../i18next/resources/${language}/${namespace}.json`)
-  )
-);
-```
-
-```javascript fileName="i18n/client.cjs" codeFormat="commonjs"
-const i18next = require("i18next");
-const resourcesToBackend = require("i18next-resources-to-backend");
-
-i18next.use(
-  resourcesToBackend(
-    (language, namespace) =>
-      import(`../i18next/resources/${language}/${namespace}.json`)
-  )
-);
-```
-
-### Declaração de Conteúdo
-
-Exemplos de arquivos de declaração de conteúdo em vários formatos:
-
-```typescript fileName="**/*.content.ts" contentDeclarationFormat="typescript"
-import { t, type Dictionary } from "intlayer";
-
-const content = {
-  key: "my-content",
-  content: {
-    myTranslatedContent: t({
-      en: "Hello World",
-      es: "Hola Mundo",
-      fr: "Bonjour le monde",
-    }),
-  },
-} satisfies Dictionary;
-
-export default content;
-```
-
-```javascript fileName="**/*.content.mjs" contentDeclarationFormat="esm"
-import { t } from "intlayer";
-
-/** @type {import('intlayer').Dictionary} */
-const content = {
-  key: "my-content",
-  content: {
-    myTranslatedContent: t({
-      en: "Hello World",
-      es: "Hola Mundo",
-      fr: "Bonjour le monde",
-    }),
-  },
-};
-```
-
-```javascript fileName="**/*.content.cjs" contentDeclarationFormat="commonjs"
-const { t } = require("intlayer");
-
-module.exports = {
-  key: "my-content",
-  content: {
-    myTranslatedContent: t({
-      en: "Hello World",
-      es: "Hola Mundo",
-      fr: "Bonjour le monde",
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./messages/${locale}/${key}.json`,
     }),
-  },
+  ],
 };
-```
 
-```json fileName="**/*.content.json" contentDeclarationFormat="json"
-{
-  "$schema": "https://intlayer.org/schema.json",
-  "key": "my-content",
-  "content": {
-    "myTranslatedContent": {
-      "nodeType": "translation",
-      "translation": {
-        "en": "Hello World",
-        "fr": "Bonjour le monde",
-        "es": "Hola Mundo"
-      }
-    }
-  }
-}
-```
-
-### Construindo os Recursos do next-i18next
-
-Para construir os recursos do next-i18next, execute o seguinte comando:
-
-```bash packageManager="npm"
-npx run intlayer build
-```
-
-```bash packageManager="yarn"
-yarn intlayer build
-```
-
-```bash packageManager="pnpm"
-pnpm intlayer build
-```
-
-Isso irá gerar recursos no diretório `./i18next/resources`. A saída esperada:
-
-```bash
-.
-└── i18next
-    └── resources
-       └── en
-           └── my-content.json
-       └── fr
-           └── my-content.json
-       └── es
-           └── my-content.json
+export default config;
 ```
 
-Nota: O namespace do i18next corresponde à chave de declaração do Intlayer.
+O plugin `syncJSON` irá automaticamente encapsular o JSON. Ele irá ler e escrever os arquivos JSON sem alterar a arquitetura do conteúdo.
 
-### Implementando o Plugin do Next.js
+Se você quiser fazer coexistir esse JSON com os arquivos de declaração de conteúdo do intlayer (`.content` files), o Intlayer procederá da seguinte forma:
 
-Uma vez configurado, implemente o plugin do Next.js para reconstruir seus recursos do i18next sempre que os arquivos de declaração de conteúdo do Intlayer forem atualizados.
+    1. carregar tanto os arquivos JSON quanto os arquivos de declaração de conteúdo e transformá-los em um dicionário do intlayer.
+    2. se houver conflitos entre o JSON e os arquivos de declaração de conteúdo, o Intlayer irá proceder à mesclagem de todos esses dicionários. Dependendo da prioridade dos plugins e da do arquivo de declaração de conteúdo (todos são configuráveis).
 
-```typescript fileName="next.config.mjs"
-import { withIntlayer } from "next-intlayer/server";
+Se alterações forem feitas usando o CLI para traduzir o JSON, ou usando o CMS, o Intlayer atualizará o arquivo JSON com as novas traduções.
 
-/** @type {import('next').NextConfig} */
-const nextConfig = {};
-
-export default withIntlayer(nextConfig);
-```
-
-### Usando Conteúdo nos Componentes do Next.js
-
-Após implementar o plugin do Next.js, você pode usar o conteúdo em seus componentes:
-
-```typescript fileName="src/components/myComponent/index.tsx" codeFormat="typescript"
-import type { FC } from "react";
-import { useTranslation } from "react-i18next";
+---
 
-const IndexPage: FC = () => {
-  const { t } = useTranslation();
+## Configuração do Git
 
-  return (
-    <div>
-      <h1>{t("my-content.title")}</h1>
-      <p>{t("my-content.description")}</p>
-    </div>
-  );
-};
+Exclua arquivos gerados do controle de versão:
 
-export default IndexPage;
+```plaintext fileName=".gitignore"
+# Ignorar arquivos gerados pelo Intlayer
+.intlayer
+intl
 ```
 
-```jsx fileName="src/components/myComponent/index.mjx" codeFormat="esm"
-import { useTranslation } from "react-i18next";
+Esses arquivos são automaticamente regenerados durante o processo de build e não precisam ser comitados no seu repositório.
 
-const IndexPage = () => {
-  const { t } = useTranslation();
+### Extensão VS Code
 
-  return (
-    <div>
-      <h1>{t("my-content.title")}</h1>
-      <p>{t("my-content.description")}</p>
-    </div>
-  );
-};
-```
-
-```jsx fileName="src/components/myComponent/index.cjx" codeFormat="commonjs"
-const { useTranslation } = require("react-i18next");
+Para uma melhor experiência de desenvolvimento, instale a extensão oficial **Intlayer VS Code Extension**:
 
-const IndexPage = () => {
-  const { t } = useTranslation();
+[Instalar no VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
 
-  return (
-    <div>
-      <h1>{t("my-content.title")}</h1>
-      <p>{t("my-content.description")}</p>
-    </div>
-  );
-};
-```
+[Instalar no Marketplace do VS Code](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)