JSON
Traduza valores de texto aninhados e controle quais caminhos são copiados, mantidos, omitidos ou atualizados.
Em um catálogo JSON, a aplicação procura uma chave e exibe o valor correspondente. O manipulador de arquivos json altera os valores de texto e preserva como dados as chaves de objetos, as posições em arrays, os números, os booleanos e os valores nulos. Ele reconstrói o destino a partir da origem atual, inserindo novas traduções ou textos já existentes no destino.
O manipulador é compatível com catálogos de objetos e arrays aninhados, além de uma string na raiz. A CLI deduz json a partir de .json. Configure a origem pela configuração da CLI ou pelo GitHub App.
O que vira uma tarefa de tradução #
Por exemplo:
{
"checkout": {
"title": "Complete your order",
"delivery": "Delivery within {days} days"
},
"plans": [
{ "name": "Personal", "seats": 1 },
{ "name": "Team", "seats": 10 }
],
"enabled": true
}O manipulador seleciona checkout.title, checkout.delivery, plans[0].name e plans[1].name. Os números de seats e o booleano de enabled permanecem inalterados. Proteja explicitamente os identificadores com valores de texto: o tipo JSON de um valor indica ao manipulador que ele é texto, mas não se ele foi feito para ser lido por pessoas.
A forma abreviada de caminho usa pontos para percorrer objetos e colchetes para indicar posições em arrays: checkout.title seleciona um valor aninhado e plans[0].name seleciona o nome do primeiro plano. Para uma chave literal chamada checkout.title, use a forma JSONPath entre aspas $['checkout.title']. Veja a sintaxe de seleção em controles de chaves.
Como as atualizações reaproveitam traduções existentes #
Uma execução incremental usa três entradas distintas:
| Entrada | Função |
|---|---|
| Origem atual | Define a estrutura e os textos da nova saída. |
| Origem anterior | Indica se o texto de origem em um caminho correspondente mudou. |
| Destino existente | Fornece as traduções que podem ser mantidas. |
Quando a origem anterior e o destino existente estão disponíveis, todo texto de origem novo ou alterado vira uma tarefa de tradução. Um texto de origem que não mudou pode reaproveitar o valor de destino existente no caminho correspondente. Duas chaves com o mesmo texto em inglês continuam sendo registros separados: elas podem ter traduções aceitas diferentes, já que seus contextos são distintos.
Por exemplo, alterar checkout.title não exige, por si só, traduzir checkout.delivery de novo. Se o valor de origem deste último não mudou e o valor de destino está disponível, ele pode ser reaproveitado. Ainda assim, uma alteração em um número ou em outros dados estruturais pode exigir a reconstrução do arquivo, mesmo sem novos textos para traduzir.
Mantenha a origem anterior sempre pareada com o destino aceito. Se faltar um dos dois, o manipulador tratará os textos como uma primeira execução. O Lockfile e o cache da CLI conectam essas entradas de uma execução para outra.
Defina o que acontece com os caminhos protegidos #
Cada um destes controles produz um resultado diferente na saída:
| Controle | Comportamento na tradução | Comportamento na saída |
|---|---|---|
| Caminho bloqueado | Excluído da tradução. | Usa o valor da origem atual. |
| Caminho preservado | Excluído da tradução. | Mantém o valor de destino existente quando o caminho existe; caso contrário, fica o valor de origem. |
| Caminho ignorado | Excluído da tradução. | Remove o caminho do destino gerado. |
| Injeção de idioma | O campo de idioma configurado é excluído da tradução. | Grava o idioma de destino nesse campo. |
Bloqueie um identificador compartilhado quando todos os idiomas precisarem usar o valor de origem. Preserve uma URL específica do destino quando cada idioma tiver seu próprio endereço. Ignore uma nota exclusiva da origem quando ela não puder aparecer no arquivo traduzido. Essas opções não são sinônimos de “não traduzir”.
No mesmo caminho, o bloqueio tem precedência sobre a preservação; por isso, um valor presente nas duas listas vem da origem. Ignorar remove o valor mesmo que ele também esteja bloqueado, preservado ou selecionado para injeção de idioma. Um idioma injetado tem precedência sobre o bloqueio e a preservação na posição em que é inserido. Prefira um único controle responsável por cada valor e confira a saída sempre que houver regras sobrepostas em um objeto ou array.
Remover um elemento de um array desloca as posições dos elementos seguintes. Revise o array resultante como dados, e não apenas como texto traduzido. A injeção de idioma pode criar objetos contêineres que estejam faltando. Ao gravar em um array, use um elemento existente ou a posição logo após o último; um caminho que crie lacunas ou atravesse um valor incompatível vai falhar.
Defina esses controles pelos campos de entrada de arquivo da CLI ou pelas opções de entrada de arquivo do GitHub.
Limites de escopo e reconstrução #
Uma atualização de chaves mescla as traduções selecionadas ao destino existente. Valores de destino não selecionados, chaves exclusivas do destino e omissões continuam como estão; chaves exclusivas da origem fora do escopo não são adicionadas. As gravações em arrays não podem criar lacunas. Por exemplo, selecionar o segundo elemento de um array não preenche automaticamente um primeiro elemento ausente. Depois de uma atualização parcial, confira o destino completo.
A saída JSON é serializada com recuo de dois espaços e uma quebra de linha no final. Espaços em branco e comentários não são preservados byte a byte. Para arquivos de origem com comentários, consulte JSONC e verifique os requisitos do sistema que consome o arquivo antes de considerar um arquivo reescrito como equivalente.
O workflow de tradução verifica os placeholders e a estrutura ICU compatíveis, incluindo argumentos alterados ou ausentes. Analise os avisos ou as falhas relatados e, em seguida, renderize o modelo aceito com os valores da aplicação. Essas verificações não avaliam se a mensagem traduzida transmite o significado pretendido.
Carregue a saída na aplicação com valores representativos. Confira se os caminhos protegidos mantêm os dados de origem ou de destino esperados e se a mensagem de entrega continua fazendo a mesma promessa após a substituição. A análise sintática valida a sintaxe JSON; já a renderização e a leitura validam a mensagem que as pessoas realmente recebem.