next-i18next VS next-intl VS Intlayer | Next.js Internacionalização (i18n)

Abaixo está uma comparação concisa de três bibliotecas populares para internacionalização (i18n) de uma aplicação Next.js: next-intl, next-i18next e Intlayer.

Este documento destaca os critérios principais:

1. Arquitetura (mantendo as traduções próximas aos seus componentes)
2. Suporte a TypeScript
3. Gerenciamento de traduções ausentes
4. Suporte a Componentes de Servidor
5. Roteamento e middleware aprimorados para Next.js
6. Simplicidade de configuração

O guia também fornece uma análise aprofundada do Intlayer, mostrando por que pode ser uma escolha forte—especialmente para Next.js 13+, incluindo App Router e Componentes de Servidor.

---

Visão Geral de Cada Biblioteca

1. next-intl

Foco Principal: Configuração rápida e fácil com uma abordagem leve para localização.

• Arquitetura: Incentiva a co-localização de traduções em uma única pasta (por exemplo, locales/) mas também permite múltiplas estratégias. Não impõe estritamente uma arquitetura de “tradução por componente”.
• Suporte a TypeScript: Integração básica com TypeScript. Algumas definições de tipo existem, mas não estão fortemente centradas na auto-geração de definições TypeScript a partir de seus arquivos de tradução.
• Traduções Ausentes: Mecanismo de fallback básico. Por padrão, recai sobre uma chave ou uma string de locale padrão. Não há ferramentas robustas prontas para uso para checagens avançadas de traduções ausentes.
• Suporte a Componentes de Servidor: Funciona com Next.js 13+ em geral, mas o padrão é menos especializado para uso profundo do lado do servidor (por exemplo, componentes de servidor com roteamento dinâmico complexo).
• Roteamento & Middleware: O suporte a middleware é possível, mas limitado. Normalmente, depende do Middleware do Next.js para detecção de locale, ou configuração manual para reescrita de caminhos de locale.
• Simplicidade da Configuração: Muito direto. Mínimo boilerplate é necessário.

Use quando: Você deseja uma abordagem mais simples ou está confortável em gerenciar suas traduções de maneiras mais convencionais (como uma pasta com arquivos JSON de locale).

---

2. next-i18next

Foco Principal: Solução testada pelo tempo usando i18next sob o capô, amplamente adotada para projetos Next.js.

• Arquitetura: Geralmente organiza traduções na pasta public/locales. Não é especificamente projetado para manter traduções “próximas” a cada componente, embora você possa manualmente adotar uma estrutura diferente.
• Suporte a TypeScript: Cobertura razoável de TypeScript, mas requer configuração personalizada para traduções tipadas e hooks tipados.
• Traduções Ausentes: o i18next oferece interpolação/fallbacks. No entanto, a detecção de traduções ausentes geralmente precisa de configuração extra ou plugins de terceiros.
• Suporte a Componentes de Servidor: O uso básico com Next.js 13 é documentado, mas o uso avançado (por exemplo, integração profunda com componentes de servidor, geração de rotas dinâmicas) pode ser complicado.
• Roteamento & Middleware: Depende fortemente do Middleware do Next.js e reescritas para subcaminhos de locale. Para configurações mais complexas, você pode precisar mergulhar na configuração avançada do i18next.
• Simplicidade da Configuração: Abordagem familiar para aqueles acostumados ao i18next. No entanto, pode ficar mais pesado em boilerplate quando recursos avançados de i18n são necessários (namespaces, múltiplos locales de fallback, etc.).

Use quando: Você já está comprometido com o ecossistema i18next ou tem traduções existentes baseadas no i18next.

---

3. Intlayer

Foco Principal: Uma biblioteca moderna e open-source de i18n especificamente adaptada para App Router do Next.js (12, 13, 14 e 15) com suporte embutido para Componentes de Servidor e Turbopack.

Principais Vantagens

1. Arquitetura

   • Incentiva colocar traduções bem ao lado de seus componentes. Cada página ou componente pode ter seu próprio arquivo .content.ts (ou JSON)—sem mais vasculhar uma pasta de tradução gigante.
   • Isso torna seu código mais modular e manutenível, especialmente em grandes bases de código.

2. Suporte a TypeScript

   • Definições de tipo auto-geradas: No momento em que você define seu conteúdo, o Intlayer gera tipos que alimentam a conclusão automática e capturam erros de tradução.
   • Minimiza erros em tempo de execução, como chaves ausentes e oferece conclusão automática avançada diretamente em seu IDE.

3. Gerenciamento de Traduções Ausentes

   • Durante a construção, o Intlayer pode detectar chaves de tradução ausentes e gerar avisos ou erros.
   • Isso garante que você nunca envie acidentalmente traduções faltantes em seus idiomas.

4. Otimizado para Componentes de Servidor

   • Totalmente compatível com o App Router do Next.js e o novo paradigma de Componentes de Servidor.
   • Fornece provedores especializados (IntlayerServerProvider, IntlayerClientProvider) para isolar o contexto do servidor (vital ao lidar com Next.js 13+).

5. Roteamento e Middleware Aprimorados

   • Inclui um intlayerMiddleware dedicado para detecção automática de locale (via cookies ou cabeçalhos do navegador) e geração avançada de rotas.
   • Lida dinamicamente com caminhos localizados (por exemplo, /en-US/about vs. /fr/about) com configuração mínima.
   • Oferece métodos auxiliares como getMultilingualUrls para gerar links de idiomas alternativos (ótimo para SEO).

