JSON

Traduza valores de texto aninhados e controle que caminhos são copiados, mantidos, omitidos ou atualizados.

Num catálogo JSON, a aplicação procura uma chave e apresenta o respetivo valor. O processador de ficheiros json altera os valores de texto, mantendo as chaves dos objetos, as posições nos arrays, os números, os booleanos e os valores nulos como dados. Reconstrói o destino a partir da origem atual, inserindo novas traduções ou mantendo o texto de destino existente.

O processador suporta catálogos de objetos e arrays aninhados, bem como um valor de texto na raiz. A CLI infere json a partir de .json. Configure a origem através da configuração da CLI ou da GitHub App.

O que dá origem a uma tarefa de tradução #

Por exemplo:

json
{
  "checkout": {
    "title": "Complete your order",
    "delivery": "Delivery within {days} days"
  },
  "plans": [
    { "name": "Personal", "seats": 1 },
    { "name": "Team", "seats": 10 }
  ],
  "enabled": true
}

O processador seleciona checkout.title, checkout.delivery, plans[0].name e plans[1].name. Mantém os números de seats e o booleano de enabled inalterados. Proteja explicitamente os identificadores com valores de texto: o tipo JSON de um valor indica ao processador que se trata de texto, mas não se esse texto se destina a ser lido por pessoas.

A notação abreviada dos caminhos usa pontos para percorrer objetos e parênteses retos para indicar posições nos arrays: checkout.title seleciona um valor aninhado e plans[0].name seleciona o nome do primeiro plano. Para uma chave cujo nome literal seja checkout.title, use a notação JSONPath entre aspas $['checkout.title']. Consulte os controlos de chaves para conhecer a sintaxe de seleção.

Como as atualizações reutilizam as traduções existentes #

Uma execução incremental utiliza três entradas distintas:

EntradaFunção
Origem atualDefine a estrutura e os textos do novo resultado.
Origem anteriorPermite determinar se o texto de origem no caminho correspondente foi alterado.
Destino existenteFornece as traduções que podem ser mantidas.

Quando a origem anterior e o destino existente estão disponíveis, um texto de origem novo ou alterado dá origem a uma tarefa de tradução. Se o texto de origem não tiver sido alterado, pode reutilizar-se o valor de destino existente no caminho correspondente. Duas chaves com o mesmo texto em inglês continuam a ser registos separados; podem ter traduções aceites diferentes porque os respetivos contextos são diferentes.

Por exemplo, alterar checkout.title não exige, por si só, que se traduza checkout.delivery novamente. Se o valor de origem deste último permanecer inalterado e o respetivo valor de destino estiver disponível, esse valor de destino pode ser reutilizado. Uma alteração a um número ou a outros dados estruturais pode, ainda assim, exigir a reconstrução do ficheiro, mesmo que não haja novos textos para traduzir.

Mantenha a origem anterior associada ao destino aceite. Se faltar um deles, o processador trata os textos como se fosse a primeira execução. O Lockfile e a cache da CLI ligam essas entradas entre execuções.

Escolha o que acontece aos caminhos protegidos #

Estes controlos têm efeitos diferentes no resultado:

ControloComportamento na traduçãoComportamento no resultado
Caminho bloqueadoExcluído da tradução.Usa o valor da origem atual.
Caminho preservadoExcluído da tradução.Mantém o valor de destino existente se esse caminho existir; caso contrário, mantém o valor de origem.
Caminho ignoradoExcluído da tradução.Remove o caminho do destino gerado.
Injeção de idiomaO campo de idioma configurado é excluído da tradução.Escreve o idioma de destino nesse campo.

Bloqueie um identificador partilhado quando todos os idiomas tiverem de usar o valor de origem. Preserve um URL específico do destino quando cada idioma tiver o seu próprio endereço de destino. Ignore uma nota exclusiva da origem quando esta não deva aparecer no ficheiro traduzido. Estas opções não são sinónimos de «não traduzir».

No mesmo caminho, o bloqueio tem precedência sobre a preservação, pelo que um valor presente em ambas as listas é obtido da origem. A opção de ignorar remove o valor mesmo que este também esteja bloqueado, preservado ou selecionado para injeção de idioma. O idioma injetado tem precedência sobre o bloqueio e a preservação na respetiva localização. Prefira um único mecanismo responsável por cada valor e verifique o resultado quando houver sobreposição de regras num objeto ou array.

Remover um elemento de um array desloca as posições dos elementos seguintes. Reveja o array resultante enquanto dados, não apenas enquanto texto traduzido. A injeção de idioma pode criar os objetos contentores em falta. Ao escrever num array, use um elemento existente ou a posição imediatamente a seguir ao último elemento; um caminho que crie lacunas ou atravesse um valor incompatível provoca uma falha.

Defina estes controlos nos campos de entrada de ficheiro da CLI ou nas opções de entrada de ficheiro do GitHub.

Âmbito e limites da reconstrução #

Uma atualização de chaves integra as traduções selecionadas no destino existente. Os valores de destino não selecionados, as chaves exclusivas do destino e as omissões mantêm-se; as chaves exclusivas da origem que estejam fora do âmbito não são adicionadas. As operações de escrita em arrays não podem criar lacunas. Por exemplo, selecionar o segundo elemento de um array não preenche automaticamente um primeiro elemento em falta. Verifique o destino completo após uma atualização parcial.

O resultado JSON é serializado com indentação de dois espaços e uma quebra de linha no final. Não conte com a preservação, byte a byte, dos espaços em branco ou dos comentários. Para ficheiros de origem com comentários, consulte JSONC e verifique os requisitos do sistema que os utiliza antes de considerar um ficheiro reescrito equivalente ao original.

O workflow de tradução verifica os marcadores de posição e a estrutura ICU suportados, incluindo argumentos alterados ou em falta. Analise os avisos ou as falhas comunicados e, em seguida, renderize o modelo aceite com os valores da aplicação. Estas verificações não avaliam se a mensagem traduzida exprime o significado pretendido.

Carregue o resultado na aplicação com valores representativos. Verifique se os caminhos protegidos mantêm os dados de origem ou de destino pretendidos e se a mensagem de entrega continua a transmitir a mesma promessa após a substituição. A análise sintática verifica a sintaxe JSON; a renderização e a leitura verificam a mensagem que as pessoas recebem.