PTC
Cadastrar-se Fazer upgrade para o Pro Sua conta

Como traduzir um aplicativo React com react-i18next

Configure o react-i18next, traduza en.json para 40+ idiomas com IA e, em seguida, deixe a extensão do navegador da PTC (Private Translation Cloud) revisar o aplicativo React em execução a cada lançamento. Este guia cobre a internacionalização do React de ponta a ponta: configuração do react-i18next, manipulação de plurais e conteúdo dinâmico, tradução do seu en.json para 40+ idiomas com a PTC e troca de idiomas em tempo de execução. Ao final, você terá uma configuração de localização do React funcionando e pronta para publicar. Para a visão geral da ferramenta independente de tradução de JSON, consulte traduzir arquivos JSON online com IA.

Como é um aplicativo React localizado

Um aplicativo React onde:

  • Todas as strings voltadas para o usuário ficam em arquivos de tradução JSON em src/i18n/locales/ (ou public/locales/).
  • Um seletor de idiomas alterna entre inglês, espanhol, francês e alemão.
  • O conteúdo dinâmico (nomes de usuários, contagens, datas) é interpolado corretamente por locale.
  • Os plurais seguem as regras de cada idioma de destino.
  • Os arquivos .json traduzidos são produzidos pela PTC, não escritos à mão.

Passo 1: Gerar a estrutura inicial de um aplicativo React + TypeScript com Vite

Este guia usa um aplicativo React + TypeScript construído com Vite. Se você estiver adicionando o react-i18next a um aplicativo existente, pule para o Passo 2.

npm create vite@latest react-localization-demo -- --template react-ts
cd react-localization-demo
npm install
npm run dev

Isso inicia um servidor de desenvolvimento e abre a página padrão do Vite + React no seu navegador.

Passo 2: Instalar o react-i18next e substituir as strings hardcoded por t()

npm install i18next react-i18next

Crie a estrutura de pastas i18n do seu React:

src/
  i18n/
    locales/
      en.json

Adicione suas strings em inglês ao src/i18n/locales/en.json:

{
  "welcome": "Welcome",
  "description": "This is a localization demo.",
  "clickMe": "Click me"
}

Um componente React típico com strings hardcoded:

function App() {
  return (
    <div>
      <h1>Welcome</h1>
      <p>This is a localization demo.</p>
      <button onClick={() => alert('Click me')}>Click me</button>
    </div>
  );
}

Substitua o texto hardcoded pelo hook useTranslation:

import { useTranslation } from 'react-i18next';

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

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('description')}</p>
      <button onClick={() => alert(t('clickMe'))}>{t('clickMe')}</button>
    </div>
  );
}

export default App;

useTranslation() retorna:

  • t() - busca uma string por chave.
  • i18n - permite que você mude de idioma programaticamente.

Passo 3: Carregar automaticamente cada JSON de locale com import.meta.glob

Crie src/i18n/index.ts para configurar o i18next e carregar automaticamente os arquivos de tradução. O padrão import.meta.glob significa que cada arquivo .json que você adiciona a src/i18n/locales/ é detectado automaticamente. Sem importações manuais ao adicionar novos idiomas:

import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';

type TranslationResources =
  | string
  | { [k: string]: TranslationResources }
  | TranslationResources[];

const modules = import.meta.glob<{ default: Record<string, TranslationResources> }>(
  './locales/*.json',
  { eager: true }
);

const resources: Record<string, { translation: Record<string, TranslationResources> }> = {};
for (const path in modules) {
  const lang = path.match(/\.\/locales\/(.*)\.json$/)?.[1];
  if (lang) {
    resources[lang] = { translation: modules[path].default };
  }
}

i18n
  .use(initReactI18next)
  .init({
    resources,
    fallbackLng: 'en',
    interpolation: { escapeValue: false },
  });

export default i18n;

Importe o i18n antes da renderização do seu aplicativo. Abra src/main.tsx e adicione a importação:

import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App.tsx';
import './index.css';
import './i18n'; // <- add this

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
);

Se você pular este passo, t() retornará as chaves de tradução em vez do texto traduzido.

Interpolar variáveis com {{variableName}}

Use a sintaxe {{variableName}} no seu JSON e passe o valor para t(). Atualize en.json:

