Alcances de traducción
Selecciona archivos y claves estables manteniendo separadas las actualizaciones incrementales, la cobertura de destinos y la regeneración intencional.
Un cambio de localización puede afectar un archivo, un idioma o un conjunto de mensajes. La CLI selecciona cada dimensión de forma distinta: la configuración del proyecto selecciona los archivos y los idiomas de destino; los patrones posicionales delimitan los archivos y modifican la planificación; --key selecciona los mensajes por clave estable.
El alcance por archivo cambia el plan #
lingo push 'locales/en.json' --waitEl patrón delimita los archivos de origen configurados. En un formato con archivos separados, este comando crea los destinos faltantes y deja los existentes sin cambios, incluso si el origen cambió. Si deja fuera del trabajo algún idioma configurado, conserva la referencia de origen existente para que una ejecución posterior de push sin opciones adicionales pueda procesar esas modificaciones. Si aún no existe una referencia, puede inicializarla.
Para las modificaciones habituales del origen, usa lingo push --wait sin opciones adicionales. Para reemplazar intencionalmente archivos completos en formatos con archivos separados, especifica un alcance posicional con --force, teniendo en cuenta que forzar el reemplazo descarta el contexto del destino existente. Los catálogos XCStrings pueden seguir reutilizando las traducciones integradas; consulta actualizaciones de catálogos. Los destinos siempre provienen de targetLocales; push no tiene las opciones --locale ni --target-locale.
Regeneración por clave estable #
lingo push 'locales/en.json' --key 'checkout.title' --key 'checkout.submit' --waitRepite --key para hacer 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 un arreglo; los comodines parciales, como auth.log*, se rechazan. Un patrón que comienza con $. o $[ se procesa como una consulta JSONPath. Escribe los patrones con comodines entre comillas.
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 completa: 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 decodifican; un patrón sin / es una ruta con puntos y no se decodifica, así que escribe un nombre codificado individual como JSONPath, por ejemplo, $['Terms of use']. Como todos los patrones con / se interpretan de esta manera, una clave cuyo nombre contiene / requiere JSONPath, por ejemplo, $.routes['/about'].title. En esta forma, * representa un nombre completo, y un * al final, como en auth/*, selecciona los valores directamente dentro de auth, pero no los objetos ni los arreglos anidados allí, tal como lo hacía la CLI anterior. Un /** al final abarca todo lo que está dentro del nombre que lo precede: auth/** equivale a auth, y auth/*/** también abarca los objetos y arreglos dentro de auth que auth/* deja fuera. Un número como items/0 selecciona el elemento del arreglo o la clave de objeto "0", según lo que contenga el documento. Se rechazan los patrones glob dentro de un nombre, ** antes del final, los corchetes y los nombres vacíos, como a//b.
| Formatos | Alcance por clave |
|---|---|
| JSON/JSONC, PHP, TypeScript, archivos de propiedades de Java | Regenera las cadenas seleccionadas, incluidos los valores de origen que no cambiaron. |
| YAML/YAML con claves raíz | Selecciona claves estables, pero las cadenas seleccionadas que no cambiaron pueden reutilizar las traducciones existentes. |
| gettext, ARB, Apple strings, XCStrings, CSV, Android, XLIFF | No compatible; --key detiene push con un error. |
| Markdown, MDX, Markdoc, HTML, OpenAPI YAML, SubRip, texto sin formato, Apple stringsdict | Sin claves estables; se omiten con un mensaje. |
La regeneración por clave requiere destinos existentes. Los idiomas faltantes y los formatos sin claves estables se omiten con mensajes en lugar de inicializarse. La operación de completar archivos faltantes crea los archivos comunes que faltan, pero no rellena los huecos dentro de los existentes. Agregar --force no cambia la planificación por clave ni impide la reutilización en YAML.
La regeneración por clave deja intacta la referencia del origen completo, tanto si la recopila push --wait como si lo hace una ejecución independiente de pull. Por eso, las modificaciones habituales pendientes del origen se siguen procesando en la siguiente ejecución de push sin opciones adicionales.
Regenerar después de cambiar las pautas #
Editar el glosario o las reglas de un motor de localización no modifica los bytes de los archivos de origen. Por eso, una ejecución de push sin opciones adicionales puede no hacer nada. Para JSON, JSONC, TypeScript y PHP, selecciona las claves estables afectadas. Para YAML, edita el destino directamente si necesitas una corrección precisa, o guarda los destinos aceptados y usa --force con un alcance de archivos completos, sin --key, para regenerarlos. Revisa todo el archivo resultante, porque ese reemplazo también puede cambiar los mensajes cercanos. Los controles de claves determinan qué valores de origen o destino se conservan durante la reconstrucción; no seleccionan el trabajo que se realizará.
Para un cambio grande, elige un alcance lo suficientemente pequeño como para revisarlo y recuperarlo; luego, obtén una estimación antes de enviarlo. La estimación carga 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 completa los archivos faltantes. Primero, termina las actualizaciones pendientes del origen y guarda las traducciones aceptadas. La eliminación filtrada conserva las referencias de origen y las entradas del Lockfile para los demás idiomas.
Para un origen configurado en locales/en.json, obtén una vista previa de la eliminación del destino en francés:
lingo purge --locale fr --file locales/en.jsonRevisa las rutas indicadas. Si corresponden a los destinos que quieres eliminar, confirma la eliminación y crea las traducciones faltantes:
lingo purge --locale fr --file locales/en.json --yes
lingo push --backfill-missing --waitPara una configuración que usa patrones glob, como locales/en/*.json, especifica rutas de origen concretas repitiendo la opción --file en ambos comandos purge. Purge no expande los patrones glob por sí mismo. Incluye todos los orígenes cuyo destino en francés quieras regenerar y verifica que no falten otros archivos de destino antes de completar los archivos faltantes: esta operación crea todos los destinos configurados que faltan.
Al finalizar, revisa el resultado en francés y crea un commit que lo incluya junto con el Lockfile actualizado. Los archivos de destino existentes para otros idiomas permanecen sin cambios. Consulta Eliminación 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 solo archivo.