Localização React com i18next

Construir um aplicativo React para um público global requer uma estratégia robusta de internacionalização (i18n). O react-i18next é a biblioteca de localização React mais popular, construída sobre o framework i18next testado em batalha. Este guia orienta você por tudo o que precisa para localizar seu aplicativo React — desde a configuração inicial até a automação pronta para produção com tradução impulsionada por IA.

Por que escolher o react-i18next para Localização React?

O react-i18next é o padrão de fato para internacionalização React, confiado por milhares de aplicativos em produção em todo o mundo. Aqui está o porquê de os desenvolvedores o escolherem:

• API baseada em Hooks - O hook useTranslation() fornece uma integração React limpa e idiomática com re-renderização automática na mudança de idioma.
• Ecossistema Rico - Plugins para detecção de idioma, backends HTTP, cache e muito mais. Estenda a funcionalidade sem reinventar a roda.
• Formato de Tradução JSON - Usa arquivos JSON padrão que são fáceis de editar, controlar versões e integrar com ferramentas de tradução e serviços de IA.
• Suporte a Namespace - Organize traduções em grupos lógicos (auth, dashboard, erros) para melhor manutenção e carregamento lento (lazy loading).
• Pronto para SSR e Next.js - Funciona perfeitamente com renderização no lado do servidor, React Server Components e o Next.js App Router.
• Suporte a TypeScript - Segurança de tipo total para chaves de tradução com preenchimento automático, detectando chaves ausentes em tempo de compilação.

Instalação

Instale o react-i18next e a biblioteca principal i18next:

npm install react-i18next i18next

Plugins Opcionais

Esses plugins populares aprimoram sua configuração do i18next com detecção automática de idioma e traduções carregadas lentamente:

# Language detector (auto-detects user language)
npm install i18next-browser-languagedetector

# HTTP backend (load translations from server)
npm install i18next-http-backend

Estrutura de Projeto Recomendada

Uma estrutura de projeto bem organizada mantém suas traduções fáceis de manter à medida que você adiciona mais idiomas:

src/
├── i18n/
│   └── i18n.ts                  ← i18next configuration
├── locales/
│   ├── en/
│   │   └── translation.json     ← English (source)
│   ├── fr/
│   │   └── translation.json     ← French
│   ├── de/
│   │   └── translation.json     ← German
│   ├── ja/
│   │   └── translation.json     ← Japanese
│   └── es/
│       └── translation.json     ← Spanish
├── components/
├── App.tsx
└── index.tsx

Formato de Arquivo JSON de Tradução

O react-i18next usa arquivos JSON aninhados para traduções. As chaves suportam notação de pontos, interpolação com {{variáveis}} e pluralização integrada:

// locales/en/translation.json
{
  "welcome": {
    "title": "Welcome to our platform",
    "greeting": "Hello, {{name}}!",
    "description": "Explore features and get started."
  },
  "nav": {
    "home": "Home",
    "dashboard": "Dashboard",
    "settings": "Settings",
    "logout": "Log out"
  },
  "cart": {
    "empty": "Your cart is empty",
    "item_one": "{{count}} item in your cart",
    "item_other": "{{count}} items in your cart",
    "checkout": "Proceed to checkout"
  }
}

• Chaves Aninhadas - Organize traduções hierarquicamente (por exemplo, welcome.title, nav.home) para uma estrutura clara.
• Interpolação - Use a sintaxe {{variableName}} para valores dinâmicos que são inseridos em tempo de execução.
• Pluralização - Adicione sufixos _one e _other (ou _zero, _two, _few, _many para idiomas complexos) para manipulação automática de plural.
• Contexto - Use sufixos _male, _female para traduções específicas de gênero quando necessário.

Configurando o i18next

O i18next suporta duas abordagens principais para carregar traduções: backend HTTP (carregamento lento) e recursos agrupados. Escolha com base nas necessidades do seu aplicativo.

Backend HTTP (Recomendado para Aplicativos Grandes)

Carregue traduções sob demanda a partir de arquivos JSON no seu servidor. Isso mantém seu pacote inicial pequeno e é ideal para aplicativos com muitos idiomas ou arquivos de tradução grandes:

