Migrando do next-intl para Intlayer

Por que migrar do next-intl para Intlayer?

Estratégia de Migração

A abordagem recomendada para aplicativos existentes é usar o adaptador de compatibilidade: Instale @intlayer/next-intl. Ele expõe exatamente a mesma API do next-intl, mas delega todo o trabalho de tradução, por baixo dos panos, ao Intlayer.

Você mantém intactos o useTranslations, o getTranslations, o NextIntlClientProvider e os demais usos em seus arquivos atuais — a única coisa que muda é o caminho da importação. Não há necessidade de refatorar assinaturas de funções de chamadas, estrutura de propriedades ou design dos componentes.

Com o tempo, você pode opcionalmente migrar arquivos individuais para o formato .content.ts mais rico do Intlayer para destravar o editor visual, CMS e o escopo no nível do componente — mas este passo é totalmente opcional e pode ser feito de modo incremental.

Índice

Migração Rápida

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

1. 1

   Instale as Dependências

   Instale os pacotes principais do Intlayer e o adaptador de compatibilidade @intlayer/next-intl:

   bash

   Copiar conteúdo

   Copiar código

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

   npm install intlayer next-intlayer @intlayer/next-intl @intlayer/sync-json-pluginnpx intlayer init

   Mantenha o next-intl instalado — ele ainda é exigido para o roteamento de URL (createNavigation, createMiddleware, Link, redirect, usePathname, useRouter). O adaptador de compatibilidade não substitui a camada de roteamento.

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 aos 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({
         // 'icu' corresponde à sintaxe de espaço reservado ICU do next-intl: {name}, {count, plural, ...}
         format: "icu",
         source: ({ locale }) => `./messages/${locale}.json`,
         location: "messages",
       }),
     ],
   };
   
   export default config;

   source mapeia um locale para o caminho do arquivo JSON correspondente. location diz ao observador (watcher) do Intlayer qual pasta monitorar para alterações. A opção format: 'icu' garante que espaços reservados ICU como {name} e {count, plural, one {# item} other {# items}} sejam analisados corretamente.

   Veja a Documentação de Configuração para a lista completa das opções disponíveis.

3. 3

   Integre o plugin do Intlayer ao Next.js

   Envolva a sua configuração existente do Next.js com createNextIntlPlugin proveniente de @intlayer/next-intl/plugin. Este pacote aplica o withIntlayer e simultaneamente registra o alias de next-intl → @intlayer/next-intl:

   next.config.ts

   Copiar conteúdo

   Copiar código

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

   import type { NextConfig } from "next";
   import { createNextIntlPlugin } from "@intlayer/next-intl/plugin";
   
   const withIntlayer = createNextIntlPlugin();
   
   const nextConfig: NextConfig = {
     /* Suas opções de configuração existentes */
   };
   
   export default withIntlayer(nextConfig);

   O createNextIntlPlugin() encapsula o withIntlayer, detecta automaticamente o Webpack ou o Turbopack, anexa o observador de conteúdo (watcher), pré-compila os dicionários e, mais importante, injetar aliases de módulos, para que as chamadas atuais ao import … from 'next-intl' redirecionem de maneira transparente ao @intlayer/next-intl em tempo de build. A importação de roteamento next-intl/routing continuará a apontar para o pacote real. Não é necessário mudar o código-fonte.

   Você prefere utilizar o plugin puro withIntlayer de next-intlayer/server? Ele compilará seus dicionários, mas não adicionará o alias para next-intl — dessa forma, será preciso renomear as importações para @intlayer/next-intl de forma manual (veja a Etapa 4).

   getRequestConfig ou carregar arquivos de mensagens não são mais necessários. Com o next-intl, você teria que criar um arquivo src/i18n.ts que carregava pacotes de mensagens JSON para cada requisição utilizando getRequestConfig. Como o Intlayer compila todos os dicionários no momento do build (build-time), não há uma etapa de carregamento de mensagens por requisição. Pode excluir com segurança esse arquivo (ou manter apenas as partes referentes ao roteamento, se você continuar usando createNavigation).

Isso é tudo para a migração rápida. Seu aplicativo agora está sendo executado no Intlayer, mantendo intatas as importações de next-intl e a API.

Chaves de tradução tipadas — automaticamente. Com a compilação de dicionários realizada pelo Intlayer, o useTranslations e getTranslations tornam-se tipados no seu conteúdo autêntico. As chaves receberão preenchimento automático (autocompletar) dentro do IDE e quaisquer caminhos que não estejam corretos acabarão apontando como erros do TypeScript no período de compilação — sem que haja a necessidade de uma configuração à parte para isso.

tsx

Copiar conteúdo

Copiar código

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

// Componente no lado cliente (Client component) — 'about' é uma chave configurada no dicionárioconst t = useTranslations("about");t("counter.label"); // ✓ autocompletart("does.not.exist"); // ✗ erro do TypeScript// Componente no lado servidor (Server component)const t = await getTranslations("about");t("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 wrapper createNextIntlPlugin() já realiza o apelido (aliasing) do next-intl → @intlayer/next-intl do lado do empacotador. Caso decida deixar evidente a dependência explícita dentro dos seus arquivos fonte (e em troca disso, utilizar o plugin padrão do withIntlayer puro), você poderá mudar as configurações de localidade com as suas próprias mãos:

   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 { useTranslations } from 'next-intl'	import { useTranslations } from '@intlayer/next-intl'
   import { useLocale } from 'next-intl'	import { useLocale } from '@intlayer/next-intl'
   import { NextIntlClientProvider } from 'next-intl'	import { NextIntlClientProvider } from '@intlayer/next-intl'
   import { getTranslations } from 'next-intl/server'	import { getTranslations } from '@intlayer/next-intl/server'
   import { getLocale } from 'next-intl/server'	import { getLocale } from '@intlayer/next-intl/server'
   import { setLocale } from 'next-intl/server'	import { setLocale } from '@intlayer/next-intl/server'
   import { getMessages } from 'next-intl/server'	import { getMessages } from '@intlayer/next-intl/server'

   Sempre preserve o que diz respeito às importações ligadas a rotas provindas diretamente do verdadeiro next-intl — o adaptador mantido para assegurar a compatibilidade não substitui o tratamento nas rotas da URL do next-intl:

   ts

   Copiar conteúdo

   Copiar código

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

   // ✅ Mantenha essas provindas do verdadeiro 'next-intl'import { createNavigation } from "next-intl/routing";import { createMiddleware } from "next-intl/server";import { defineRouting } from "next-intl/routing";

   Alternativamente, usar o defineRouting do @intlayer/next-intl/routing possibilita a inserção e mesclagem auto-gerada dos seus ambientes na intlayer.config.ts.

2. 5

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

   Opcional

   Logo que o sistema do Intlayer tiver sido devidamente ajustado, utilize a sua CLI (Interface de Linha de Comando) no intuito de inserir automaticamente os espaços em falta providenciados com o seu LLM (Large Language Model) predileto:

   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

   Acrescente o OPENAI_API_KEY (ou de quem você preferir) em seu registro .env local e prolongue/estenda também a base do seu arquivo 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: "icu",
         source: ({ locale }) => `./messages/${locale}.json`,
         location: "messages",
       }),
     ],
     ai: {
       apiKey: process.env.OPENAI_API_KEY,
       // provider: "openai",     // padrão
       // model: "gpt-4o-mini",   // padrão
     },
   };
   
   export default config;

   Dê uma lida atenta nos conteúdos incluídos na Documentação da CLI do Intlayer no propósito de verificar o leque inteiro em torno destas aberturas em seu dispor.

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

Logo que o @intlayer/next-intl estiver configurado, as estruturas do tipo boilerplate que dizem respeito ao seu app rodando next-intl podem então seguir rumo a exclusão:

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 about.content.ts ao lado do seu about/page.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 Next.js — Guia completo de configuração para Next.js: intlayerwithnextjs_16.md