Migrando de react-i18next / i18next para Intlayer

Por que migrar de react-i18next / i18next para Intlayer?

Estratégias de Migração

Existem duas estratégias complementares para migrar de react-i18next / i18next para o Intlayer:

1. Adaptador de Compatibilidade (Recomendado para apps existentes) — Instale o @intlayer/react-i18next (para compilação em componentes React) e/ou inclua na mesma jogada o pacote com foco na área do i18n geral @intlayer/i18next. Esses pacotes expõem exatamente a mesma API do react-i18next / i18next, mas delegam todo o trabalho de tradução, por baixo dos panos, para o Intlayer. Mantenha intactas as suas chamadas existentes relacionadas ao useTranslation, Trans, withTranslation e i18next.t() — o que muda exclusivamente serão os caminhos listados em suas importações.

2. Migração Completa — Substitua progressivamente com calma o legado vindo das APIs originadas no ecossistema do react-i18next pelas opções dos hooks modernos do Intlayer (ex: useIntlayer, IntlayerProvider) enquanto paralelamente vai colocalizando todo modelo mantenedor de seus dados por detrás de diretórios contendo sua extensão em novo formato padrão .content.ts próximos em hierarquia de pastas diretamente onde pertencem no conjunto ao lado dos seus devidos componentes.

Este guia cobre primeiro a Estratégia 1 (adaptador de compatibilidade) e, em seguida, detalha 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 react-i18next existente no Intlayer, sem alterar o código de nenhum componente.

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 react-intlayer @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-pluginnpx intlayer init

   Mantenha em segurança os seus pacotes ligados diretamente de base instalados na aplicação vinda da estrutura original como o seu react-i18next acompanhado ainda paralelamente do i18next presentes no decorrer de tudo que fará. O novo adaptador encarregado na compatibilização com ele faz proveito exigindo tais referências com ligações que visam fins relacionados à averiguação do compilador TypeScript enquanto classificados de forma branda seja no modo das conhecidas marcações opcionais tratadas por opções designadas pelas extensões denominadas em formato de rótulos tanto pela vertente de devDependencies ou via preenchimento sob o arranjo de modelo atrelado por características na modelagem visual de exigência e suporte de classes associadas referidas por via das peerDependencies. Em sumo e no final do percurso de execução prática, em tempo nenhum por parte deste ou aquele momento, a menor que seja uma obrigatória modificação se mostrará pedida e passará exigindo ter ou haver edição prévia nas dependências originadas em base à sua antiga raiz contida sob a sua grade de pares inserida lá mesmo perante arquivos definidores de referências presentes nos módulos contidos no final com a exata terminação e nome por parte da listagem no seu base e raiz package.json.

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 direcione o plugin syncJSON para 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 react-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 os espaços reservados como {{name}} sejam interpretados corretamente.

