Traduzir JSON

Envie um objeto JSON com contexto, dicas e caminhos protegidos e baixe as traduções.

Envie um objeto JSON diretamente em uma tarefa de localização quando sua aplicação já tiver o conteúdo de origem na memória. O Lingo.dev armazena esse objeto como um documento JSON e gera uma saída para cada idioma de destino.

O guia de início rápido traz um programa completo. Esta referência detalha os campos de requisição específicos para JSON.

Enviar um documento no corpo da requisição #

Crie a tarefa em POST /v2/organizations/:orgId/localization/jobs com uma chave de API em X-API-Key e um Idempotency-Key estável para este envio:

json
{
  "engineId": "YOUR_ENGINE_ID",
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "documents": [
    {
      "key": "settings.json",
      "format": {
        "type": "json",
        "options": {
          "context": "Settings dialog in a team collaboration application",
          "hints": { "$.save": ["Button that saves the edited settings"] },
          "lockedKeys": ["$.productName"]
        }
      },
      "source": {
        "content": {
          "save": "Save changes",
          "cancel": "Cancel",
          "productName": "Acme"
        }
      }
    }
  ]
}

O conteúdo de origem deve ser um objeto JSON e pode conter objetos e arrays aninhados. Valores de texto nos nós folha são candidatos à tradução; números, booleanos e valores nulos mantêm seus tipos JSON. Proteja identificadores, nomes de produtos ou URLs armazenados como texto quando precisarem permanecer inalterados.

Conteúdos de origem enviados no corpo da requisição usam format.type: "json". Para JSONC ou outro formato de arquivo, envie os bytes do arquivo.

Adicionar contexto e selecionar conteúdo #

Defina as opções de JSON em format.options do documento:

OpçãoEfeito
contextTexto não vazio que descreve a finalidade ou o público do conteúdo.
hintsConsultas JSONPath associadas a arrays não vazios de dicas também não vazias. As dicas correspondentes são acumuladas para os textos selecionados. O padrão é um objeto vazio.
lockedKeysCopia os valores de origem selecionados sem traduzi-los. O padrão é [].
preservedKeysReutiliza os valores selecionados da versão de destino anterior, quando disponíveis; caso contrário, copia os valores de origem. O padrão é [].
ignoredKeysRemove os valores selecionados da saída. O padrão é [].
keyScopeGera novamente os textos selecionados por uma lista não vazia de consultas JSONPath. Requer uma tradução anterior para cada idioma de destino.
termScopeGera novamente os textos que correspondem a uma lista não vazia de termos de origem. Requer uma tradução anterior para cada idioma de destino.
injectLocaleGrava o idioma de destino em um único caminho JSONPath, como $.meta.locale. Essa subárvore fica protegida contra tradução.

Use JSONPath nas requisições à API. $.title seleciona uma propriedade da raiz; $.nav.home seleciona uma propriedade aninhada; $['nav.home'] seleciona uma chave literal que contém um ponto; $..productName seleciona essa propriedade em qualquer profundidade. Ao selecionar um objeto ou array, os textos de todos os seus descendentes são incluídos. Nomes de chaves isolados não são consultas válidas para a API.

Os controles de chaves são aplicados antes da tradução. Os valores ignorados são removidos; os valores de origem bloqueados têm prioridade sobre os valores de destino preservados. A seleção de escopo não se sobrepõe a esses controles. Consulte a referência do formato JSON para saber mais sobre a montagem da saída e as mensagens ICU.

termScope busca trechos nos textos de origem, diferenciando maiúsculas de minúsculas. Qualquer termo listado pode selecionar um texto: "cat" também corresponde a "catalog", enquanto "login" não corresponde a "Login". O texto selecionado é gerado novamente por inteiro, não apenas o termo correspondente. Quando keyScope e termScope estão presentes, o texto precisa atender aos dois critérios. Use uma seleção precisa de chaves via JSONPath quando a busca por um trecho puder incluir mensagens não relacionadas.

Iniciar e consultar o resultado #

Salve o id retornado na resposta de criação. Se a tarefa também fizer referência a arquivos anteriores ou a outros documentos, envie cada entrada de uploads e, em seguida, chame POST /v2/localization/jobs/:id/start.

Leia GET /v2/localization/jobs/:id e verifique o targets de cada documento. Um destino com status._tag: "Completed" tem um status.downloadUrl. Baixe o conteúdo dessa URL usando a mesma autenticação para obter o objeto JSON. A resposta da tarefa em si contém o progresso e os endereços dos artefatos, não o objeto traduzido.

Para atualizações, envie os artefatos anteriores de origem e de destino conforme descrito em atualizar um documento existente. Guarde a nova revisão do conteúdo de origem junto com o ID da tarefa para evitar que um resultado atrasado substitua um conteúdo mais recente.