// src/i18n/i18n.ts
import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import LanguageDetector from "i18next-browser-languagedetector";
import HttpBackend from "i18next-http-backend";

i18n
  .use(HttpBackend)
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    fallbackLng: "en",
    supportedLngs: ["en", "fr", "de", "ja", "es"],
    defaultNS: "translation",
    interpolation: {
      escapeValue: false, // React already escapes by default
    },
    backend: {
      loadPath: "/locales/{{lng}}/{{ns}}.json",
    },
    detection: {
      order: ["localStorage", "navigator", "htmlTag"],
      caches: ["localStorage"],
    },
  });

export default i18n;

Recursos Agrupados (Abordagem Simples)

Importe traduções diretamente para o pacote. Melhor para aplicativos menores ou quando você precisa de traduções disponíveis imediatamente sem solicitações de rede:

// src/i18n/i18n.ts — Bundled approach (no HTTP backend)
import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import LanguageDetector from "i18next-browser-languagedetector";

import en from "../locales/en/translation.json";
import fr from "../locales/fr/translation.json";
import de from "../locales/de/translation.json";

i18n
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    fallbackLng: "en",
    supportedLngs: ["en", "fr", "de"],
    defaultNS: "translation",
    interpolation: {
      escapeValue: false,
    },
    resources: {
      en: { translation: en },
      fr: { translation: fr },
      de: { translation: de },
    },
  });

export default i18n;

Inicializando no seu Aplicativo

Importe o arquivo de configuração i18n no ponto de entrada do seu aplicativo antes de renderizar qualquer componente. Isso garante que as traduções sejam carregadas antes que sua UI seja renderizada:

// src/index.tsx
import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";
import "./i18n/i18n"; // Initialize i18next before rendering

const root = ReactDOM.createRoot(
  document.getElementById("root") as HTMLElement
);

root.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

Traduzindo Componentes React

O react-i18next fornece duas APIs principais para traduzir componentes: o hook useTranslation para acesso programático e o componente Trans para texto rico com JSX.

Hook useTranslation

O hook useTranslation é a maneira mais comum de acessar traduções em componentes funcionais. Ele fornece a função t() e re-renderiza automaticamente quando o idioma muda:

import { useTranslation } from "react-i18next";

function WelcomeBanner() {
  const { t } = useTranslation();

  return (
    <div>
      <h1>{t("welcome.title")}</h1>
      <p>{t("welcome.greeting", { name: "Alice" })}</p>
      <p>{t("welcome.description")}</p>
    </div>
  );
}

Componente Trans para Texto Rico

Quando as traduções contêm elementos HTML ou JSX (negrito, links, etc.), use o componente Trans. Ele preserva sua árvore de componentes React dentro das traduções:

import { Trans } from "react-i18next";

function RichTextExample() {
  return (
    <p>
      <Trans i18nKey="richText.welcome">
        Welcome to <strong>our platform</strong>.
        Visit your <a href="/dashboard">dashboard</a> to get started.
      </Trans>
    </p>
  );
}

// In the translation file:
// "richText.welcome": "Welcome to <1>our platform</1>. Visit your <3>dashboard</3> to get started."

Manipulando a Pluralização

O i18next lida com formas plurais automaticamente com base nas regras plurais ICU para cada idioma. Passe um parâmetro de contagem e o i18next seleciona a forma plural correta:

// In translation JSON:
// "cart.item_one": "{{count}} item in your cart"
// "cart.item_other": "{{count}} items in your cart"

import { useTranslation } from "react-i18next";

function CartSummary({ itemCount }: { itemCount: number }) {
  const { t } = useTranslation();

  return (
    <p>{t("cart.item", { count: itemCount })}</p>
  );
}

// itemCount=0 → "0 items in your cart"
// itemCount=1 → "1 item in your cart"
// itemCount=5 → "5 items in your cart"

• Adicione sufixos _one e _other às suas chaves de tradução para o inglês
• Para idiomas com regras plurais complexas (árabe, polonês, russo), adicione sufixos _zero, _two, _few, _many conforme necessário
• O i18next seleciona automaticamente a forma correta com base nas regras plurais CLDR do idioma de destino

