Como Traduzir Arquivos JSON i18next no React e Next.js (2026)

Você acabou de finalizar um aplicativo React que precisa ser lançado em 12 idiomas até a próxima sexta-feira. Seus arquivos de localização estão em public/locales/en/common.json, você tem 340 chaves por localidade, e os tokens dentro de suas strings se parecem com {{userName}} e {{count}} espalhados por objetos aninhados. Você cola o JSON no ChatGPT, e ele retorna com {{ nombreUsuario }}, espaços extras e metade das chaves de pluralização renomeadas. Seu aplicativo falha na compilação.

Se você já tentou automatizar a tradução JSON i18next, conhece essa dor. O formato JSON é flexível, e é exatamente por isso que a maioria das ferramentas de tradução o danifica. O verdadeiro problema não é a qualidade do modelo de linguagem - é que as ferramentas de IA de nível de consumidor não entendem as regras estruturais do i18next.

Este guia explica o que torna o JSON i18next diferente de outros formatos de localidade, por que abordagens de tradução ingênuas quebram aplicativos React e Next.js, e como automatizar a tradução com segurança em dezenas de localidades sem revisar manualmente cada chave.

O Que É JSON i18next e Por Que a Tradução É Complicada

i18next é a biblioteca i18n mais amplamente utilizada no ecossistema JavaScript. Ele alimenta o React (react-i18next), Next.js (next-i18next, App Router next-intl), Vue e serviços de backend Node. Ele armazena strings traduzíveis em arquivos JSON planos ou aninhados, um por localidade.

Um arquivo típico se parece com isto:

{
  "welcome": "Welcome, {{userName}}!",
  "cart": {
    "empty": "Your cart is empty",
    "items_one": "{{count}} item in your cart",
    "items_other": "{{count}} items in your cart"
  },
  "errors": {
    "network": "Network error. <strong>Please retry</strong>."
  }
}

Isso parece simples, mas três coisas tornam perigoso traduzir com IA de propósito geral.

Tokens de Interpolação São Estruturais, Não Texto

A sequência {{userName}} não é uma palavra - é um espaço reservado que o runtime substitui por dados. Adicione um espaço ({{ userName }}), renomeie-o ou traduza o identificador interno e o runtime falhará silenciosamente ou lançará um erro. Alguns tradutores convertem útilmente {{count}} para {{conteo}} em espanhol. Seu aplicativo agora tenta interpolar uma variável que não existe e renderiza o placeholder bruto para o seu usuário.

Chaves de Pluralização São Sufixos Mágicos

i18next detecta plurais por sufixos: _zero, _one, _two, _few, _many, _other. Estas não são strings arbitrárias - elas devem corresponder às categorias de plural CLDR para a localidade de destino. O inglês usa apenas _one e _other. Russo, árabe e polonês usam até seis categorias. Se o seu tradutor omitir _other ou o renomear, a cadeia de fallback é quebrada.

Chaves Aninhadas Devem Permanecer Intactas

Ao contrário dos arquivos .po do Gettext, que são pares chave-valor planos, os arquivos i18next podem ser aninhados arbitrariamente. Um tradutor preguiçoso pode nivelar a estrutura, alterar nomes de chaves para corresponder ao texto traduzido ou reordenar objetos. Sua chamada t('cart.items_other') no código não se resolve mais.

Soluções Ruins Que Desenvolvedores Tentam Primeiro

Toda equipe passa pelo mesmo ciclo de falha em três estágios antes de investir em uma solução real.

Estágio Um: Colar no ChatGPT

Você copia 200 chaves para o ChatGPT, pergunta "traduza este JSON para o espanhol" e cola o resultado de volta. Funciona para 180 chaves. Vinte têm espaços adicionados dentro de {{...}}, três têm sufixos de plural reescritos e uma tag <strong> foi traduzida para <fuerte>. Sua compilação falha ou envia strings silenciosamente quebradas para produção.

Estágio Dois: API do Google Translate

Você conecta a API REST do Google Translate, itera sobre seu JSON e envia cada valor. A velocidade é ótima. A qualidade não. A API do Google trata cada string isoladamente - sem contexto sobre seu aplicativo, sem entender que {{count}} é um placeholder, sem a consciência de que a chave cart.empty é diferente de cart.items_one. Você ainda precisa de revisão humana em cada chave.

Estágio Três: Plataformas TMS Comerciais

Você se inscreve em um sistema de gerenciamento de tradução. Eles cobram por palavra, exigem integrações com o GitHub e o prendem a licenças mensais. Para um projeto paralelo ou um aplicativo independente, a economia desmorona rapidamente - e você ainda enfrenta os mesmos problemas de corrupção de placeholders se o motor deles não analisar o formato i18next especificamente.

Os mesmos modos de falha aparecem também nos fluxos de trabalho do Gettext. Nosso guia sobre como traduzir arquivos .po sem quebrar variáveis de código aborda o problema paralelo para WordPress e outras pilhas baseadas em Gettext.

A Abordagem Segura: Tradução Sensível à Sintaxe

A única maneira confiável de traduzir JSON i18next em escala é com uma ferramenta que analisa o formato primeiro, bloqueia a sintaxe e envia apenas o texto traduzível para a IA.

Aqui está o que o processamento sensível à sintaxe faz nos bastidores:

1. Analisa o JSON em uma árvore abstrata, preservando caminhos de chaves e aninhamento.
2. Identifica tokens de interpolação ({{name}}, {{count, number}}, {{date, datetime}}) e os substitui por IDs de placeholder.
3. Identifica tags HTML dentro de componentes Trans (<0>, <strong>, <br/>) e as bloqueia.
4. Detecta chaves de plural por sufixo e as mapeia para as regras CLDR da localidade de destino.
5. Envia apenas o texto limpo para o LLM com contexto sobre o caminho da chave.
6. Reinsere os tokens e tags originais em suas posições exatas.
7. Valida a saída - se algum placeholder estiver faltando ou malformado, reverte para a origem.

