@intlayer/docs 7.0.4-canary.0 → 7.0.5

package/blog/pt/intlayer_with_next-intl.md

@@ -1,310 +1,111 @@
 ---
 createdAt: 2025-01-02
-updatedAt: 2025-06-29
-title: Intlayer e next-intl
-description: Integre o Intlayer com o next-intl para a internacionalização (i18n) de um aplicativo React
-keywords:
-  - next-intl
-  - Intlayer
-  - Internacionalização
-  - Blogumentação
-  - Next.js
-  - JavaScript
-  - React
+updatedAt: 2025-10-29
+title: Como automatizar suas traduções JSON do next-intl usando Intlayer
+description: Automatize suas traduções JSON com Intlayer e next-intl para uma internacionalização aprimorada em aplicações Next.js.
 slugs:
   - blog
   - intlayer-with-next-intl
+history:
+  - version: 7.0.0
+    date: 2025-10-29
+    changes: Alteração para o plugin syncJSON
 ---
 
-# Next.js Internacionalização (i18n) com next-intl e Intlayer
+# Como automatizar suas traduções JSON do next-intl usando Intlayer
 
-Tanto o next-intl quanto o 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.
+## O que é o Intlayer?
 
-Eles compartilham três noções principais:
+**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.
 
-1. **Declaração de Conteúdo**: O método para definir o conteúdo traduzível da sua aplicação.
-   - Chamado de `arquivo de declaração de conteúdo` no Intlayer, que pode ser um arquivo JSON, JS ou TS exportando os dados estruturados. Veja [documentação do Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/doc/concept/content) para mais informações.
-   - Chamado de `messages` ou `locale messages` no next-intl, geralmente em arquivos JSON. Veja [documentação do next-intl](https://github.com/amannn/next-intl) para mais informações.
+Veja uma comparação concreta com 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).
 
-2. **Utilitários**: Ferramentas para construir e interpretar declarações de conteúdo na aplicação, como `useIntlayer()` ou `useLocale()` para Intlayer, e `useTranslations()` para next-intl.
+## Por que combinar Intlayer com next-intl?
 
