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:
{
"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:
| Evento | Ação da aplicação |
|---|---|
| A revisão 12 é guardada | Colocar a revisão 12 em fila para tradução para alemão. |
| A revisão 13 é guardada antes de esse trabalho terminar | Colocar 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ída | Validar e aceitar a tradução, associando-a à revisão 13. |
| A tradução da revisão 12 é concluída mais tarde | Conservar 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.