6. Configuração Simplificada

   • Um único arquivo de configuração (intlayer.config.ts) para definir seus locales, locale padrão e preferências de integração.
   • Um plugin wrapper withIntlayer(nextConfig) que injeta todas as variáveis de ambiente e observadores para seu conteúdo.
   • Sem grandes configurações de fallback—o sistema foi feito para "simplesmente funcionar" com mínima fricção.

Resumo: O Intlayer é uma solução moderna que deseja impulsionar as melhores práticas: desde manter traduções próximas a cada componente React, até oferecer suporte robusto a TS e uso fácil do lado do servidor, enquanto drasticamente reduz o boilerplate.

---

Comparação de Recursos Lado a Lado

---

Por que Intlayer?

Para equipes migrando ou construindo em cima do Next.js App Router (versões 13, 14 ou 15) com Componentes de Servidor, o Intlayer oferece:

1. Uma Arquitetura Simplificada

   • Cada rota ou componente contém suas próprias traduções. Isso promove clareza e manutenibilidade.

2. Integração Poderosa com TypeScript

   • Você ganha segurança a nível de compilador, evitando chaves de tradução "cheias de erros de digitação" ou ausentes.

3. Alertas Reais de Tradução Ausente

   • Se você esquecer uma chave ou tradução de idioma, será alertado em tempo de construção (em vez de enviar uma interface incompleta).

4. Roteamento Avançado Embutido

   • Detecção automática de locale, geração dinâmica de rotas e fácil gerenciamento de URLs localizadas estão incluídos.
   • Um intlayerMiddleware padrão não requer reescritas profundas de configuração.

5. Configuração de Um Parada Só

   • Mínimo boilerplate: basta definir seu intlayer.config.ts, envelopar next.config com withIntlayer, e adicionar o middleware oficial.
   • Uso claro e direto para ambos componentes de servidor e cliente via IntlayerServerProvider e IntlayerClientProvider.

6. Amigável para SEO

   • Helpers embutidos (getMultilingualUrls, atributos hrefLang, etc.) facilitam a produção de páginas e sitemaps compatíveis com SEO.

---

Exemplo: Intlayer em Ação

Abaixo está um snippet muito condensado ilustrando como aproveitar o Intlayer em um projeto Next.js 15. Para os detalhes completos e exemplos de código, confira o guia completo do Intlayer.

Exemplo passo a passo

1. Instalar & Configurar

   bash

   npm install intlayer next-intlayer

   ts

   // intlayer.config.tsimport { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],    defaultLocale: Locales.ENGLISH,  },};export default config;

2. Usar o Plugin

   ts

   // next.config.mjsimport { withIntlayer } from "next-intlayer/server";/** @type {import('next').NextConfig} */const nextConfig = {};export default withIntlayer(nextConfig);

3. Adicionar Middleware

   ts

   // src/middleware.tsexport { intlayerMiddleware as middleware } from "next-intlayer/middleware";export const config = {  matcher:    "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",};

4. Criar um Layout Localizado

   tsx

   // src/app/[locale]/layout.tsximport { getHTMLTextDir } from "intlayer";import { NextLayoutIntlayer } from "next-intlayer";const LocaleLayout: NextLayoutIntlayer = async ({ children, params }) => {  const { locale } = params;  return (    <html lang={locale} dir={getHTMLTextDir(locale)}>      <body>{children}</body>    </html>  );};export { generateStaticParams } from "next-intlayer";export default LocaleLayout;

5. Declarar & Usar Conteúdo

   tsx

   // src/app/[locale]/page.content.tsimport { t } from "intlayer";export default {  key: "page",  content: {    getStarted: {      main: t({        en: "Get started by editing",        fr: "Commencez par éditer",        es: "Comience por editar",      }),      pageLink: "src/app/page.tsx",    },  },};

   tsx

   // src/app/[locale]/page.tsximport { IntlayerServerProvider } from "next-intlayer/server";import { IntlayerClientProvider, useIntlayer } from "next-intlayer";const PageContent = () => {  const { content } = useIntlayer("page");  return (    <>      <p>{content.getStarted.main}</p>      <code>{content.getStarted.pageLink}</code>    </>  );};export default function Page({ params }) {  return (    <IntlayerServerProvider locale={params.locale}>      <IntlayerClientProvider locale={params.locale}>        <PageContent />      </IntlayerClientProvider>    </IntlayerServerProvider>  );}

---

Conclusão

Cada solução—next-intl, next-i18next e Intlayer—tem se mostrado eficaz para projetos multilíngues Next.js. No entanto, Intlayer vai mais longe:

• Incentivando fortemente uma arquitetura de tradução a nível de componente
• Integrando-se perfeitamente com Next.js 13+ e Componentes de Servidor
• Oferecendo poderosa auto-geração de TypeScript para código mais seguro
• Lidando com traduções ausentes em tempo de construção
• Fornecendo uma abordagem simplificada e de configuração única com roteamento e middleware avançados

Se você deseja recursos de i18n modernos adaptados ao App Router do Next.js e procura uma experiência totalmente tipada sem precisar manualmente de lógica de fallback, reescritas de rotas ou etapas de construção complexas, Intlayer é uma escolha atraente. Ele não apenas reduz seu tempo de configuração, mas também garante uma abordagem mais manutenível e escalável para traduções para sua equipe.