Organizando com Namespaces

Namespaces permitem que você divida traduções em arquivos separados por recurso ou domínio. Isso melhora a manutenibilidade e permite o carregamento lento de pacotes de tradução:

// src/i18n/i18n.ts
i18n.init({
  defaultNS: "common",
  ns: ["common", "dashboard", "auth", "errors"],
  backend: {
    loadPath: "/locales/{{lng}}/{{ns}}.json",
  },
});

// Usage in components:
import { useTranslation } from "react-i18next";

function DashboardPage() {
  // Load specific namespace
  const { t } = useTranslation("dashboard");

  return <h1>{t("title")}</h1>;
}

function LoginForm() {
  // Load multiple namespaces
  const { t } = useTranslation(["auth", "common"]);

  return (
    <form>
      <h2>{t("auth:login.title")}</h2>
      <button>{t("common:submit")}</button>
    </form>
  );
}

Troca Dinâmica de Idioma

O react-i18next torna a troca de idioma perfeita. Chame i18n.changeLanguage() e todos os componentes que usam useTranslation re-renderizam automaticamente com o novo idioma:

import { useTranslation } from "react-i18next";

const LANGUAGES = [
  { code: "en", label: "English" },
  { code: "fr", label: "Français" },
  { code: "de", label: "Deutsch" },
  { code: "ja", label: "日本語" },
  { code: "es", label: "Español" },
];

function LanguageSwitcher() {
  const { i18n } = useTranslation();

  const changeLanguage = (lng: string) => {
    i18n.changeLanguage(lng);
  };

  return (
    <select
      value={i18n.language}
      onChange={(e) => changeLanguage(e.target.value)}
    >
      {LANGUAGES.map(({ code, label }) => (
        <option key={code} value={code}>
          {label}
        </option>
      ))}
    </select>
  );
}

React Suspense e Carregamento Lento

O react-i18next integra-se ao React Suspense para lidar com o carregamento assíncrono de tradução com elegância. Ao usar o backend HTTP, o Suspense fornece um estado de carregamento limpo enquanto as traduções são buscadas:

import { Suspense } from "react";
import { useTranslation } from "react-i18next";

// i18next supports React Suspense for async translation loading
function App() {
  return (
    <Suspense fallback={<div>Loading translations...</div>}>
      <MainContent />
    </Suspense>
  );
}

function MainContent() {
  const { t, ready } = useTranslation();

  // With Suspense, 'ready' is always true here
  return <h1>{t("welcome.title")}</h1>;
}

Chaves de Tradução com Segurança de Tipo TypeScript

O i18next suporta integração total com TypeScript. Ao aumentar o módulo i18next, você obtém preenchimento automático e verificação em tempo de compilação para todas as chaves de tradução — evitando erros de digitação e traduções ausentes:

// src/i18n/types.ts
import "i18next";
import translation from "../locales/en/translation.json";

declare module "i18next" {
  interface CustomTypeOptions {
    defaultNS: "translation";
    resources: {
      translation: typeof translation;
    };
  }
}

// Now t() calls are fully type-safe:
// t("welcome.title")       ✅ Autocomplete works
// t("welcome.greeting")    ✅ Valid key
// t("invalid.key")         ❌ TypeScript error

Renderização no Lado do Servidor com Next.js

Para aplicativos Next.js usando o App Router, você pode usar o i18next em componentes de servidor e cliente. Crie uma instância i18next separada para traduções no lado do servidor para evitar o compartilhamento de estado entre solicitações:

// next-i18next.config.js (Next.js App Router)
// For Next.js 13+ with App Router, use next-intl or i18next directly

// src/i18n/server.ts
import { createInstance } from "i18next";
import { initReactI18next } from "react-i18next/initReactI18next";

export async function getServerTranslation(lng: string) {
  const i18nInstance = createInstance();
  await i18nInstance.use(initReactI18next).init({
    lng,
    fallbackLng: "en",
    resources: {
      [lng]: {
        translation: (await import(`../locales/${lng}/translation.json`)).default,
      },
    },
  });
  return i18nInstance;
}