3. 3

   Adicione os plugins do Intlayer ao seu bundler

   Insira ao redor no centro global contendo sua forma inicial já estabelecida englobada a respeito e encargo atrelado à parte e seção dos dados descritores voltados à moldar seu agrupador que compila tudo engatando então, para junto daquele conjunto e ambiente, toda base construída no modelo feito no pacote designado à trazer uma tradução suave por base de ser um adaptante facilitador nas vias deste compatibilizador final e auxiliar. Ao integrar ele perfeitamente aos demais, ocorrerá de forma orgânica as definições automáticas contidas baseando as ligações intrínsecas essenciais ao passo a compor internamente para todo funcionamento o emparelhamento com monitoração dos conteúdos em si. O processo crucial por aqui acontece então garantindo na retaguarda de todo código principal e ao longo e tempo voltados a etapa do próprio momento exato do processo visando a checagem no Build-Time que uma injeção perfeitamente clara de alias no âmbito estruturado sobre os módulos transcorra sem incidentes. Sendo isso de suma utilidade já que ele faz automaticamente chamadas que estiverem originárias nos antigos moldes provenientes da sua herança antiga utilizando caminhos parecidos vindos num padrão referenciado que cita um import … from 'react-i18next' (inclusive no outro sendo pelo lado direto ao referir-se perante uso focado ao contido do chamado vindo a requerer o 'i18next') sejam interceptadas fluindo tranquilamente guiadas com transparência a passarem e repassarem a frente direcionadas para caírem num retorno certeiro e bem referenciado focando unicamente recair sua totalidade visando e retornando num fluxo para os emparelhamentos dos caminhos novos referenciados por vias dos padrões usando as vias criadas ao designar os caminhos @intlayer/react-i18next e bem em conjunto, também o que leva no padrão ao outro designado como parte no caminho @intlayer/i18next. Ao concluir as averiguações em campo visando o período completo deste percurso por todo o momento decorrente, o ponto focado no encerramento garante tranquilidade demonstrando claramente ser impossível exigirem ter de se executar intervenção manual buscando forçar com que se repasse alterando o que é seu por essência originada do código e base na via de código-fonte. Para Vite: typescript fileName="vite.config.ts" codeFormat={["typescript", "esm", "commonjs"]} import { defineConfig } from "vite"; import react from "@vitejs/plugin-react"; import { reactI18nextVitePlugin } from "@intlayer/react-i18next/plugin"; export default defineConfig({ plugins: [react(), reactI18nextVitePlugin()], }); > O reactI18nextVitePlugin() encapsula o plugin intlayer() do vite-intlayer e adiciona automaticamente os aliases para react-i18next / i18next. Usar o plugin comum intlayer() do pacote originado pelo empacotamento advindo pela base focada a integração focada em fornecer as chaves para os mecanismos voltados à compilação oriunda pela origem proveniente em cima de quem engloba a formatação em uso para compilar junto a ele seus dicionários (isso no arranjo base designado por nós na essência da extensão base em cima das raízes vindas pelo intermédio voltado perante as tratativas visando suporte direto perante ambiente vite-intlayer), fará sem falta o seu trabalho perfeitamente. Contudo, fique bem claro de cara, a mesma ação proveniente da formatação crua não fará ali de brinde e presente as ligações encarregadas em anexar por tabela os aliases — O que acaba exigindo nesse contexto o seu devido trabalho operando para tratar em re-renomeações e renomeações da totalidade e conjunções provindas num agrupamento generalizado focando para as vias de sua base manual mirando a todos retornos perante todas frentes baseadas na invocação onde há e constem nas vias os caminhos aos caminhos baseados na estrutura chamando pelos prefixos sob base inicial do @intlayer/* (Consulte para mais e melhores detalhes no passo subsequente da Etapa 4). Para Next.js: Se você usa next-i18next (integração Pages Router), instale @intlayer/next-i18next e next-intlayer: bash packageManager="npm" npm install @intlayer/next-i18next next-intlayer Em seguida, adicione o plugin de compatibilidade ao seu next.config.ts (ele injetará os aliases de next-i18next / react-i18next / i18next): typescript fileName="next.config.ts" codeFormat={["typescript", "esm", "commonjs"]} import type { NextConfig } from "next"; import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin"; const withIntlayer = createNextI18nPlugin(); const nextConfig: NextConfig = { /* Suas opções de configuração */ }; export default withIntlayer(nextConfig); > A antiga necessidade focada sob as bases voltadas em se iniciar usando chamadas i18next.init() lado a lado incluindo para a lista ainda por cima os métodos arcaicos operados pelo lado humano que provém e forçavam com arranjos via Bootstraping na parte contendo as amarrações do Provedor de Dados tornam-se de imediato agora não mais que memórias, algo do passado, coisas defasadas e em estado não operante. O Intlayer compila todos os dicionários no momento do build (build-time), removendo o passo de ter de aguardar por carregar os materiais dependendo com base ligada ao tempo decorrente contido pelo lado do run-time. Com seu formato atrelado como base central visando gerir os redirecionamentos usando os novos recursos vinculados do alias a todo pacote proveniente na essência ligada por base à função atribuída contida operando no provedor engarregará este componente e delegará nas mãos dele todo o processo que abrange e tem com meta as formatações e finalidades do controle encarregado nas inicializações a serem disparadas por tudo aquilo a ser encarregado perante o que seja listado adiante e em todo processamento principal que advém adiante.

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 react-i18next intactas.

Chaves de tradução tipadas — automaticamente. Uma vez que o Intlayer compila seus dicionários, useTranslation e getFixedT tornam-se tipados no seu conteúdo real. As chaves serão autocompletadas na sua IDE e caminhos inválidos resultarão em erros do TypeScript em tempo de compilação — nenhuma configuração extra é necessária.

tsx

Copiar conteúdo

Copiar código

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

// 'about' é uma chave configurada no dicionário → t() apenas processará o uso aceitando as conexões baseadas na viabilidade e certeza do caminho referir algo totalmente válidoconst { t } = useTranslation("about");t("counter.label"); // ✓ autocompletart("does.not.exist"); // ✗ erro do TypeScript// Componente no lado servidor (instância i18next)const tAbout = i18n.getFixedT(null, "about");tAbout("counter.label"); // ✓ tipado

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

   O plugin do Intlayer já lida com o aliasing (apelido) a nível do bundler. Se preferir tornar a dependência explícita nos seus arquivos de código-fonte, você pode renomear as importações 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 { useTranslation } from 'react-i18next'	import { useTranslation } from '@intlayer/react-i18next'
   import { Trans } from 'react-i18next'	import { Trans } from '@intlayer/react-i18next'
   import { withTranslation } from 'react-i18next'	import { withTranslation } from '@intlayer/react-i18next'
   import { I18nextProvider } from 'react-i18next'	import { I18nextProvider } from '@intlayer/react-i18next'
   import { initReactI18next } from 'react-i18next'	import { initReactI18next } from '@intlayer/react-i18next'
   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'

   Para Next.js (next-i18next):

   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 { serverSideTranslations } from 'next-i18next/serverSideTranslations'	import { serverSideTranslations } from '@intlayer/next-i18next'
   import { appWithTranslation } from 'next-i18next'	import { appWithTranslation } from '@intlayer/next-i18next'
   import { useTranslation } from 'next-i18next'	import { useTranslation } from '@intlayer/next-i18next'

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 react-i18next / 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 do seu MyComponent.tsx, 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 com páginas e componentes totalmente fluida.

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
• Intlayer com React — Guia completo de configuração para React: intlayerwithvite+react.md
• Intlayer com Next.js — Guida completo de configuração para Next.js: intlayerwithnextjs_16.md