Localização em React com i18next

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

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

O react-i18next é o padrão de fato para internacionalização em React, confiável para milhares de aplicações em produção ao redor do mundo. Eis por que os desenvolvedores o escolhem:

• API focada em Hooks - O hook useTranslation() fornece uma integração limpa e idiomática com o React, com renderização automática ao alterar o 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 - Utiliza arquivos JSON padrão que são fáceis de editar, versionar e integrar com ferramentas de tradução e serviços de IA.
• Suporte a Namespaces - Organize traduções em grupos lógicos (auth, dashboard, errors) para melhor manutenibilidade e carregamento sob demanda (lazy loading).
• Pronto para SSR e Next.js - Funciona perfeitamente com renderização no lado do servidor, React Server Components e o App Router do Next.js.
• Suporte a TypeScript - Segurança total de tipos 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 carregamento de traduções sob demanda:

# 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 ponto, 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 (ex.: welcome.title, nav.home) para uma estrutura clara.
• Interpolação - Use a sintaxe {{nomeDaVariavel}} 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 tratamento automático de plurais.
• 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 sob demanda) e recursos agrupados (bundled). Escolha com base nas necessidades da sua aplicação.

Backend HTTP (Recomendado para grandes aplicações)

Carregue traduções sob demanda a partir de arquivos JSON no seu servidor. Isso mantém seu bundle inicial pequeno e é ideal para aplicações 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 bundle. Melhor para aplicações menores ou quando você precisa que as traduções estejam disponíveis imediatamente sem requisiçõ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 na sua aplicação

Importe o arquivo de configuração do i18n no ponto de entrada da sua aplicação antes de renderizar qualquer componente. Isso garante que as traduções sejam carregadas antes da renderização da interface:

// 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 forma mais comum de acessar traduções em componentes funcionais. Ele fornece a função t() e renderiza novamente de forma automática quando o idioma é alterado:

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."

Tratando a pluralização

O i18next lida com formas plurais automaticamente com base nas regras de plural do ICU para cada idioma. Passe um parâmetro de contagem (count), 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 os sufixos _one e _other às suas chaves de tradução para inglês
• Para idiomas com regras de plural 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 de plural CLDR do idioma de destino

Organizando com Namespaces

Namespaces permitem dividir traduções em arquivos separados por funcionalidade ou domínio. Isso melhora a manutenibilidade e permite o carregamento sob demanda 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 algo fluido. Chame i18n.changeLanguage() e todos os componentes que usam useTranslation renderizarão novamente de forma automática 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 sob demanda

O react-i18next integra-se ao React Suspense para lidar com o carregamento assíncrono de traduções de forma elegante. 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 tipos (TypeScript)

O i18next suporta integração total com TypeScript. Ao estender 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 chaves 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 aplicações Next.js usando o App Router, você pode usar o i18next tanto em componentes de servidor quanto de cliente. Crie uma instância separada do i18next para traduções no lado do servidor para evitar o compartilhamento de estado entre requisiçõ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 do i18next por requisição no servidor para evitar vazamento de estado entre usuários
• Use os mesmos arquivos JSON de tradução para renderização no servidor e no cliente
• Considere o i18next-resources-to-backend ou next-intl como alternativas para configurações complexas de Next.js

Acelere a tradução com IA

Configurar o react-i18next é apenas metade do caminho — 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 assistida por IA muda o jogo.

Por que usar o l10n.dev para o react-i18next?

O l10n.dev foi criado especificamente para fluxos de trabalho de localização de desenvolvedores. Ele entende seus arquivos de tradução JSON nativamente e produz traduções que soam naturais, não geradas por máquinas:

• Suporte nativo a JSON — Envie seu translation.json e receba de volta arquivos JSON perfeitamente formatados e prontos para uso
• IA com consciência de contexto — Entende o domínio da sua aplicação, preservando termos técnicos e a voz da marca em todos os idiomas
• Seguro para interpolação — Preserva {{variáveis}}, sufixos de plural (_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 com IA

1. Escreva seu translation.json original 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 faça o deploy

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 pela 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 a 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 do VS Code para tradução de 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 a partir do VS Code Marketplace
2. Abra seu arquivo de tradução translation.json original
3. Clique com o botão direito e selecione 'Translate with l10n.dev'
4. Escolha seus idiomas de destino e obtenha os arquivos traduzidos instantaneamente

Comece a localizar sua aplicação React hoje

Você agora tem tudo o que precisa para construir uma aplicação React totalmente localizada com o react-i18next. Combine o poder do ecossistema maduro do i18next com a tradução assistida por IA para lançar sua aplicação em qualquer idioma, rapidamente.