// In a Server Component:
export default async function Page({ params }: { params: { lng: string } }) {
  const i18n = await getServerTranslation(params.lng);
  const t = i18n.t.bind(i18n);

  return <h1>{t("welcome.title")}</h1>;
}

• Crie uma nova instância i18next por solicitação no servidor para evitar vazamento de estado entre usuários
• Use os mesmos arquivos JSON de tradução para renderização no lado do servidor e do cliente
• Considere i18next-resources-to-backend ou next-intl como alternativas para configurações complexas do Next.js

Acelere a Tradução com IA

Configurar o react-i18next é apenas metade da batalha — você ainda precisa de traduções de alta qualidade para cada idioma de destino. Traduzir manualmente dezenas de arquivos JSON é lento, caro e propenso a erros. A tradução impulsionada por IA muda o jogo.

Por que usar o l10n.dev para React i18next?

O l10n.dev é construído especificamente para fluxos de trabalho de localização de desenvolvedores. Ele entende seus arquivos de tradução JSON nativamente e produz traduções que parecem naturais, não geradas por máquina:

• Suporte nativo a JSON — Envie seu translation.json e receba arquivos JSON perfeitamente formatados e prontos para uso
• IA com consciência de contexto — Entende o domínio do seu aplicativo, preservando termos técnicos e a voz da marca em todos os idiomas
• Seguro para interpolação — Preserva {{variáveis}}, sufixos plurais (_one, _other) e estruturas de chaves aninhadas
• Tradução em lote — Traduza para mais de 10 idiomas simultaneamente em segundos, não em dias
• Integração CI/CD — Automatize traduções como parte do seu pipeline de build com o pacote npm ai-l10n

Fluxo de Trabalho de Tradução por IA

1. Escreva seu translation.json de origem em inglês (ou seu idioma base)
2. Envie para o l10n.dev ou execute a CLI ai-l10n para traduzir
3. A IA gera traduções contextualmente precisas para todos os idiomas de destino
4. Coloque os arquivos JSON traduzidos no seu diretório locales/ e implante

Automatize Traduções com a CLI ai-l10n

O pacote npm ai-l10n integra a tradução por IA diretamente no seu fluxo de trabalho de desenvolvimento. Traduza seus arquivos JSON a partir da linha de comando:

# Install the l10n.dev CLI
npm install ai-l10n

# Translate your JSON files to multiple languages at once
npx ai-l10n translate src/locales/en/translation.json \
  --languages fr,de,ja,es,ko,zh-CN

Integração de Build

Adicione automação de tradução ao seu pipeline de build para que as traduções estejam sempre atualizadas:

Scripts do package.json

{
  "scripts": {
    "translate": "ai-l10n translate src/locales/en/translation.json --languages fr,de,ja,es,ko --update",
    "pretranslate": "npm run translate",
    "dev": "vite",
    "build": "npm run translate && vite build"
  }
}

Makefile

LANGUAGES = fr,de,ja,es,ko,zh-CN

translate:
	npx ai-l10n translate src/locales/en/translation.json --languages $(LANGUAGES) --update

dev: translate
	npx vite

build: translate
	npx vite build

Para mais detalhes sobre integração CI/CD e automação, veja nosso Guia de Automação de Localização

Extensão VS Code para Tradução JSON

Traduza seus arquivos JSON do React i18next diretamente do VS Code. A extensão l10n.dev permite traduzir arquivos sem sair do seu editor:

Como Funciona

1. Instale a extensão l10n.dev do VS Code Marketplace
2. Abra seu arquivo translation.json de origem
3. Clique com o botão direito e selecione 'Translate with l10n.dev'
4. Escolha seus idiomas de destino e obtenha arquivos traduzidos instantaneamente

Comece a Localizar seu Aplicativo React Hoje

Você agora tem tudo o que precisa para construir um aplicativo React totalmente localizado com react-i18next. Combine o poder do ecossistema maduro do i18next com a tradução impulsionada por IA para enviar seu aplicativo em qualquer idioma, rapidamente.