{
  "welcome": "Welcome",
  "userGreeting": "Welcome back, {{firstName}}!",
  "description": "This is a localization demo.",
  "clickMe": "Click me"
}
const user = { firstName: 'Sarah' };
<p>{t('userGreeting', { firstName: user.firstName })}</p>

O segundo argumento para t() é um objeto com os valores que você deseja substituir. Quantas variáveis você precisar.

Pluralizar com os sufixos de chave _one / _other

Use o padrão de sufixo _one / _other. A variável deve se chamar count:

{
  "newMessages_one": "You have {{count}} new message.",
  "newMessages_other": "You have {{count}} new messages."
}
<p>{t('newMessages', { count: messageCount })}</p>

O i18next seleciona a forma plural correta automaticamente. Ele também lida com idiomas que têm mais de duas formas plurais (polonês, árabe, russo) sem configuração extra.

Para traduções contendo elementos HTML como links ou texto em negrito, use o componente Trans:

{
  "termsText": "I agree to the <1>Terms of Service</1> and <3>Privacy Policy</3>."
}

As tags <1> e <3> são placeholders baseados em índice que mapeiam para elementos filhos (contando a partir de 0):

import { Trans } from 'react-i18next';

<Trans i18nKey="termsText">
  I agree to the <a href="/terms">Terms of Service</a> and <a href="/privacy">Privacy Policy</a>.
</Trans>

Isso mantém seus elementos JSX no componente, ao mesmo tempo em que permite que os tradutores reordenem o texto ao redor naturalmente.

Formatar datas, números e moedas com Intl

Use os formatadores Intl em vez de incorporar strings de formato nas suas traduções:

const formatDate = (date: Date, locale: string) =>
  new Intl.DateTimeFormat(locale, { dateStyle: 'long' }).format(date);

const formatCurrency = (amount: number, locale: string, currency: string) =>
  new Intl.NumberFormat(locale, { style: 'currency', currency }).format(amount);

const { i18n } = useTranslation();
<p>{formatDate(new Date(), i18n.language)}</p>
<p>{formatCurrency(199.99, i18n.language, 'EUR')}</p>

Passo 5: Traduzir os arquivos JSON com a PTC em 5 passos

Agora você tem en.json e precisa produzir es.json, fr.json, de.json, etc. A PTC foi projetada exatamente para isso.

  1. Inicie um projeto na PTC e escolha o inglês como idioma de origem. O teste cobre 20.000 palavras em 2 idiomas, sem cartão de crédito.
  2. Faça o upload de en.json. A PTC analisa a estrutura aninhada, reconhece os placeholders do i18next ({{name}}, {{count}}) e detecta os sufixos plurais (_one, _other).
  3. Adicione uma breve descrição do seu aplicativo React e do seu público-alvo. A PTC usa esse contexto para adequar o tom e a terminologia em todos os idiomas.
  4. Escolha os idiomas de destino e confirme. A PTC produz um .json traduzido por idioma de destino, estruturalmente idêntico à origem. Mesmas chaves, mesmo aninhamento, mesmos placeholders. Valores traduzidos.
  5. Coloque os arquivos em src/i18n/locales/. Devido ao carregamento automático do import.meta.glob que você configurou no Passo 3, os novos arquivos funcionam imediatamente, sem alterações de código.

Depois de traduzir seu primeiro arquivo com a PTC, você pode passar para um processo automatizado. Conecte seu repositório do GitHub, GitLab ou Bitbucket via integração com Git, ou use a API da PTC para conectar a tradução ao seu pipeline de CI/CD. Novas strings em en.json acionam a tradução automática. A PTC abre um merge request com os arquivos atualizados nos idiomas de destino.

Passo 6: Verificar a configuração com um seletor de idiomas

Adicione botões de idioma para verificar se a sua configuração do react-i18next está funcionando:

import { useTranslation } from 'react-i18next';

function App() {
  const { t, i18n } = useTranslation();

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <button onClick={() => i18n.changeLanguage('en')}>EN</button>
      <button onClick={() => i18n.changeLanguage('fr')}>FR</button>
    </div>
  );
}

i18n.changeLanguage() aciona uma nova renderização de cada componente usando useTranslation(), de modo que toda a UI é atualizada imediatamente. Sem recarregar a página.

Detectar automaticamente o idioma do usuário com i18next-browser-languagedetector

