Criar um workflow de tradução por API

Traduza registos da aplicação no servidor e mantenha as versões linguísticas aceites associadas à revisão do texto de origem a que correspondem.

Quando alguém da equipa editorial atualiza a descrição de um produto, todas as versões traduzidas têm de refletir essa alteração. A resposta da API fornece o novo texto; cabe à sua aplicação decidir a que registo pertence, se o texto de origem continua atualizado e quando fica disponível para leitura.

Este guia parte de um primeiro pedido de tradução para criar um workflow de backend que pode executar repetidamente. É adequado para registos geridos pela sua aplicação, como descrições de produtos e entradas de ajuda. Para recursos estáticos da aplicação, um workflow de ficheiros em CI é muitas vezes mais adequado, porque a compilação dos recursos e a revisão no repositório já proporcionam uma etapa de validação.

Enviar um bloco de conteúdo coerente #

Crie uma tarefa de localização com um único documento JSON incorporado para um registo de produto. Agrupe os campos relacionados para que o contexto possa descrever a sua finalidade e mantenha as chaves estáveis para que o objeto transferido corresponda a esses campos.

Envie este corpo para POST /v2/organizations/:orgId/localization/jobs, com uma chave de API e um Idempotency-Key estável para esta revisão:

json
{
  "engineId": "YOUR_ENGINE_ID",
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "documents": [
    {
      "key": "products/bottle.json",
      "format": {
        "type": "json",
        "options": {
          "context": "Product listing for a reusable drinks bottle",
          "hints": {
            "$.title": ["Catalog card title"],
            "$.description": ["Short product description; do not add specifications"]
          }
        }
      },
      "source": {
        "content": {
          "title": "Insulated bottle",
          "description": "Keeps drinks cold during your commute."
        }
      }
    }
  ]
}

Mantenha as credenciais no backend e selecione explicitamente o motor. Use as orientações do glossário partilhado para a terminologia do produto e o contexto do documento para esta utilização específica. A Referência de JSON explica as indicações contextuais e os caminhos protegidos.

Executar a tradução em segundo plano #

Guarde o ID devolvido para a tarefa antes de a iniciar. Carregue tudo o que estiver indicado em uploads e, em seguida, invoque POST /v2/localization/jobs/:id/start. Mesmo com JSON incorporado, é necessário iniciar a tarefa explicitamente.

Consulte periodicamente o estado da tarefa a partir do processo de trabalho do backend e transfira as traduções concluídas através dos URLs devolvidos. O pedido para guardar a edição pode receber uma resposta assim que a aplicação tiver colocado este trabalho numa fila persistente. Não precisa de ficar em aberto enquanto decorre a tradução ou a revisão humana.

Para atualizações incrementais, conserve os artefactos anteriores do texto de origem e das traduções aceites e forneça-os no pedido de documento seguinte. A secção Atualizações de documentos explica os limites da reutilização.

Registar o trabalho depois de guardar o texto de origem #

Depois de confirmada a transação do texto de origem, crie um registo de trabalho no seu próprio sistema de armazenamento com o ID do conteúdo, a revisão do texto de origem, o idioma de destino, o registo do motor de localização/configuração e o estado de processamento. Coloque a tradução em fila a partir desse registo. Isto impede que um processo de trabalho traduza uma edição que a transação do texto de origem venha depois a reverter.

Mantenha um resultado por idioma de destino. A tradução para alemão pode estar pronta, enquanto a tradução para francês precisa de uma nova tentativa ou de revisão. Registar apenas um indicador global de «traduzido» ocultaria essa diferença à aplicação que decide o que apresentar. Os nomes de estado que adicionar pertencem à conceção da sua aplicação, não ao vocabulário das respostas da API.

Aceitar resultados apenas para a revisão pretendida #

As edições do texto de origem e as traduções concluídas podem chegar por uma ordem diferente. Considere esta sequência:

EventoAção da aplicação
A revisão 12 é guardadaColocar a revisão 12 em fila para tradução para alemão.
A revisão 13 é guardada antes de esse trabalho terminarColocar a revisão 13 em fila e marcá-la como a revisão atual do texto de origem.
A tradução da revisão 13 é concluídaValidar e aceitar a tradução, associando-a à revisão 13.
A tradução da revisão 12 é concluída mais tardeConservar o resultado registado sem substituir o texto aceite da revisão 13.

No momento da ativação, compare a revisão do texto de origem indicada no registo de trabalho com a revisão atual. No seu sistema de armazenamento, condicione a comparação e a escrita a essa revisão, para que nenhuma outra edição do texto de origem passe despercebida entre as duas operações. Se o trabalho da revisão atual não tiver sido colocado em fila ou tiver falhado, agende essa revisão em vez de reatribuir um resultado mais antigo.

No momento da leitura, procure a tradução aceite para o idioma e a revisão pedidos. Defina o que a aplicação faz quando essa tradução não existe: apresentar o texto de origem, usar um idioma alternativo predefinido, apresentar uma tradução anterior explicitamente identificada como tal ou suspender a publicação. A escolha certa depende do impacto que um texto desatualizado ou por traduzir pode ter em quem o lê. Uma alteração nas condições de finalização da compra pode justificar uma política mais rigorosa do que uma descrição informal de produto.

Recuperar com a identidade remota e o registo local #

Guarde de forma persistente a chave de idempotência do pedido antes de o enviar e o ID da tarefa assim que receber a resposta de criação. Se o tempo limite de rede for excedido, repita o pedido de criação sem alterações, usando a mesma chave, ou obtenha a tarefa registada. Repetir a operação de início atua sobre a mesma tarefa.

Após falhas temporárias de leitura, volte a consultar o estado com intervalos progressivamente maiores. O tempo limite do cliente interrompe a espera, não o trabalho no servidor. Conserve separadamente os resultados concluídos e os detalhes das falhas por idioma de destino; uma tarefa com falha pode ainda conter ficheiros concluídos e utilizáveis.

Os erros de autenticação, os motores desativados, os dados de entrada inválidos e os limites da conta exigem medidas corretivas. Uma tarefa pendente pode voltar a ser iniciada depois de resolvida a restrição imposta pelo limite de admissão. Se o trabalho tiver falhado durante a execução, corrija a causa e envie os documentos/idiomas afetados com uma nova chave de idempotência.

No momento da aceitação, aplique a mesma verificação de revisão a todos os resultados, incluindo os obtidos após a recuperação. A conclusão da transferência confirma que o texto está disponível; a sua política de validação e revisão determina se pode ser publicado.

Testar o ciclo de vida do registo #

Use um registo curto com uma variável e teste depois uma atualização do texto de origem, uma falha num idioma e traduções que ficam concluídas fora de ordem. Verifique as chaves dos campos guardadas e os identificadores dos idiomas, além do próprio texto. A aplicação deve apresentar apenas a versão aceite pela sua política, e quem fizer a revisão deve conseguir identificar o texto de origem correspondente.

Para medir a qualidade, conserve o texto de origem e a tradução correspondente, juntamente com o critério usado para os avaliar. A conceção da medição aplica-se independentemente do workflow de geração. Assim, o seu registo pode distinguir o texto devolvido, uma resposta de medição, a aceitação humana e a publicação, em vez de os tratar como um único evento.