Tarefas de tradução
Crie e inicie tarefas com um ou mais documentos e idiomas de destino.
Uma tarefa traduz documentos usando um único engine de localização. Cada documento tem uma chave estável e um destino para cada idioma solicitado. Use JSON inline para conteúdo em memória ou endereços de artefatos para arquivos.
Todas as rotas abaixo usam https://api.lingo.dev e autenticação de API.
Criar uma tarefa #
POST /v2/organizations/:orgId/localization/jobs
Content-Type: application/json
X-API-Key: YOUR_API_KEY
Idempotency-Key: order-confirmation-v3-de-fr{
"engineId": "YOUR_ENGINE_ID",
"sourceLocale": "en",
"targetLocales": ["de", "fr"],
"documents": [
{
"key": "order-confirmation.json",
"format": { "type": "json" },
"source": { "content": { "subject": "Your order is confirmed" } }
}
]
}Campos da requisição #
| Campo | Obrigatório | Descrição |
|---|---|---|
engineId | Sim | Engine da organização que o solicitante pode usar para traduzir. |
sourceLocale | Sim | Idioma de origem. |
targetLocales | Sim | Array não vazio de idiomas de destino, sem repetições. Um documento não pode ter o próprio idioma de origem como destino. |
documents | Sim | Array não vazio de documentos com valores únicos de key. |
originId | Não | Identificador não vazio, com até 512 caracteres, do local onde os documentos estão armazenados; por exemplo, github:acme/web. Ele associa edições posteriores feitas nessa origem à medição da tradução. |
Cada documento tem:
| Campo | Obrigatório | Descrição |
|---|---|---|
key | Sim | Caminho lógico ou nome de arquivo não vazio e único nesta tarefa. Mantenha esse valor estável entre as revisões. |
format | Sim | Objeto de formato com type e options específico do formato. |
source | Sim | Endereço de artefato SHA-256 ou { "content": { ... } } para JSON inline. |
previousSource | Não | Endereço do artefato de origem anterior. Omita ou use null na primeira tradução. |
previousTranslations | Não | Array de { "locale": "de", "artifact": "SHA256" }. O padrão é []; cada idioma deve aparecer uma única vez e estar entre os destinos deste documento. |
targetLocales | Não | Definição de idiomas específica para este documento, não vazia e sem repetições. Se omitida ou definida como null, usa os idiomas de destino da tarefa. |
Ao usar keyScope ou termScope, forneça uma tradução anterior para cada destino. Consulte formatos de documentos e atualizações.
Idempotência #
Envie um Idempotency-Key não vazio com no máximo 255 caracteres. As chaves têm escopo limitado ao engine; o prefixo content-sync: é reservado. Guarde a chave junto com a requisição original e repita essa requisição sem alterações se houver incerteza sobre a resposta de criação.
Reutilizar uma chave retorna a tarefa criada originalmente com ela, sem atualizar os documentos ou idiomas dessa tarefa. Use uma nova chave se o trabalho tiver alterações. Uma opção de execução conflitante pode gerar LocalizationJobIdempotencyKeyReused (422).
Resposta de criação #
Quando a criação é bem-sucedida, a API retorna HTTP 200 e a resposta da tarefa, normalmente com status: { "_tag": "Pending" }. Salve id de forma persistente antes de continuar. O array uploads lista os artefatos de entrada ausentes como { "address": "...", "uploadUrl": "..." }.
A criação armazena os conteúdos de origem inline, mas não inicia a tradução, mesmo quando uploads está vazio.
Enviar e iniciar #
Envie cada artefato ausente para seu uploadUrl usando um PUT autenticado com os bytes originais. Em seguida, chame:
POST /v2/localization/jobs/:id/start
X-API-Key: YOUR_API_KEYA requisição de início não tem corpo. A resposta HTTP 200 contém o registro atual da tarefa. É seguro repetir a solicitação de início para a mesma tarefa, o que pode resolver uma incerteza no envio para execução; isso não cria outra tarefa nem executa novamente uma tarefa concluída.
Ao iniciar, são verificados os artefatos enviados, a configuração do engine e os limites da conta. ArtifactsNotUploaded (409) lista as entradas ausentes. Se o limite diário de tokens for atingido (429) ou não houver créditos suficientes, a tarefa permanece pendente; resolva a condição antes de tentar iniciá-la novamente. Consulte erros.
Configurar etapas do pipeline #
Configure o pipeline do engine antes de iniciar a tarefa. Essa configuração é registrada no momento do início. As etapas resultantes de cada destino da tarefa mostram o trabalho efetivamente selecionado, considerando a disponibilidade no plano.
Coletar resultados e recuperar falhas #
Consulte a tarefa para inspecionar cada destino e baixar os arquivos concluídos. Use o progresso das etapas para distinguir o trabalho do modelo, as esperas por revisão, o trabalho ignorado e as falhas.
Uma tarefa com falha ainda pode ter destinos concluídos. Guarde esses resultados e, após corrigir a causa, envie apenas o trabalho que precisa ser gerado novamente, usando uma nova chave de idempotência. Mantenha as revisões de origem junto com os IDs das tarefas para evitar que uma entrega posterior sobrescreva traduções mais recentes.
Liste as tarefas para encontrar envios por engine, estado, gatilho ou chave de serviço.