Una carga útil real rara vez es puro texto. El mismo objeto que contiene un title y un body también contiene un id, un slug, una URL de recurso, un nombre de plantilla, un código enum: valores que identifican o conectan tu contenido y que deben salir de la traducción exactamente como entraron. El riesgo es silencioso: si le das a un modelo un campo llamado id junto al texto que está traduciendo, puede decidir que "post-42" se lee mejor localizado, o normalizar una URL, o "corregir" un enum. Un identificador alterado puede convertirse en un enlace roto o una búsqueda fallida en producción, en cualquier idioma donde al modelo se le ocurra "ayudar".
lockedKeys elimina las suposiciones. Tú indicas las claves que no deben cambiar —por nombre exacto o por glob— y el motor de localización excluye esos valores de la traducción; luego vuelve a insertar los valores de origen literalmente en outputData para cada idioma de destino. Un valor bloqueado no se traduce, no se normaliza ni se reescribe. Mismo identificador al entrar, mismo identificador al salir, en todos los idiomas.
lockedKeys es un campo de la solicitud create-jobs. Consulta Create jobs para ver la forma completa de la solicitud y la respuesta 202; esta página cubre únicamente qué poner en lockedKeys y cómo funciona la coincidencia.
Bloquea una clave por nombre#
Pasa lockedKeys junto con tu data. Cada entrada es un patrón; en su forma más simple, el nombre de una clave que quieres conservar.
{
"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"]
}El patrón simple id coincide con la clave id dondequiera que aparezca como un segmento completo; aquí, tanto en el id de nivel superior como en el author.id anidado. El outputData de cada trabajo en alemán y francés conserva exactamente "post-42" y "u_abc". Solo se traducen title, name y body; tags se mantiene igual porque no contiene ninguna ruta bloqueada, y sus valores de cadena se traducen como cualquier otro texto.
Vale la pena dejar bien claro ese último punto, porque responde la primera pregunta que suele hacer una persona escéptica.
¿Se traduce un valor bloqueado?
No. Una clave que indicas en lockedKeys se excluye de la traducción y su valor de origen se vuelve a insertar literalmente en outputData para cada idioma de destino. El valor que enviaste vuelve sin cambios: no se traduce, no se normaliza ni se reescribe. El bloqueo es una garantía sobre el resultado, expresada mediante lockedKeys; no es una sugerencia que se le pide al modelo que respete.
Coincide por nombre, en cualquier parte, o por posición#
Un patrón simple es un nombre de clave, y coincide con ese nombre como un segmento completo, a cualquier profundidad y en cualquier parte del árbol. Si audioSrc aparece en doce lugares anidados bajo distintos padres, el único patrón audioSrc bloquea los doce. No hace falta enumerar rutas para cubrir cada aparición: ese es el caso más común, y se resuelve en una sola línea.
Cuando necesitas control por posición —bloquear una aparición pero no otra, o todos los elementos de un arreglo y nada más— usa un glob con / como separador de ruta. Los índices de arreglos aparecen como segmentos normales, así que users/0/email y users/*/email son rutas válidas.
| Patrón | Qué bloquea |
|---|---|
audioSrc | Cada hoja audioSrc del árbol, a cualquier profundidad |
metadata | Todo el subárbol metadata dondequiera que aparezca |
metadata/author | La secuencia metadata/author dondequiera que aparezca, y todo lo que cuelgue de ella |
users/*/email | El email de cada usuario: * es un segmento y coincide con cualquier índice |
users/0/email | Solo el email del primer usuario |
**/{audioSrc,imageSrc} | Ambos nombres de hoja mediante alternancia con llaves |
Dos de los patrones anteriores bloquean más que una sola hoja, por diseño. metadata bloquea todo el subárbol bajo esa clave: se conserva cada valor que cuelga de ella, parezca traducible o no. metadata/author bloquea esa secuencia dondequiera que aparezca y todo lo que haya por debajo. Recurre a un bloqueo de subárbol cuando un bloque completo es estructural —un objeto de configuración, un embed sin procesar— y a un bloqueo de hoja (metadata/author/name) cuando solo un campo dentro de un bloque por lo demás traducible debe mantenerse.
Glob, no regex
* coincide exactamente con un segmento de ruta; ** abarca cualquier cantidad de segmentos; {a,b} usa alternancia con llaves entre alternativas. No hay coincidencia por clases de caracteres ni por fragmentos parciales: los patrones operan sobre segmentos completos de ruta, no sobre subcadenas. Escribe users/*/email, no una expresión regular.
Qué vuelve#
El bloqueo cambia lo que el modelo traduce; no cambia la forma de tu resultado. outputData refleja exactamente la estructura de entrada: las claves bloqueadas permanecen en sus posiciones originales con sus valores originales, y las cadenas traducibles a su alrededor sí se traducen. No se elimina, renombra ni reordena nada.
Para la entrada anterior, el outputData de cada idioma conserva id: "post-42" y author.id: "u_abc" sin cambios, con title, name y body en el idioma de destino. La respuesta completa del trabajo —outputData, steps por etapa y estado— está documentada en Get a single job.
Un límite, dicho desde el principio#
lockedKeys acepta hasta 100 patrones por solicitud. Ese es un tope en la cantidad de patrones, no en la cantidad de claves con las que coinciden: un solo audioSrc o users/*/email puede bloquear miles de valores en una carga útil grande y cuenta como un único patrón. Si te estás acercando a 100 patrones distintos, por lo general es señal de que un glob más amplio (**/{id,slug,href}) o un bloqueo de subárbol expresará la misma intención en muchas menos líneas.
lockedKeys también es por solicitud y ad hoc: bloquea claves solo para este grupo de trabajos. Así que, para términos que nunca deberían traducirse en ningún trabajo —un nombre de producto, una función con marca registrada, una unidad que debe mantenerse literal—, el lugar permanente es una entrada no traducible en el glosario de tu motor, aplicada automáticamente en cada llamada. Consulta Glossaries. Usa lockedKeys para campos estructurales ligados a la forma de una carga útil específica; usa el glosario para el vocabulario que se mantiene constante en todo tu contenido.
