Migrando de i18next para Intlayer

Por que migrar de i18next para Intlayer?

Estratégias de Migração

Existem duas estratégias complementares para migrar do i18next para o Intlayer:

1. Adaptador de Compatibilidade (Recomendado para apps existentes) — Instale @intlayer/i18next. Este pacote expõe exatamente a mesma API do i18next, mas delega todo o trabalho de tradução, por baixo dos panos, ao Intlayer. Mantenha suas chamadas existentes de i18next.t(), i18next.changeLanguage() e createInstance() intactas — a única coisa que muda é o caminho de importação e a inicialização.

2. Migração Completa — Substitua gradualmente as APIs do i18next pelas ferramentas nativas do Intlayer, e co-localize seu conteúdo em arquivos .content.ts próximos aos seus componentes.

Este guia cobre a Estratégia 1 (adaptador de compatibilidade) primeiro, depois discute a migração completa opcional.

Índice

Migração Rápida

As etapas a seguir são o mínimo necessário para executar seu aplicativo i18next existente no Intlayer, sem fazer alterações na sua base de código.

1. 1

   Instale as Dependências

   Instale o pacote principal do Intlayer e o adaptador de compatibilidade:

   bash

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   npm install intlayer @intlayer/i18next @intlayer/sync-json-pluginnpx intlayer init

   Você pode manter o i18next instalado com segurança — o adaptador de compatibilidade o utiliza como uma devDependency / peerDependency para tipos TypeScript.

2. 2

   Configure o Intlayer

   O comando intlayer init cria um arquivo inicial intlayer.config.ts. Atualize-o para corresponder aos seus locales existentes e aponte o plugin syncJSON para os seus arquivos de mensagens:

   intlayer.config.ts

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   import { Locales, type IntlayerConfig } from "intlayer";
   import { syncJSON } from "@intlayer/sync-json-plugin";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [
         Locales.ENGLISH,
         Locales.FRENCH,
         Locales.SPANISH,
         // Adicione todos os seus locales existentes aqui
       ],
       defaultLocale: Locales.ENGLISH,
     },
     plugins: [
       syncJSON({
         // Corresponde à sintaxe de espaço reservado do i18next: {{name}}
         format: "i18next",
         source: ({ locale }) => `./src/locales/${locale}.json`,
         location: "src/locales",
       }),
     ],
   };
   
   export default config;

   source mapeia um locale para o caminho de seu arquivo JSON. location diz ao observador (watcher) do Intlayer qual pasta monitorar para alterações. A opção format: 'i18next' garante que espaços reservados como {{name}} sejam interpretados corretamente.

3. 3

   Atualize o Alias do Bundler (Opcional)

   Se você usa um empacotador (Vite, Webpack, esbuild), você pode injetar um alias de módulo para que import ... from 'i18next' resolva automaticamente para @intlayer/i18next. Isso remove a necessidade de alterar os caminhos de importação manualmente em toda a sua base de código.

   Para Vite:

   vite.config.ts

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   import { defineConfig } from "vite";
   import i18nextVitePlugin from "@intlayer/i18next/plugin";
   
   export default defineConfig({
     plugins: [i18nextVitePlugin()],
   });

   O i18nextVitePlugin() encapsula o plugin intlayer() do vite-intlayer e adiciona automaticamente o alias de i18next → @intlayer/i18next para você. Usar o plugin intlayer() comum do vite-intlayer compila os dicionários, mas não adiciona o alias — você teria que renomear as importações para @intlayer/i18next manualmente nesse caso (veja o próximo passo).

Isso é tudo para a migração rápida. Seu aplicativo agora está rodando no Intlayer, mantendo todas as suas importações e a API do i18next intactas.

Migração Completa

As etapas a seguir são opcionais e podem ser feitas gradativamente. Elas desbloqueiam o conjunto completo das funcionalidades do Intlayer: editor visual, CMS, arquivos de conteúdo tipados, automação de tradução por IA e muito mais.

1. 4

   Renomeie Explícitamente as Importações (Opcional)

   Opcional

   Se você preferir tornar a dependência explícita nos seus arquivos-fonte ou não usar um plugin de bundler para criar alias nas importações, você pode renomear os caminhos de importação manualmente:

   Mostrar todo o conteúdo da tabela

   Mostrar todo o conteúdo da tabela

   Abrir a tabela em um modal para ver todo o conteúdo claramente

   Antes	Depois
   import i18next from 'i18next'	import i18next from '@intlayer/i18next'
   import { createInstance } from 'i18next'	import { createInstance } from '@intlayer/i18next'
   import { t } from 'i18next'	import { t } from '@intlayer/i18next'

   Essas são substituições diretas (drop-in) — nenhuma alteração de assinaturas de chamadas, argumentos ou tipos de retorno é necessária.

2. 5

   Habilite a Automação de Tradução por IA

   Opcional

   Com o Intlayer configurado, você pode usar a CLI para preencher traduções ausentes automaticamente:

   bash

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   # Testar traduções ausentes (adicionar ao CI)npx intlayer test# Preencher traduções ausentes usando IAnpx intlayer fill

   Adicione a configuração de IA ao seu intlayer.config.ts:

   intlayer.config.ts

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   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({
         format: "i18next",
         source: ({ locale }) => `./src/locales/${locale}.json`,
         location: "src/locales",
       }),
     ],
     ai: {
       apiKey: process.env.OPENAI_API_KEY,
       // provider: "openai",     // padrão
       // model: "gpt-4o-mini",   // padrão
     },
   };
   
   export default config;

   Verifique a Documentação da CLI do Intlayer para explorar todas as opções disponíveis.

O que pode ser excluído pós-migração

Uma vez que o adaptador de compatibilidade esteja implementado, o seguinte boilerplate padrão do i18next pode ser excluído:

Quando você estiver pronto para ir mais além, o Intlayer descobre automaticamente todos os arquivos .content.ts e .content.json em qualquer lugar da sua base de código (por padrão, em qualquer lugar sob ./src). Basta colocar um arquivo my-component.content.ts ao lado de sua lógica, e o Intlayer o detectará em tempo de build sem necessidade de configuração adicional — não são necessários imports, registros ou um arquivo index central. Isso torna a co-localização das traduções totalmente simples e integrada.

Configuração do TypeScript

O Intlayer usa aumento de módulo (module augmentation) para fornecer IntelliSense completo no TypeScript (autocompletar) para as chaves de tradução. Certifique-se de que o seu arquivo tsconfig.json inclua os tipos gerados automaticamente:

{  // ... Suas configurações existentes de TypeScript  "include": [    // ... Suas configurações existentes de TypeScript    ".intlayer/**/*.ts", // Inclui os tipos gerados automaticamente  ],}

Configuração do Git

Adicione o diretório gerado pelo Intlayer ao seu .gitignore:

# Ignora arquivos gerados pelo Intlayer.intlayer

Explore Além

• Editor Visual — Gerencie traduções visualmente no seu navegador: Editor Visual Intlayer
• CMS — Externalize o conteúdo e gerencie remotamente: CMS do Intlayer
• Extensão para VS Code — Obtenha autocompletar de tradução e detecção de erros em tempo real: Extensão do VS Code para o Intlayer
• Referência da CLI — Lista completa de comandos da CLI: CLI do Intlayer