Blog

Claves de traducción que se mantienen consistentes en toda una aplicación

Cómo localize.dev nombra las claves, las reutiliza para texto repetido, separa copias cortas y ambiguas, y nota cuándo el texto fuente cambia después de haber sido traducido.

Stephen Ufort · 6 de noviembre de 2026 · 3 min de lectura

La solicitud de extracción de Pages CMS: 535 cadenas en 73 archivos movidas a react-i18next, con claves y traducciones

Las claves escritas a mano se desvían. Una persona escribe save_button, otra buttons.save, una tercera common.actions.save, y tres claves contienen la misma palabra. Pedir a un agente de codificación que extraiga cadenas de una en una se desvía de la misma manera, porque cada archivo comienza sin conocer las claves que los otros crearon.

localize.dev nombra las claves para toda la aplicación en una ejecución, y las recuerda para la siguiente. Esta publicación cubre cómo.

Quién nombra la clave

El modelo propone cada clave a partir de la ruta del archivo, el componente y la cadena. Las reglas que recibe son cortas: segmentos en snake case en minúsculas unidos por puntos, un espacio de nombres para la función o pantalla, y un nombre para lo que hace la cadena, no una transliteración de la misma. src/components/AuthForm.tsx da auth.*; un encabezado se convierte en auth.welcome_heading, no en auth.welcome_back_we_missed_you.

Todo lo demás es código. Cada clave propuesta se limpia y registra. Si dos cadenas diferentes obtienen el mismo nombre, la segunda obtiene un sufijo _2, y una clave que chocaría con una rama existente del archivo de idioma se renombra para que ninguna sobrescriba a la otra.

El mismo texto obtiene la misma clave

Antes de que una cadena se envíe al modelo, el motor comprueba si ese texto ya tiene una clave, ya sea en su archivo de idioma de origen o de antes en la misma ejecución. Si es así, el código llama a esa clave nuevamente y el modelo nunca ve la cadena. Una ejecución informa de esto como claves reutilizadas, contando cada lugar donde aparece el texto, por lo que diez botones de "Cancelar" son diez reutilizaciones de una clave.

Texto corto que significa dos cosas

La reutilización solo por texto es incorrecta para copias cortas. "Publicar" en un botón es un verbo, y en el título de una tarjeta es un sustantivo. Muchos idiomas usan palabras diferentes para cada uno.

Una copia de tres palabras o menos, hasta 40 caracteres, sin marcadores de posición ni etiquetas, tiene sentido junto a su texto: el elemento y el atributo en el que se encuentra, como button o input[placeholder]. "Publicar" en un <button> y "Publicar" en un <h3> se convierten en mensajes separados, y cada uno se envía con una pista sobre dónde aparece.

context sent with a string
"placeholder" attribute on <input> in component <Login>
element text inside <button> in component <Composer>

Cuando las traducciones de los dos sentidos vuelven iguales en todos los idiomas, se fusionan en una sola clave. Cuando difieren, ambas claves permanecen. Solo obtienes una segunda clave donde realmente la necesita un idioma.

Saber cuándo cambió el texto fuente

Las claves solo ayudan si sus traducciones se mantienen en línea con la fuente. Cuando alguien cambia "Guardar" a "Guardar cambios" en en.json, todas las traducciones de esa clave están desactualizadas, pero el archivo no lo indica.

localize.lock.json registra una huella digital de cada mensaje fuente en el momento en que fue traducido: los primeros 12 caracteres hexadecimales de su SHA-256. Confírmalo con tu código. En la próxima ejecución, un mensaje cuya huella digital ya no coincida será traducido nuevamente, y localize-dev check fallará en CI con un error de "Traducciones desactualizadas" que nombra las claves.

Claves en otros stacks

No todos los stacks usan claves punteadas. Los archivos JSON de Laravel y los catálogos gettext usan el texto fuente como clave, así que localize.dev también. Las claves ARB de Flutter están en camelCase y las de Android en snake_case, porque así lo esperan sus herramientas.

Pruébalo en tu propio código en la zona de juegos, no se necesita cuenta