Como traduzir um arquivo JSON para outro idioma

Para traduzir um arquivo de idioma JSON, envie o arquivo de origem, informe o idioma de destino e traduza os valores de texto. Comece com um arquivo pequeno no tradutor JSON gratuito e confira o arquivo resultante no seu app. Você pode baixar o exemplo usado aqui.

Este guia é voltado para strings de apps, como locales/en.json. Se o arquivo contiver um catálogo de produtos ou registros de API, defina quais campos contêm texto legível antes de seguir o mesmo fluxo de trabalho. Um identificador armazenado como string continua sendo um identificador.

Experimente primeiro estas seis strings

O exemplo contém uma tela de checkout e dois rótulos de configuração:

{
  "checkout": {
    "title": "Your order",
    "greeting": "Hello, {{name}}",
    "pay": "Pay now",
    "support": "Contact Pinecart support"
  },
  "settings": {
    "language": "Language",
    "notifications": "Email notifications"
  }
}

Envie o arquivo para a ferramenta JSON e informe:

Translate every text value into French.
Keep Pinecart in English and preserve {{name}} exactly.

A ferramenta gratuita aceita arquivos de até 2 MB, cinco por dia, e traduz até 5.000 palavras por arquivo. Arquivos maiores são devolvidos completos, com o texto restante inalterado. Assim, o download serve como exemplo, mas não corresponde a uma localidade totalmente traduzida. Use o app para traduzir um arquivo grande por completo, usar um glossário do espaço de trabalho e repetir versões.

Saiba quais partes fazem parte do seu app

O aplicativo chama checkout.title; quem lê vê o valor correspondente. A variável de nome é preenchida em tempo de execução. Ambos precisam ser preservados ao mudar de idioma.

O AI Glot lê o JSON como uma estrutura e o grava novamente com recuo de dois espaços. Por isso, um diff pode incluir alterações de espaços em branco. Revise os valores separadamente da formatação.

Defina a convenção dos placeholders. O exemplo usa o formato {{name}}, como no i18next. Outros projetos usam {name}, %s ou mensagens ICU. Ao escrever a instrução, copie uma string real do seu app. Não converta uma convenção em outra durante a tradução.

Confira o plano antes de um trabalho grande

Para lançamentos recorrentes, use um glossário do workspace para termos do produto e nomes de recursos. As instruções de escopo definem quais valores serão traduzidos; as regras de redação definem como cada valor será escrito.

Um en.json que contém apenas o texto-fonte não informa quais rótulos em francês foram traduzidos no mês passado. Pedir para “traduzir apenas as strings em francês que estão faltando” não fornece um arquivo em francês para comparação. Exclua prefixos de chave conhecidos ou prepare os campos de origem e destino juntos e confira a interpretação do plano. O guia de arquivos de idioma de apps aborda o fluxo de trabalho mais amplo e outros formatos.

Faça uma verificação estrutural antes de confirmar as alterações

Salve o arquivo baixado como fr.json, ao lado de en.json. Copie este código para check-locale.mjs e execute node check-locale.mjs com o Node.js. Ele verifica as chaves de objetos aninhados, os comprimentos dos arrays, os tipos de valores, os valores não textuais que devem permanecer inalterados e os placeholders de chaves duplas do exemplo.

import { readFileSync } from 'node:fs';
import assert from 'node:assert/strict';

const source = JSON.parse(readFileSync('en.json', 'utf8'));
const target = JSON.parse(readFileSync('fr.json', 'utf8'));
const tokens = text => [...text.matchAll(/\{\{[^{}]+\}\}/g)]
  .map(match => match[0]).sort();

function check(a, b, path = '$') {
  assert.equal(typeof b, typeof a, `${path}: value type changed`);
  if (a === null || typeof a !== 'object') {
    if (typeof a === 'string') {
      assert.ok(b.trim().length || !a.trim().length,
        `${path}: translation is empty`);
      assert.deepEqual(tokens(b), tokens(a),
        `${path}: placeholders changed`);
    } else {
      assert.deepEqual(b, a, `${path}: non-text value changed`);
    }
    return;
  }
  assert.equal(Array.isArray(b), Array.isArray(a),
    `${path}: container type changed`);
  assert.ok(b !== null, `${path}: container is null`);
  if (Array.isArray(a)) {
    assert.equal(b.length, a.length, `${path}: array length changed`);
  }
  assert.deepEqual(Object.keys(b).sort(), Object.keys(a).sort(),
    `${path}: keys changed`);
  for (const key of Object.keys(a)) check(a[key], b[key], `${path}.${key}`);
}

check(source, target);
console.log('Keys, types and {{placeholders}} match. Review the wording next.');

Isso valida um contrato, não a qualidade da tradução. Um valor que permanece em inglês ainda passa na validação. O mesmo vale para uma tradução com erros gramaticais ou longa demais para o botão. A regra de tokens abrange {{name}}, mas não todos os formatos de placeholders. Adapte-a à sintaxe do seu aplicativo.

No i18next JSON v4, as variantes de plural usam sufixos específicos de cada idioma, e suas chamadas fornecem uma contagem. Prepare e teste as chaves necessárias para o idioma de destino. Esta verificação de igualdade de chaves rejeita deliberadamente qualquer alteração no conjunto de chaves; ela não gera nem valida um novo conjunto de formas de plural.

Finalize dentro do aplicativo

Configure o carregador de localidade em francês que seu app já usa para apontar para fr.json. Abra o checkout, insira um nome real e confira o botão mais longo na menor largura de tela compatível. Se usar plurais, teste contagens que acionem cada forma do idioma de destino.

Para um arquivo pequeno, uma revisão manual cuidadosa pode ser suficiente. Para milhares de strings a cada lançamento, mantenha o arquivo de origem, o glossário, essa verificação estrutural e a revisão da interface no mesmo fluxo de trabalho. A solução de localização de aplicativos explica como o AI Glot se encaixa quando várias pessoas mantêm esse processo.