Ámbitos de traducción

Selecciona archivos y claves estables sin mezclar las actualizaciones incrementales, la cobertura de los destinos y la regeneración deliberada.

Un cambio de localización puede afectar a un archivo, a un idioma o a un conjunto de mensajes. La CLI selecciona cada una de estas dimensiones de forma distinta: la configuración del proyecto selecciona los archivos y los idiomas de destino; los patrones posicionales acotan los archivos y modifican la planificación; --key selecciona los mensajes por clave estable.

El ámbito de archivos modifica el plan #

sh
lingo push 'locales/en.json' --wait

El patrón acota los archivos de origen configurados. En los formatos con archivos separados, este comando crea los destinos que faltan y deja intactos los existentes, aunque el origen haya cambiado. Si deja fuera del trabajo algunos idiomas configurados, conserva la referencia de origen existente para que un push posterior sin opciones adicionales pueda procesar esos cambios. Si aún no hay una referencia, puede inicializarla.

Para los cambios habituales en el origen, usa lingo push --wait sin opciones adicionales. Para sustituir deliberadamente archivos completos en formatos con archivos separados, especifica un ámbito posicional con --force y ten en cuenta que el modo forzado descarta el contexto de destino existente. Los catálogos XCStrings pueden seguir reutilizando las traducciones integradas; consulta actualizaciones de catálogos. Los destinos siempre se obtienen de targetLocales; push no dispone de las opciones --locale ni --target-locale.

Regeneración por clave estable #

sh
lingo push 'locales/en.json' --key 'checkout.title' --key 'checkout.submit' --wait

Repite --key para realizar varias selecciones. Una clave es una ruta con puntos o corchetes, como checkout.title o items[0].title. Al seleccionar un objeto, se incluyen todas las cadenas que contiene. Así, auth.login incluye auth.login.title sin seleccionar auth.login_url. * representa un segmento completo y [] representa cada elemento de una matriz; los comodines parciales, como auth.log*, se rechazan. Un patrón que empieza por $. o $[ se procesa como una consulta JSONPath. Escribe entre comillas los patrones con comodines.

Los patrones escritos para la CLI anterior con / también funcionan. Un patrón que contiene / se divide únicamente por /, y cada nombre se trata como una unidad: auth/login selecciona las mismas claves que auth.login, y common/error.message selecciona la clave error.message dentro de common. Los nombres con codificación porcentual, como legal/Terms%20of%20use, se descodifican; un patrón sin / es una ruta con puntos y no se descodifica, así que, para un único nombre codificado, usa JSONPath, como $['Terms of use']. Como todos los patrones con / se interpretan de esta forma, una clave cuyo nombre contenga / debe expresarse con JSONPath, como $.routes['/about'].title. En este formato, * representa un nombre completo, y un * al final, como en auth/*, selecciona los valores situados directamente bajo auth, pero no los objetos ni las matrices anidados en él, igual que hacía la CLI anterior. Un /** al final abarca todo lo que hay bajo el nombre que lo precede: auth/** equivale a auth, y auth/*/** también abarca los objetos y las matrices bajo auth que auth/* deja fuera. Un número como items/0 selecciona el elemento de la matriz o la clave de objeto "0", según lo que contenga el documento. Se rechazan los patrones de comodines dentro de un nombre, ** en cualquier posición que no sea la final, los corchetes y los nombres vacíos, como a//b.

FormatosÁmbito de claves
JSON/JSONC, PHP, TypeScript, archivos de propiedades de JavaRegenera las cadenas seleccionadas, incluidos los valores de origen que no han cambiado.
YAML/YAML con clave raízSelecciona claves estables, pero las cadenas seleccionadas que no han cambiado pueden reutilizar las traducciones existentes.
gettext, ARB, Apple strings, XCStrings, CSV, Android, XLIFFNo se admite; --key detiene el push con un error.
Markdown, MDX, Markdoc, HTML, OpenAPI YAML, SubRip, texto sin formato, Apple stringsdictSin claves estables; se omiten con un mensaje.

La regeneración por clave requiere destinos existentes. Los idiomas que faltan y los formatos sin claves estables se omiten con mensajes en lugar de inicializarse. La operación de completado crea los archivos ordinarios que faltan, pero no cubre los huecos dentro de los existentes. Añadir --force no cambia la planificación por claves ni impide la reutilización en YAML.

La regeneración por clave deja intacta la referencia del origen completo, tanto si la recoge push --wait como si lo hace un pull independiente. Por tanto, los cambios ordinarios pendientes en el origen se seguirán procesando en el siguiente push sin opciones adicionales.

Regenerar tras cambiar las directrices #

Editar el glosario o las reglas de un motor de localización no modifica los bytes de los archivos de origen. Por eso, un push sin opciones adicionales puede no hacer nada. Para JSON, JSONC, TypeScript y PHP, selecciona las claves estables afectadas. Para YAML, edita directamente el destino si necesitas una corrección precisa, o guarda los destinos aceptados y usa --force con un ámbito de archivos completos y sin --key para regenerarlos. Revisa todo el archivo resultante, porque esa sustitución también puede modificar los mensajes cercanos. Los controles de claves determinan qué valores de origen o de destino se conservan durante la reconstrucción; no seleccionan el trabajo que se va a realizar.

Para un cambio de gran alcance, elige un ámbito lo bastante pequeño como para poder revisarlo y recuperarlo. Después, obtén una estimación antes de enviarlo. La estimación sube los archivos necesarios y planifica el trabajo sin crear un trabajo de traducción.

Volver a traducir un solo idioma #

En un proyecto con un archivo separado para cada idioma, elimina los destinos de ese idioma y crea los archivos que faltan con la operación de completado. Antes, termina las actualizaciones pendientes del origen y guarda las traducciones aceptadas. La purga filtrada conserva las referencias de origen y las entradas del Lockfile de los demás idiomas.

Para un origen configurado en locales/en.json, previsualiza la eliminación del destino en francés:

sh
lingo purge --locale fr --file locales/en.json

Revisa las rutas indicadas. Si corresponden a los destinos que quieres eliminar, confirma la eliminación y crea las traducciones que faltan:

sh
lingo purge --locale fr --file locales/en.json --yes
lingo push --backfill-missing --wait

Si la configuración usa patrones de comodines, como locales/en/*.json, indica rutas de origen concretas repitiendo la opción --file en ambos comandos de purga. La purga no expande esos patrones por sí sola. Incluye todos los orígenes cuyos destinos en francés quieras regenerar y comprueba que no falten otros archivos de destino antes de ejecutar backfill: backfill crea todos los destinos configurados que faltan.

Al terminar, revisa el resultado en francés y confirma los cambios junto con el Lockfile actualizado. Los archivos de destino existentes de los demás idiomas permanecen intactos. Consulta Purga para conocer las reglas de selección. Este procedimiento no se aplica a los catálogos XCStrings, donde el origen y todos los idiomas de destino comparten un único archivo.