Uma payload real raramente é só prosa. O mesmo objeto que contém um title e um body também contém um id, um slug, um URL de recurso, um nome de template, um código enum — valores que identificam ou ligam o seu conteúdo e que têm de sair da tradução exatamente como entraram. O risco é subtil: se entregar a um modelo um campo chamado id ao lado do texto que está a traduzir, ele pode decidir que "post-42" fica melhor localizado, ou normalizar um URL, ou “corrigir” um enum. Basta um identificador alterado para ter uma ligação quebrada ou uma procura falhada em produção, seja qual for o idioma em que o modelo decidiu ser prestável.
lockedKeys elimina as suposições. Indica as chaves que não podem mudar — por nome exato ou por glob — e o motor de localização exclui esses valores da tradução, voltando depois a inserir os valores de origem literalmente em outputData para cada idioma de destino. Um valor bloqueado não é traduzido, normalizado nem reescrito. Entra o mesmo identificador, sai o mesmo identificador, em todos os idiomas.
lockedKeys é um campo no pedido create-jobs. Consulte Create jobs para ver a estrutura completa do pedido e a resposta 202; esta página cobre apenas o que colocar em lockedKeys e como funciona a correspondência.
Bloquear uma chave por nome#
Passe lockedKeys juntamente com o seu data. Cada entrada é um padrão — na forma mais simples, o nome simples de uma chave que quer preservar.
{
"sourceLocale": "en",
"targetLocales": ["de", "fr"],
"data": {
"id": "post-42",
"title": "How async APIs reduce latency",
"tags": ["performance", "infra"],
"author": { "id": "u_abc", "name": "Sam" },
"body": "Async APIs let your app stay responsive while translations process in the background."
},
"lockedKeys": ["id"]
}O padrão simples id corresponde à chave id onde quer que apareça como um segmento completo — aqui, tanto o id de nível superior como o author.id aninhado. O outputData de cada tarefa em alemão e francês mantém "post-42" e "u_abc" exatamente. Só title, name e body são traduzidos; tags permanece inalterado porque não contém nenhum caminho bloqueado, e os seus valores de string são traduzidos como qualquer outro texto.
Vale a pena fixar este último ponto, porque responde à primeira pergunta que um cético faz.
Um valor bloqueado é traduzido?
Não. Uma chave que indicar em lockedKeys é excluída da tradução, e o respetivo valor de origem é reinserido em outputData, literalmente, para cada idioma de destino. O valor que enviou regressa inalterado — não é traduzido, nem normalizado, nem reescrito. O bloqueio é uma garantia sobre o resultado, expressa através de lockedKeys, não uma sugestão que se pede ao modelo para respeitar.
Corresponder por nome, em qualquer lado — ou por posição#
Um padrão simples é um nome de chave e corresponde a esse nome como um segmento completo, a qualquer profundidade, em qualquer ponto da árvore. Se audioSrc aparecer em doze locais aninhados sob pais diferentes, o único padrão audioSrc bloqueia os doze. Não precisa de enumerar caminhos para apanhar cada ocorrência — esse é o caso mais comum, e fica resolvido numa só linha.
Quando precisa de controlo posicional — bloquear uma ocorrência mas não outra, ou todos os elementos de um array mas nada mais — use um glob com / como separador de caminho. Os índices do array aparecem como segmentos normais, por isso users/0/email e users/*/email são ambos caminhos válidos.
| Padrão | O que bloqueia |
|---|---|
audioSrc | Cada folha audioSrc na árvore, a qualquer profundidade |
metadata | A subárvore inteira metadata, onde quer que apareça |
metadata/author | A sequência metadata/author onde quer que apareça, e tudo o que estiver abaixo |
users/*/email | O email de cada utilizador — * é um segmento e corresponde a qualquer índice |
users/0/email | Apenas o email do primeiro utilizador |
**/{audioSrc,imageSrc} | Ambos os nomes de folha, através de alternância com chavetas |
Dois dos padrões acima bloqueiam mais do que uma única folha, propositadamente. metadata bloqueia toda a subárvore sob essa chave — cada valor abaixo dela, pareça traduzível ou não, é preservado. metadata/author bloqueia essa sequência onde quer que ocorra e tudo o que estiver abaixo dela. Recorra a um bloqueio de subárvore quando um bloco inteiro é estrutural — um objeto de configuração, um embed bruto — e a um bloqueio de folha (metadata/author/name) quando apenas um campo dentro de um bloco, de resto traduzível, tem de se manter.
Glob, não regex
* corresponde exatamente a um segmento de caminho; ** abrange qualquer número de segmentos; {a,b} faz alternância com chavetas entre alternativas. Não existe correspondência por classe de caracteres nem por token parcial — os padrões operam sobre segmentos completos do caminho, não sobre substrings. Escreva users/*/email, não uma expressão regular.
O que regressa#
O bloqueio altera o que o modelo traduz — não altera a forma do seu resultado. outputData reflete exatamente a estrutura de entrada: as chaves bloqueadas ficam nas posições originais com os valores originais, e as strings traduzíveis à sua volta são traduzidas. Nada é removido, renomeado ou reordenado.
Para a entrada acima, o outputData de cada idioma inclui id: "post-42" e author.id: "u_abc" inalterados, com title, name e body no idioma de destino. A resposta completa da tarefa — outputData, steps por fase e estado — está documentada em Get a single job.
Um limite, claro desde o início#
lockedKeys aceita até 100 padrões por pedido. É um limite para o número de padrões, não para o número de chaves a que correspondem — um único audioSrc ou users/*/email pode bloquear milhares de valores numa payload grande, e conta como um padrão. Se estiver a aproximar-se de 100 padrões distintos, isso costuma ser sinal de que um glob mais abrangente (**/{id,slug,href}) ou um bloqueio de subárvore exprimirá a mesma intenção em muito menos linhas.
lockedKeys também é ad hoc e por pedido: bloqueia chaves apenas para este grupo de tarefas. Por isso, para termos que nunca devem ser traduzidos em qualquer tarefa — um nome de produto, uma funcionalidade com marca registada, uma unidade que tem de permanecer literal — o lugar certo a longo prazo é uma entrada não traduzível no glossário do seu motor, aplicada automaticamente em cada chamada. Consulte Glossaries. Use lockedKeys para campos estruturais ligados à forma de uma payload específica; use o glossário para vocabulário que se mantém constante em todo o seu conteúdo.