Este é o mesmo princípio que torna a tradução PO baseada em nuvem segura. Se você estiver curioso sobre a arquitetura subjacente, nossa comparação de qualidade de tradução por IA detalha como diferentes LLMs lidam com essas restrições.

Passo a Passo: Traduza JSON i18next com SimplePoTranslate

SimplePoTranslate suporta JSON i18next nativamente nos planos Pro e Lifetime. A camada gratuita atualmente cobre .po e .pot - atualize ou use uma avaliação para acessar JSON.

1. Prepare Seu Arquivo Fonte

Use seu arquivo em inglês (ou localidade fonte) como mestre. Certifique-se de que é um JSON válido e contém todas as chaves que seu aplicativo usa. Um erro comum é deixar chaves obsoletas ou não utilizadas, o que consome sua cota de tradução para strings que você nunca irá renderizar.

# From your project root
cp public/locales/en/common.json ~/Desktop/common.json

2. Carregue para o SimplePoTranslate

Faça login no seu painel, clique em Nova Tradução e carregue common.json. A plataforma detecta automaticamente o formato i18next. Escolha seu idioma de destino entre as 41 localidades suportadas, selecione um tom (profissional, casual, marketing) e envie.

3. Deixe o Motor Trabalhar

Nos bastidores, o arquivo é analisado, dividido em lotes seguros e traduzido em paralelo. Os tokens de interpolação são bloqueados. Os sufixos de plural são preservados e mapeados para as regras CLDR da localidade de destino. O HTML dentro dos componentes Trans permanece intacto.

4. Baixe o ZIP

Você recebe um ZIP contendo o JSON traduzido mais formatos alternativos (.php para aplicativos PHP, .po para compatibilidade entre ferramentas). Solte o JSON em public/locales/es/common.json e faça o redeploy.

unzip common_es.zip
mv common.json public/locales/es/common.json
npm run build

5. Repita ou Loteie

Para todas as 12 localidades de destino, envie 12 trabalhos. As cotas do plano Pro cobrem dezenas de aplicativos SaaS típicos. Para monorepos com vários arquivos de namespace, carregue cada um separadamente ou os loteie sequencialmente.

Integrando Traduções de Volta ao Seu Aplicativo

Uma vez que você tenha os arquivos JSON traduzidos, a integração é a parte fácil. Algumas observações:

• Verifique as categorias de plural. Faça um teste rápido por localidade: renderize um componente com count={0}, count={1}, count={5} e confirme que todos os três produzem a string correta.
• Verifique as localidades RTL. Se você traduziu para árabe, hebraico ou persa, sua UI precisa de CSS com suporte a RTL. Nosso guia de tradução RTL para WordPress cobre os padrões CSS que se aplicam também a aplicativos React.
• Configure uma cadeia de fallback. Configure o i18next para retornar ao inglês se uma chave estiver faltando, para que os estados de meio de implantação não causem falhas aos usuários.
• Bloqueie seu arquivo fonte no CI. Adicione uma verificação que rejeita PRs onde en/common.json muda sem regenerar outras localidades. O desvio de tradução é a maior causa única de bugs i18n em produção.

Para equipes que implementam em React, Next.js e no lado do servidor, produzir todos os formatos a partir de uma única fonte é uma enorme vitória. Nosso post sobre um arquivo de entrada, cinco formatos de saída explica por que a saída multi-formato é importante para a manutenção a longo prazo.

Quando JSON Não É Suficiente: Lidando Com Casos Complexos

Alguns casos extremos precisam de atenção extra.

ICU MessageFormat

Se seu projeto usa sintaxe ICU ({count, plural, one {1 item} other {# items}}), o i18next o trata como interpolação, mas a estrutura é mais complexa. Certifique-se de que sua ferramenta de tradução reconhece os parâmetros ICU e não traduz nomes de categorias como one, other, ou identificadores de formato como plural, number, date.

Componente Trans com Nós React

<Trans> renderiza componentes React dentro de strings traduzidas, indexados por (<0>, <1>). O tradutor deve preservar a ordem exata das tags. O bloqueio de sintaxe do SimplePoTranslate lida com isso, mas se você usar uma ferramenta diferente, verifique antes de enviar.

Arquivos de Namespace

Grandes aplicativos dividem localidades em namespaces: common.json, dashboard.json, checkout.json. Traduza cada arquivo independentemente - não os mescle. A qualidade do contexto é maior quando os caminhos de chave de cada namespace permanecem dentro do escopo.

Juntando Tudo

Traduzir JSON i18next para um aplicativo React ou Next.js não é sobre escolher o melhor modelo de IA. É sobre respeitar as regras estruturais do formato: interpolações, sufixos de plural, chaves aninhadas e tags HTML devem sobreviver à viagem de ida e volta. Ferramentas de IA de consumidor tratam JSON como texto não estruturado. Ferramentas sensíveis à sintaxe o analisam como dados estruturados e tocam apenas nas superfícies traduzíveis.

Se você está lançando um aplicativo multilíngue e tem copiado e colado JSON em interfaces de chat, você já conhece o custo: horas de revisão manual por localidade, bugs aleatórios em produção e uma pilha crescente de formas de plural quebradas. Um pipeline consciente do formato remove cada um desses modos de falha.

Pronto para traduzir seus arquivos JSON i18next com segurança? Experimente o SimplePoTranslate gratuitamente - sem necessidade de cartão de crédito. Faça o upload uma vez, distribua em 41 idiomas.