Um payload real raramente é composto só de texto corrido. O mesmo objeto que contém um title e um body também traz um id, um slug, uma URL de asset, um nome de template, um código de enum — valores que identificam ou estruturam seu conteúdo e precisam sair da tradução exatamente como entraram. O risco é sutil: entregue a um modelo um campo chamado id ao lado do texto que ele está traduzindo, e ele pode decidir que "post-42" ficaria melhor localizado, ou normalizar uma URL, ou “corrigir” um enum. Basta um identificador alterado para quebrar um link ou causar uma falha de busca em produção, em qualquer idioma em que o modelo tenha resolvido “ajudar”.
lockedKeys elimina essa incerteza. Você informa as chaves que não podem mudar — por nome exato ou por glob — e o engine de localização exclui esses valores da tradução, depois reinsere os valores de origem literalmente em outputData para cada idioma de destino. Um valor bloqueado não é traduzido, normalizado nem reescrito. Entra um identificador, sai o mesmo identificador, em qualquer idioma.
lockedKeys é um campo da requisição create-jobs. Veja Create jobs para conferir o formato completo da requisição e a resposta 202; esta página cobre apenas o que colocar em lockedKeys e como a correspondência funciona.
Bloqueie uma chave pelo nome#
Passe lockedKeys junto com seu data. Cada entrada é um padrão — no caso mais simples, apenas o nome da chave que você 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 ela apareça como um segmento completo — aqui, tanto no id de nível superior quanto no author.id aninhado. O outputData de cada job em alemão e francês mantém "post-42" e "u_abc" exatamente como estão. Apenas title, name e body são traduzidos; tags permanece inalterado porque não contém nenhum caminho bloqueado, e seus valores de string são traduzidos como qualquer outro texto.
Vale a pena deixar esse último ponto bem claro, porque ele responde à primeira pergunta que qualquer cético faz.
Um valor bloqueado é traduzido?
Não. Uma chave que você informa em lockedKeys é excluída da tradução, e seu valor de origem é reinserido em outputData, literalmente, para cada idioma de destino. O valor que você enviou volta inalterado — não é traduzido, nem normalizado, nem reescrito. O bloqueio é uma garantia sobre o resultado, expressa por meio de lockedKeys, não uma sugestão que o modelo é instruído a seguir.
Correspondência por nome, em qualquer lugar — ou por posição#
Um padrão simples é um nome de chave, e ele corresponde a esse nome como um segmento completo, em qualquer profundidade, em qualquer ponto da árvore. Se audioSrc aparece em doze lugares aninhados sob pais diferentes, o único padrão audioSrc bloqueia os doze. Você não precisa enumerar caminhos para cobrir cada ocorrência — esse é o caso mais comum, e resolve-se em uma linha.
Quando você precisa de controle posicional — bloquear uma ocorrência, mas não outra, ou cada elemento de um array e nada além disso — use um glob com / como separador de caminho. Índices de array aparecem como segmentos comuns, então users/0/email e users/*/email são ambos caminhos válidos.
| Padrão | O que ele bloqueia |
|---|---|
audioSrc | Cada folha audioSrc na árvore, em qualquer profundidade |
metadata | A subárvore inteira de metadata onde quer que ela apareça |
metadata/author | A sequência metadata/author onde quer que apareça, mais tudo abaixo dela |
users/*/email | O email de cada usuário — * é um segmento e corresponde a qualquer índice |
users/0/email | Apenas o email do primeiro usuário |
**/{audioSrc,imageSrc} | Ambos os nomes de folha via alternância com chaves |
Dois padrões acima bloqueiam mais do que uma única folha, de propósito. metadata bloqueia a subárvore inteira sob essa chave — todos os valores abaixo dela, pareçam traduzíveis ou não, são preservados. metadata/author bloqueia essa sequência onde quer que ela ocorra e tudo abaixo dela. Recorra ao bloqueio de subárvore quando um bloco inteiro for estrutural — um objeto de configuração, um embed bruto — e ao bloqueio de folha (metadata/author/name) quando apenas um campo dentro de um bloco que, fora isso, é traduzível, precisa ser preservado.
Glob, não regex
* corresponde a exatamente um segmento de caminho; ** abrange qualquer número de segmentos; {a,b} faz alternância com chaves entre alternativas. Não há correspondência por classe de caracteres nem por parte do token — os padrões operam sobre segmentos completos de caminho, não sobre substrings. Escreva users/*/email, não uma expressão regular.
O que volta#
O bloqueio muda o que o modelo traduz — não muda a estrutura do seu resultado. outputData espelha exatamente a estrutura de entrada: as chaves bloqueadas permanecem em suas posições originais com seus valores originais, e as strings traduzíveis ao redor são traduzidas. Nada é removido, renomeado ou reordenado.
Para a entrada acima, o outputData de cada idioma traz id: "post-42" e author.id: "u_abc" inalterados, com title, name e body no idioma de destino. A resposta completa do job — outputData, steps por etapa e status — está documentada em Get a single job.
Um limite, dito logo de cara#
lockedKeys aceita até 100 padrões por requisição. Esse é um teto para a quantidade de padrões, não para a quantidade de chaves às quais eles correspondem — um único audioSrc ou users/*/email pode bloquear milhares de valores em um payload grande, e ainda conta como um padrão. Se você estiver se aproximando de 100 padrões distintos, isso normalmente é sinal de que um glob mais amplo (**/{id,slug,href}) ou um bloqueio de subárvore expressa a mesma intenção em muito menos linhas.
lockedKeys também é ad hoc e por requisição: ele bloqueia chaves apenas para este grupo de jobs. Portanto, para termos que nunca devem ser traduzidos em nenhum job — um nome de produto, um recurso com marca registrada, uma unidade que precisa permanecer literal — o lugar certo é uma entrada não traduzível no glossário do seu engine, aplicada automaticamente em cada chamada. Veja Glossaries. Use lockedKeys para campos estruturais ligados ao formato de um payload específico; use o glossário para vocabulário que permanece constante em todo o seu conteúdo.
