Crie um workflow de tradução via API
Traduza registros da aplicação no servidor e mantenha as versões aceitas em cada idioma vinculadas à revisão de origem que representam.
Quando um editor atualiza a descrição de um produto, cada versão traduzida precisa refletir essa alteração. A resposta da API fornece o novo texto; sua aplicação decide a qual registro ele pertence, se a origem ainda é a versão atual e quando os leitores podem vê-lo.
Este guia parte de uma primeira solicitação de tradução para criar um workflow de backend que pode ser executado repetidamente. Ele é indicado para registros gerenciados pela sua aplicação, como descrições de produtos e artigos de ajuda. Para recursos estáticos da aplicação, um workflow de arquivos em CI costuma ser mais adequado, pois a compilação dos recursos e a revisão do repositório já oferecem uma etapa de validação.
Envie um conteúdo coeso #
Crie uma tarefa de localização com um único documento JSON no corpo da solicitação para um registro de produto. Agrupe os campos relacionados para que o contexto descreva a finalidade deles e preserve chaves estáveis para que o objeto baixado possa ser associado aos campos correspondentes.
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 o engine explicitamente. Use as orientações compartilhadas do glossário para a terminologia do produto e o contexto do documento para este uso específico. A Referência de JSON explica as dicas de contexto e os caminhos protegidos.
Execute a tradução em segundo plano #
Salve o ID retornado para a tarefa antes de iniciá-la. Envie tudo o que estiver listado em uploads e, em seguida, chame POST /v2/localization/jobs/:id/start. Mesmo um documento JSON enviado no corpo da solicitação exige esse início explícito.
Consulte periodicamente a tarefa pelo processo de trabalho do backend e baixe os resultados concluídos de cada idioma de destino usando as URLs retornadas. A solicitação de salvamento do editor pode receber uma resposta assim que sua aplicação tiver colocado esse trabalho em uma fila persistente. Ela não precisa permanecer aberta durante a tradução ou a revisão humana.
Para atualizações incrementais, mantenha os artefatos anteriores da origem e das traduções aceitas e forneça-os na próxima solicitação de documento. Atualizações de documentos explica os limites de reutilização.
Registre o trabalho depois de salvar a origem #
Após a confirmação da transação de origem, crie um registro de trabalho no seu próprio armazenamento com o ID do conteúdo, a revisão de origem, o idioma de destino, o registro do engine de localização/configuração e o estado de processamento. Coloque a tradução na fila a partir desse registro. Isso impede que um processo de trabalho traduza uma edição que a transação de origem venha a reverter.
Mantenha um resultado por idioma de destino. A versão em alemão pode estar pronta enquanto a versão em francês precisa de uma nova tentativa ou revisão. Registrar apenas um indicador geral de “traduzido” ocultaria essa diferença da aplicação que decide o que disponibilizar. Os nomes de estado que você adicionar pertencem ao projeto da sua aplicação, não ao vocabulário de resposta da API.
Aceite o resultado apenas para a revisão prevista #
As edições da origem e as traduções concluídas podem chegar em ordens diferentes. Considere esta sequência:
| Evento | Ação da aplicação |
|---|---|
| A revisão 12 é salva | Coloque a revisão 12 na fila para tradução para o alemão. |
| A revisão 13 é salva antes da conclusão desse trabalho | Coloque a revisão 13 na fila e marque-a como a origem atual. |
| A tradução da revisão 13 é concluída | Valide e aceite a tradução, vinculando-a à revisão 13. |
| A tradução da revisão 12 é concluída depois | Mantenha o resultado registrado sem substituir o texto aceito da revisão 13. |
No momento da ativação, compare a revisão de origem do registro de trabalho com a origem atual. No seu sistema de armazenamento, faça a comparação e condicione a gravação a essa revisão, para que outra edição da origem não passe despercebida entre as duas operações. Se o trabalho da revisão atual não tiver sido colocado na fila ou tiver falhado, agende essa revisão em vez de atribuir um resultado antigo a ela.
No momento da leitura, busque a tradução aceita para o idioma e a revisão solicitados. Decida o que a aplicação fará se ela não estiver disponível: mostrar o texto de origem, usar um idioma alternativo definido, disponibilizar uma tradução anterior explicitamente rastreada ou suspender a publicação. A escolha certa depende do impacto que um texto desatualizado ou não traduzido pode ter para o leitor. Uma alteração nas condições de finalização da compra pode exigir uma política mais rigorosa do que uma descrição informal de produto.
Recupere o processamento com a identificação remota e o registro local #
Salve de forma persistente a chave de idempotência da solicitação antes de enviá-la e o ID da tarefa assim que receber a resposta de criação. Se o tempo limite de rede for atingido, repita a solicitação de criação sem alterações usando a mesma chave ou recupere a tarefa registrada. Repetir o comando de início atua sobre a mesma tarefa.
Após falhas temporárias de leitura, repita as consultas com intervalos progressivos. O tempo limite do cliente interrompe a espera, não o trabalho no servidor. Mantenha os resultados concluídos de cada idioma de destino separados dos detalhes das falhas; uma tarefa com falha ainda pode conter arquivos concluídos e utilizáveis.
Erros de autenticação, engines desativados, dados de entrada inválidos e limites da conta exigem correção. Uma tarefa pendente pode ser iniciada novamente depois que a restrição de admissão for resolvida. Para trabalhos que falharam durante a execução, corrija a causa e envie os documentos/idiomas afetados com uma nova chave de idempotência.
Ao aceitar os resultados, aplique a mesma verificação de revisão a todos eles, inclusive aos obtidos após a recuperação. A conclusão do download confirma que o texto está disponível; sua política de validação e revisão determina se ele pode ser publicado.
Teste o ciclo de vida do registro #
Use um registro curto com uma variável e teste uma atualização da origem, uma falha em um idioma e traduções concluídas que chegam fora de ordem. Além do texto, inspecione as chaves dos campos armazenados e os identificadores dos idiomas. A aplicação deve disponibilizar apenas a versão aceita pela sua política, e um revisor deve conseguir rastreá-la até a origem.
Para medir a qualidade, mantenha o par de origem e destino junto com o critério usado para examiná-lo. O planejamento da medição se aplica independentemente do workflow de geração. Assim, seu registro pode distinguir o texto retornado, uma resposta de medição, a aceitação humana e a publicação, em vez de tratá-los como um único evento.