Instale i18next-browser-languagedetector para carregar automaticamente o idioma correto a partir das configurações do navegador do usuário, URL ou preferências salvas:

npm install i18next-browser-languagedetector
import LanguageDetector from 'i18next-browser-languagedetector';

i18n
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    resources,
    fallbackLng: 'en',
    supportedLngs: ['en', 'fr', 'de', 'ar'],
    interpolation: { escapeValue: false },
    detection: {
      order: ['querystring', 'localStorage', 'cookie', 'navigator'],
      caches: ['localStorage', 'cookie'],
    },
  });

Carregue as traduções sob demanda com i18next-http-backend

Por padrão, todos os arquivos de tradução são incluídos no bundle no momento do build. Para aplicativos com muitos idiomas, use i18next-http-backend para buscar apenas o idioma que o usuário realmente precisa:

npm install i18next-http-backend
import Backend from 'i18next-http-backend';

i18n
  .use(Backend)
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    fallbackLng: 'en',
    supportedLngs: ['en', 'fr'],
    interpolation: { escapeValue: false },
    backend: { loadPath: '/locales/{{lng}}/{{ns}}.json' },
  });

Mova seus arquivos de tradução para public/locales/ para que sejam servidos como recursos estáticos:

public/
  locales/
    en/translation.json
    fr/translation.json

Mudar para o francês agora busca /locales/fr/translation.json sob demanda em vez de incluí-lo no bundle. O bundle inicial permanece enxuto, independentemente de quantos idiomas você suporta.

Revisão visual de tradução do seu aplicativo React em execução - publique sem QA manual por lançamento

Depois que a PTC traduzir seu en.json, você ainda precisa verificar o aplicativo React em execução. Um rótulo traduzido pode causar um estouro em um botão em alemão. “Save” pode ser traduzido como um substantivo em francês quando a UI precisava de um verbo. Uma string hardcoded em inglês fora de t() será renderizada sem tradução, independentemente de quantos idiomas você publicar.

O AI Visual QA da PTC substitui o passe de QA manual. Para aplicativos baseados em navegador como o React, a variante certa é a extensão do navegador. Instale-a uma vez e crie um curto percurso gravado dos fluxos de usuário críticos do seu aplicativo React (login, recurso principal, configurações). A partir de então, a PTC reproduz a gravação em cada idioma de destino após cada atualização de tradução, faz a captura de cada tela e inspeciona o resultado renderizado:

  • Correções nos arquivos de tradução quando a PTC os controla. A PTC retraduz uma classe gramatical errada, escolhe um sinônimo mais curto que caiba em um botão, regenera uma forma plural.
  • Prompts do Cursor / Claude Code quando o problema está no código do seu componente. Uma string hardcoded em inglês fora de t(), uma frase construída por concatenação de strings em vez de t('key', { var }), um componente Trans ausente para traduções de rich-text.

O resultado: revisão-como-etapa-de-CI. Cada lançamento é publicado com verificação visual em todos os idiomas de destino, sem gargalos humanos.

Traduzir notas de lançamento, páginas de marketing e e-mails de clientes

Suas notas de lançamento, páginas de marketing, landing pages e e-mails de clientes ficam fora de en.json. O Paste to Translate da PTC lida com esse texto no mesmo projeto. Cole o texto de origem no painel da PTC, escolha os idiomas de destino e receba traduções que usam o mesmo glossário e a mesma voz da marca que as suas strings de UI do React.

Traduzir comentários de usuários, postagens e resultados de pesquisa com a API da PTC

Comentários de usuários, postagens, resultados de pesquisa e qualquer outro conteúdo gerado pelo usuário com o qual o seu aplicativo React lida precisam de tradução assim que chegam. A API REST da PTC traduz esse conteúdo sob demanda com autenticação por token Bearer, usando o mesmo glossário e a mesma voz da marca que as suas traduções de en.json.

Agora traduza o seu arquivo en.json

Comece seu teste de 30 dias - 20.000 palavras em 2 idiomas, sem cartão de crédito. Dois caminhos:

  • Manual: faça o upload de src/i18n/locales/en.json na página de tradução de JSON.
  • Orientado por CI: conecte seu repositório Git via API da PTC e as traduções acontecem automaticamente a cada push.

De qualquer forma, instale a extensão do navegador e deixe o AI Visual QA verificar o seu aplicativo React em execução em todos os idiomas antes de você publicar.