PTC
Cadastrar-se Fazer upgrade para o Pro Sua conta

Como traduzir um aplicativo React com a react-i18next

Configure a react-i18next, traduza en.json para mais de 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 abrange a internacionalização do React de ponta a ponta: configurar a react-i18next, lidar com plurais e conteúdo dinâmico, traduzir seus en.json para mais de 40 idiomas com a PTC e alternar idiomas em tempo de execução. Ao final, você terá uma configuração de localização do React funcionando e pronta para ser lançada. Para obter uma 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, e não escritos à mão.

Etapa 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 a react-i18next a um aplicativo existente, pule para a Etapa 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.

Etapa 2: Instalar a react-i18next e substituir 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;

O useTranslation() retorna:

  • t() - busca uma string por chave.
  • i18n - permite que você altere os idiomas de forma programática.

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

Crie o src/i18n/index.ts para configurar a i18next e carregar automaticamente os arquivos de tradução. O padrão import.meta.glob significa que cada arquivo .json que você adicionar a src/i18n/locales/ será detectado automaticamente. Não são necessárias 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 a i18n antes que o seu aplicativo seja renderizado. Abra o 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 esta etapa, o t() retornará 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 o 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. Você pode usar quantas variáveis precisar.

Pluralizar com chaves com sufixo _one / _other

Use o padrão de sufixo _one / _other. A variável deve ser nomeada como count:

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

A i18next seleciona a forma plural correta automaticamente. Ela também lida com idiomas com 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 e, ao mesmo tempo, permite que os tradutores reordenem o texto ao redor de forma natural.

Formatar datas, números e moedas com Intl

Use os formatadores Intl em vez de incorporar strings de formato em 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>

Etapa 5: Traduza os arquivos JSON com a PTC em 5 passos

Agora você tem o en.json e precisa produzir o 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 do en.json. A PTC analisa a estrutura aninhada, reconhece os placeholders do i18next ({{name}}, {{count}}) e detecta os sufixos de plural (_one, _other).
  3. Adicione uma breve descrição do seu aplicativo React e do seu público. 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 à fonte. 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 o seu primeiro arquivo com a PTC, você pode passar para um processo automatizado. Conecte o seu repositório do GitHub, GitLab ou Bitbucket por meio da integração com Git, ou use a API da PTC para conectar a tradução ao seu pipeline de CI/CD. Novas strings no en.json acionam a tradução automática. A PTC abre um merge request com os arquivos atualizados nos idiomas de destino.

Etapa 6: Verifique 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>
  );
}

O i18n.changeLanguage() aciona uma nova renderização de todos os componentes que usam useTranslation(), para que toda a UI seja atualizada imediatamente. Sem recarregamento de página.

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

Instale o i18next-browser-languagedetector para carregar automaticamente o idioma correto a partir das configurações do navegador do usuário, da URL ou das 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'],
    },
  });

Faça o carregamento sob demanda das traduções com o i18next-http-backend

Por padrão, todos os arquivos de tradução são incluídos no bundle no momento da compilação. Para aplicativos com muitos idiomas, use o i18next-http-backend para buscar apenas o idioma de 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 os seus arquivos de tradução para public/locales/ para que eles sejam servidos como recursos estáticos:

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

Mudar para o francês agora busca o /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 - lance sem QA manual a cada lançamento

Depois que a PTC traduzir o 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 do t() será renderizada sem tradução, independentemente de quantos idiomas você lançar.

O AI Visual QA da PTC substitui a execução de QA manual. Para aplicativos baseados em navegador como o React, a variante certa é a extensão do navegador. Instale-a uma vez e registre um percurso gravado curto 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 todos os idiomas de destino após cada atualização de tradução, captura 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 do 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 é enviado com verificação visual em todos os idiomas de destino, sem gargalos humanos.

Traduza 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 do en.json. A 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 de volta traduções que usam o mesmo glossário e voz da marca que as suas strings de UI do React.

Traduza 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 que o seu aplicativo React manipula 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 voz da marca que as suas traduções do en.json.

Agora traduza o seu arquivo en.json

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

  • Manual: faça o upload do src/i18n/locales/en.json na página de tradução de JSON.
  • Orientado por CI: conecte o seu repositório Git por meio da API da PTC e um push que altera as suas strings de origem volta traduzido.

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ê lançar.