-3. **Plugins e Middlewares**: Recursos para gerenciar redirecionamento de URL, otimização de empacotamento, e mais, ex: `intlayerMiddleware` para Intlayer ou [`createMiddleware`](https://github.com/amannn/next-intl) para next-intl.
+Embora o Intlayer forneça uma excelente solução de 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-intl por várias razões:
 
-## Intlayer vs. next-intl: Principais Diferenças
+1. **Base de código existente**: Você tem uma implementação estabelecida do next-intl 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 next-intl.
+3. **Familiaridade da equipe**: Sua equipe está confortável com o next-intl, mas deseja um melhor gerenciamento de conteúdo.
 
-Para uma análise mais profunda de como o Intlayer se compara a outras bibliotecas de i18n para Next.js (como o next-intl), confira o [post no 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).
+**Para isso, o Intlayer pode ser implementado como um adaptador para o next-intl para ajudar a automatizar suas traduções JSON em pipelines CLI ou CI/CD, testar suas traduções e muito mais.**
 
-## Como Gerar Mensagens next-intl com Intlayer
+Este guia mostra como aproveitar o sistema superior de declaração de conteúdo do Intlayer enquanto mantém a compatibilidade com o next-intl.
 
-### Por que Usar Intlayer com next-intl?
+## Índice
 
-Os arquivos de declaração de conteúdo do Intlayer geralmente oferecem uma melhor experiência para o desenvolvedor. Eles são mais flexíveis e manuteníveis devido a duas principais vantagens:
+<TOC/>
 
-1. **Colocação Flexível**: Você pode colocar um arquivo de declaração de conteúdo do Intlayer em qualquer lugar na árvore de arquivos da sua aplicação. Isso facilita renomear ou deletar componentes sem deixar arquivos de mensagem não utilizados ou pendentes.
+## Guia passo a passo para configurar o Intlayer com next-intl
 
-   Exemplos de estruturas de arquivos:
+### Passo 1: Instalar dependências
 
-   ```bash codeFormat="typescript"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.ts # Arquivo de declaração de conteúdo
-               └── index.tsx
-   ```
-
-   ```bash codeFormat="esm"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.mjs # Arquivo de declaração de conteúdo
-               └── index.mjx
-   ```
-
-   ```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
-   ```
-
-2. **Traduções Centralizadas**: O Intlayer armazena todas as traduções em uma única declaração de conteúdo, garantindo que nenhuma tradução esteja faltando. Em projetos TypeScript, traduções ausentes são sinalizadas automaticamente como erros de tipo, fornecendo feedback imediato aos desenvolvedores.
-
-### Instalação
-
-Para usar o Intlayer e o next-intl juntos, instale ambas as bibliotecas:
+Instale os pacotes necessários:
 
 ```bash packageManager="npm"
-npm install intlayer next-intl
+npm install intlayer @intlayer/sync-json-plugin
 ```
 
-```bash packageManager="yarn"
-yarn add intlayer next-intl
+```bash packageManager="pnpm"
+pnpm add intlayer @intlayer/sync-json-plugin
 ```
 
-```bash packageManager="pnpm"
-pnpm add intlayer next-intl
+```bash packageManager="yarn"
+yarn add intlayer @intlayer/sync-json-plugin
 ```
 
-### Configurando o Intlayer para Exportar Mensagens next-intl
+**Descrição dos pacotes:**
 
-> **Nota:** Exportar mensagens do Intlayer para o next-intl pode introduzir pequenas diferenças na estrutura. Se possível, mantenha um fluxo apenas do Intlayer ou apenas do next-intl para simplificar a integração. Se você precisar gerar mensagens next-intl a partir do Intlayer, siga os passos abaixo.
+- **intlayer**: Biblioteca principal para gerenciamento de internacionalização, declaração de conteúdo e construção
+- **@intlayer/sync-json-plugin**: Plugin para exportar declarações de conteúdo do Intlayer para o formato JSON compatível com next-intl
 
-Crie ou atualize um arquivo `intlayer.config.ts` (ou `.mjs` / `.cjs`) na raiz do seu projeto:
+### Passo 2: Implementar o plugin Intlayer para encapsular o JSON
 
-```typescript fileName="intlayer.config.ts" codeFormat="typescript"
-import { Locales, type IntlayerConfig } from "intlayer";
+Crie um arquivo de configuração do Intlayer para definir os locais suportados:
 
-const config: IntlayerConfig = {
-  internationalization: {
-    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
-    defaultLocale: Locales.ENGLISH,
-  },
-  content: {
-    dictionaryOutput: ["next-intl"], // Usar a saída do next-intl
-    nextIntlMessagesDir: "./intl/messages", // Onde salvar mensagens next-intl
-  },
-};
+**Se você também quiser exportar dicionários JSON para o next-intl**, adicione o plugin `syncJSON`:
 
-export default config;
-```
-
-```javascript fileName="intlayer.config.mjs" codeFormat="esm"
-import { Locales } from "intlayer";
-
-/** @type {import('intlayer').IntlayerConfig} */
-const config = {
-  internationalization: {
-    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
-    defaultLocale: Locales.ENGLISH,
-  },
-  content: {
-    dictionaryOutput: ["react-intl"],
-    nextIntlMessagesDir: "./intl/messages",
-  },
-};
-
-export default config;
-```
-
-```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: ["next-intl"],
-    nextIntlMessagesDir: "./intl/messages",
-  },
-};
-
-module.exports = config;
-```
-
-### Declaração de Conteúdo
-
-Abaixo estão exemplos de arquivos de declaração de conteúdo em múltiplos formatos. O Intlayer compilará isso em arquivos de mensagem que o next-intl pode consumir.
-
-```typescript fileName="**/*.content.ts" contentDeclarationFormat="typescript"
-import { t, type Dictionary } from "intlayer";
-
-const content = {
-  key: "my-component",
-  content: {
-    helloWorld: 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-component",
-  content: {
-    helloWorld: t({
-      en: "Hello World",
-      es: "Hola Mundo",
-      fr: "Bonjour le monde",
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./messages/${locale}/${key}.json`,
     }),
