Una carga real rara vez es solo 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 igual que 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" suena mejor localizado, o normalizar una URL, o "corregir" un enum. Basta con un identificador alterado para provocar un enlace roto o un fallo de búsqueda en producción, en cualquier idioma en el que el modelo creyó estar ayudando.
lockedKeys elimina las suposiciones. Indicas las claves que no deben cambiar —por nombre exacto o mediante un glob— y el motor de localización excluye esos valores de la traducción; después 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 estructura completa de la solicitud y la respuesta 202; esta página solo cubre qué poner en lockedKeys y cómo funciona la coincidencia.
Bloquear una clave por nombre#
Pasa lockedKeys junto con tus data. Cada entrada es un patrón; en su forma más simple, el nombre sin más de una clave que quieres 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"]
}El patrón simple id coincide con la clave id allí donde aparece como un segmento completo; aquí, tanto el id de nivel superior como 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 tal cual porque no contiene ninguna ruta bloqueada, y sus valores de cadena se traducen como cualquier otro texto.
Conviene dejar claro ese último punto, porque responde a la primera pregunta que suele hacer alguien escéptico.
¿Se traduce un valor bloqueado?
No. Una clave que indiques en lockedKeys queda excluida de la traducción, y su valor de origen se vuelve a insertar en outputData literalmente para cada idioma de destino. El valor que enviaste vuelve sin cambios: no se traduce, no se normaliza y no se reescribe. El bloqueo es una garantía sobre el resultado, expresada mediante lockedKeys, no una sugerencia que se le pide al modelo que respete.
Coincidencia por nombre, en cualquier parte, o por posición#
Un patrón simple es el nombre de una 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 elementos padre, el único patrón audioSrc bloquea los doce. No hace falta enumerar rutas para abarcar cada aparición: ese es el caso habitual, y se resuelve en una sola línea.
Cuando necesitas control posicional —bloquear una aparición pero no otra, o cada elemento de un array y nada más— usa un glob con / como separador de ruta. Los índices de array 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 allí donde aparezca |
metadata/author | La secuencia metadata/author allí donde aparezca, y además todo lo que haya por debajo |
users/*/email | El email de cada usuario: * es un segmento y coincide con cualquier índice |
users/0/email | Solo el correo electrónico 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, y es intencionado. metadata bloquea todo el subárbol bajo esa clave: se preserva cada valor que haya debajo, parezca traducible o no. metadata/author bloquea esa secuencia allí donde aparezca y todo lo que haya por debajo. Recurre a un bloqueo de subárbol cuando un bloque entero es estructural —un objeto de configuración, una inserción en bruto—, y a un bloqueo de hoja (metadata/author/name) cuando solo un campo dentro de un bloque por lo demás traducible debe mantenerse fijo.
Glob, no regex
* coincide exactamente con un segmento de ruta; ** abarca cualquier número de segmentos; {a,b} es alternancia con llaves entre alternativas. No hay coincidencia por clases de caracteres ni por coincidencias 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 traduce el modelo; no cambia la forma del resultado. outputData refleja exactamente la estructura de entrada: las claves bloqueadas se mantienen en sus posiciones originales con sus valores originales, y las cadenas traducibles que las rodean 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, claro desde el principio#
lockedKeys acepta hasta 100 patrones por solicitud. Ese es un límite del número de patrones, no del número de claves con las que coinciden: un solo audioSrc o users/*/email puede bloquear miles de valores en una carga grande, y cuenta como un único patrón. Si te estás acercando a 100 patrones distintos, normalmente 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 específico de cada solicitud y ad hoc: bloquea claves solo para este grupo de trabajos. Por eso, para términos que no deberían traducirse nunca en ningún trabajo —un nombre de producto, una funcionalidad con marca registrada, una unidad que debe mantenerse literal—, el lugar adecuado y duradero 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 concreta; usa el glosario para el vocabulario que se mantiene constante en todo tu contenido.