-  },
+  ],
 };
 
-export default content;
-```
-
-```javascript fileName="**/*.content.cjs" contentDeclarationFormat="commonjs"
-const { t } = require("intlayer");
-
-module.exports = {
-  key: "my-component",
-  content: {
-    helloWorld: t({
-      en: "Hello World",
-      es: "Hola Mundo",
-      fr: "Bonjour le monde",
-    }),
-  },
-};
+export default config;
 ```
 
-```json fileName="**/*.content.json" contentDeclarationFormat="json"
-{
-  "$schema": "https://intlayer.org/schema.json",
-  "key": "my-component",
-  "content": {
-    "helloWorld": {
-      "nodeType": "translation",
-      "translation": {
-        "en": "Hello World",
-        "fr": "Bonjour le monde",
-        "es": "Hola Mundo"
-      }
-    }
-  }
-}
-```
+O plugin `syncJSON` irá automaticamente encapsular o JSON. Ele irá ler e escrever os arquivos JSON sem alterar a arquitetura do conteúdo.
 
-### Construir as Mensagens next-intl
+Se você quiser fazer coexistir esse JSON com arquivos de declaração de conteúdo do intlayer (`.content` files), o Intlayer procederá da seguinte forma:
 
-Para construir os arquivos de mensagem para o next-intl, execute:
+    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).
 
-```bash packageManager="npm"
-npx intlayer dictionaries build
-```
+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.
 
-```bash packageManager="yarn"
-yarn intlayer build
-```
+## Configuração do Git
 
-```bash packageManager="pnpm"
-pnpm intlayer build
-```
+É recomendado ignorar os arquivos gerados automaticamente pelo Intlayer:
 
-Isso irá gerar recursos no diretório `./intl/messages` (conforme configurado em `intlayer.config.*`). A saída esperada:
-
-```bash
-.
-└── intl
-    └── messages
-       └── pt
-           └── my-content.json
-       └── fr
-           └── my-content.json
-       └── es
-           └── my-content.json
+```plaintext fileName=".gitignore"
+# Ignorar arquivos gerados pelo Intlayer
+.intlayer
 ```
 
-Cada arquivo inclui mensagens compiladas de todas as declarações de conteúdo do Intlayer. As chaves de nível superior normalmente correspondem aos seus campos `content.key`.
-
-### Usando next-intl em Seu App Next.js
-
-> Para mais detalhes, veja a [documentação oficial de uso do next-intl](https://github.com/amannn/next-intl#readme).
-
-1. **Criar um Middleware (opcional):**  
-   Se você quiser gerenciar a detecção automática de idioma ou redirecionamento, use o [createMiddleware do next-intl](https://github.com/amannn/next-intl#createMiddleware).
-
-   ```typescript fileName="middleware.ts"
-   import createMiddleware from "next-intl/middleware";
-   import { NextResponse } from "next/server";
-
-   export default createMiddleware({
-     locales: ["en", "fr", "es"],
-     defaultLocale: "en",
-   });
-
-   export const config = {
-     matcher: ["/((?!api|_next|.*\\..*).*)"],
-   };
-   ```
-
-2. **Criar um `layout.tsx` ou `_app.tsx` para Carregar Mensagens:**  
-   Se você está usando o App Router (Next.js 13+), crie um layout:
-
-   ```typescript fileName="app/[locale]/layout.tsx"
-   import { NextIntlClientProvider } from 'next-intl';
-   import { notFound } from 'next/navigation';
-   import React, { ReactNode } from 'react';
+Esses arquivos podem ser regenerados durante o processo de build e não precisam ser commitados no controle de versão.
 
+### Extensão VS Code
 
-   export default async function RootLayout({
-     children,
-     params
-   }: {
-     children: ReactNode;
-     params: { locale: string };
-   }) {
-     let messages;
-     try {
-       messages = (await import(`../../intl/messages/${params.locale}.json`)).default;
-     } catch (error) {
-       notFound();
-     }
+Para melhorar a experiência do desenvolvedor, instale a extensão oficial **Intlayer VS Code Extension**:
 
-     return (
-       <html lang={params.locale}>
-         <body>
-   ```
+[Instalar a partir do Marketplace do VS Code](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)

package/blog/pt/intlayer_with_react-i18next.md

@@ -1,98 +1,124 @@
 ---
 createdAt: 2025-01-02
-updatedAt: 2025-06-29
-title: Intlayer e react-i18next
-description: Compare o Intlayer com o react-i18next para um aplicativo React
+updatedAt: 2025-10-29
+title: Como automatizar suas traduções JSON do react-i18next usando Intlayer
+description: Automatize suas traduções JSON com Intlayer e react-i18next para uma internacionalização aprimorada em aplicações React.
 keywords:
   - react-i18next
   - i18next
   - Intlayer
   - Internacionalização
-  - Blogumentação
-  - Next.js
-  - JavaScript
+  - i18n
+  - Blog
   - React
+  - JavaScript
+  - TypeScript
+  - Gestão de Conteúdo
 slugs:
   - blog
   - intlayer-with-react-i18next
+history:
+  - version: 7.0.0
+    date: 2025-10-29
+    changes: Mudança para o plugin syncJSON
 ---
 
-# React Internationalization (i18n) com react-i18next e Intlayer
-
-## Visão Geral
-
-- **Intlayer** ajuda você a gerenciar traduções através de arquivos de declaração de conteúdo **a nível de componente**.
-- **react-i18next** é uma integração popular do React para **i18next** que fornece hooks como `useTranslation` para buscar strings localizadas em seus componentes.
-
-Quando combinados, Intlayer pode **exportar** dicionários em **JSON compatível com i18next** para que react-i18next possa **consumi-los** em tempo de execução.
-
-## Por que usar Intlayer com react-i18next?
-
-Os arquivos de declaração de conteúdo **Intlayer** oferecem uma melhor experiência para o desenvolvedor, pois são:
-
-1. **Flexíveis na Colocação de Arquivos**  
-   Coloque cada arquivo de declaração de conteúdo ao lado do componente que precisa dele. Essa estrutura permite que você mantenha traduções localizadas, prevenindo traduções órfãs quando componentes se movem ou são excluídos.
-
-   ```bash codeFormat="typescript"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.ts # Arquivo de declaração de conteúdo
-               └── index.tsx
-   ```
-
-   ```bash codeFormat="esm"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.mjs # Arquivo de declaração de conteúdo
-               └── index.mjx
-   ```
-
-   ```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
-   ```
-
-2. **Traduções Centralizadas**  
-   Um único arquivo de declaração de conteúdo coleta todas as traduções necessárias para um componente, tornando mais fácil identificar traduções ausentes.  
-   Com TypeScript, você ainda recebe erros em tempo de compilação se traduções estiverem faltando.
-
-## Instalação
-
-Em um projeto Create React App, instale essas dependências:
-
-```bash
-# Com npm
-npm install intlayer react-i18next i18next i18next-resources-to-backend
+# Como automatizar suas traduções JSON do react-i18next usando Intlayer
+
+## O que é o 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 a gestão de conteúdo em aplicações React.
+
+Veja uma comparação concreta com react-i18next em nosso post no blog [react-i18next vs. react-intl vs. Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pt/react-i18next_vs_react-intl_vs_intlayer.md).
+
+## Por que combinar Intlayer com react-i18next?
+
+Embora o Intlayer forneça uma excelente solução de i18n independente (veja nosso [guia de integração com React](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_with_vite+react.md)), você pode querer combiná-lo com react-i18next por vários motivos:
+
+1. **Base de código existente**: Você possui uma implementação estabelecida do react-i18next e deseja migrar gradualmente para a melhor experiência de desenvolvedor oferecida pelo Intlayer.
+2. **Requisitos legados**: Seu projeto exige compatibilidade com plugins ou fluxos de trabalho existentes do react-i18next.
+3. **Familiaridade da equipe**: Sua equipe está confortável com o react-i18next, mas deseja uma melhor gestão de conteúdo.
+
+**Para isso, o Intlayer pode ser implementado como um adaptador para o react-i18next, ajudando a automatizar suas traduções JSON em pipelines CLI ou CI/CD, testar suas traduções e muito mais.**
+
+Este guia mostra como aproveitar o sistema superior de declaração de conteúdo do Intlayer enquanto mantém a compatibilidade com o react-i18next.
+
+## Índice
+
+<TOC/>
+
+## Guia passo a passo para configurar o Intlayer com react-i18next
+
+### Passo 1: Instalar Dependências
+
+Instale os pacotes necessários:
+
+```bash packageManager="npm"
+npm install intlayer @intlayer/sync-json-plugin
+```
+
+```bash packageManager="pnpm"
+pnpm add intlayer @intlayer/sync-json-plugin
 ```
 
-```bash
-# Com yarn
-yarn add intlayer react-i18next i18next i18next-resources-to-backend
+```bash packageManager="yarn"
+yarn add intlayer @intlayer/sync-json-plugin
 ```
 
-```bash
-# Com pnpm
-pnpm add intlayer react-i18next i18next i18next-resources-to-backend
+**Descrição dos pacotes:**
+
+- **intlayer**: Biblioteca principal para gerenciamento de internacionalização, declaração de conteúdo e construção
+- **@intlayer/sync-json-plugin**: Plugin para exportar declarações de conteúdo do Intlayer para o formato JSON compatível com react-i18next
+
+### Passo 2: Implementar o plugin Intlayer para encapsular o JSON
+
+Crie um arquivo de configuração do Intlayer para definir os seus locais suportados:
+
+**Se você também quiser exportar dicionários JSON para o react-i18next**, adicione o plugin `syncJSON`:
+
+```typescript fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./messages/${locale}/${key}.json`,
+    }),
+  ],
+};
+
+export default config;
+```
+
+O plugin `syncJSON` irá automaticamente encapsular o JSON. Ele irá ler e escrever os arquivos JSON sem alterar a arquitetura do conteúdo.
+
+Se você quiser fazer coexistir esse JSON com arquivos de declaração de conteúdo do intlayer (`.content` files), o Intlayer procederá da seguinte forma:
+
+    1. carregar tanto os arquivos JSON quanto os arquivos de declaração de conteúdo e transformá-los em um dicionário 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).
+
+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.
+
+Para ver mais detalhes sobre o plugin `syncJSON`, por favor consulte a [documentação do plugin syncJSON](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/plugins/sync-json.md).
+
+## Configuração do Git
+
+É recomendado ignorar os arquivos gerados automaticamente pelo Intlayer:
+
+```plaintext fileName=".gitignore"
+# Ignorar arquivos gerados pelo Intlayer
+.intlayer
 ```
 
-### O que são esses pacotes?
+Estes arquivos podem ser regenerados durante o seu processo de build e não precisam ser commitados no controle de versão.
+
+### Extensão VS Code
+
+Para uma melhor experiência de desenvolvimento, instale a **Extensão oficial Intlayer para VS Code**:
 
-- **intlayer** – A CLI e biblioteca principal para gerenciar configurações de i18n, declarações de conteúdo e construir saídas de dicionário.
-- **react-intlayer** –
+[Instalar no VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)