Configuración de la CLI
Define cómo se detectan los archivos de origen, las opciones de traducción y las rutas de destino en .lingo/config.json.
.lingo/config.json describe qué archivos traduce un proyecto y dónde deben guardarse sus archivos de destino. La CLI busca la configuración más cercana desde el directorio de trabajo hacia los directorios superiores y resuelve las rutas relativas al proyecto a partir de esa raíz. Los comandos locales del catálogo usan cwd cuando no hay ninguna configuración.
{
"sourceLocale": "en",
"targetLocales": ["de", "fr"],
"files": [{ "pattern": "locales/en.json" }]
}Ejecuta link para añadir los ID de la organización y del motor de localización necesarios para la traducción remota. La extracción puede usar los ajustes de i18n localmente sin esos ID. Usa JSON estricto: no se admiten comentarios ni comas finales.
Campos raíz #
| Campo | Significado |
|---|---|
orgId, engineId | ID de recursos no vacíos; juntos definen la vinculación remota. |
sourceLocale | Cadena no vacía que indica el idioma de origen. |
targetLocales | Entradas con cadenas no vacías; durante la ejecución se eliminan los duplicados y la coincidencia exacta con el idioma de origen. |
files | Entradas de origen descritas a continuación. |
i18n.messagesPath | Directorio del catálogo para extracción, comprobación y limpieza; valor predeterminado: locales. |
i18n.typesPath | Ruta de declaraciones para extracción y comprobación; valor predeterminado: lingo.d.ts. |
github.workflows.onPushToDefaultBranch.enabled | Activador opcional de la integración para la rama predeterminada. |
github.workflows.onPullRequest.enabled | Activador opcional de la integración para solicitudes de incorporación de cambios. |
github.safety.requireApproval | Ajuste opcional para aprobar las ejecuciones de la integración. |
Las claves desconocidas en la raíz y en las entradas de archivo generan advertencias y se ignoran. Un error tipográfico puede hacer que se siga aplicando un valor predeterminado en lugar de rechazar todo el archivo.
Init escribe los ajustes de localización; link escribe los ID de vinculación; unlink elimina solo esos ID. Las operaciones de escritura conservan las demás secciones raíz, pero init --force reconstruye las entradas de archivo y descarta las opciones avanzadas. Los ajustes de GitHub no instalan la aplicación ni hacen que un envío desde la CLI active la automatización del repositorio; usa la configuración de la integración.
Campos de las entradas de archivo #
| Campo | Significado |
|---|---|
pattern | Un patrón de origen no vacío. |
include | Patrones de origen; tienen prioridad sobre pattern, incluso si la lista está vacía. |
exclude | Patrones excluidos de esta entrada. |
format | Formato explícito de la lista de formatos admitidos que aparece a continuación. |
localeFormat | Representación de la ruta en bcp47, underscore o android. |
targetPath, sourceRoot | Plantilla de salida y prefijo opcional que se elimina para [path]. |
translateFrontmatterFields | Campos de metadatos seleccionados por los procesadores de la familia Markdown. |
translateComponentProps | Nombres de propiedades o reglas de propiedades filtradas por componente. |
lockedKeys, preservedKeys, ignoredKeys | Listas no vacías de rutas de claves para los procesadores que las admiten. |
injectLocale | Booleano o { "enabled": true, "key": "language" }. |
keyColumn | Solo CSV: encabezado de la columna de claves; por defecto, la primera celda del encabezado. |
lockedPatterns | Solo para archivos properties: las expresiones regulares RE2 de los valores se mantienen sin traducir. |
Cada entrada necesita pattern o include; un include vacío no selecciona nada. La primera entrada que coincide determina las opciones. Controles de claves explica a quién pertenecen los valores y los límites de los formatos.
Patrones de archivos #
El sistema de coincidencias admite * dentro de un segmento y **/ entre directorios. Usa docs/en/**/* para un subárbol recursivo; un ** al final, por sí solo, no significa lo mismo. No des por hecho que las llaves o los patrones extglob se comportan como en otras bibliotecas de patrones glob.
{
"sourceLocale": "en",
"targetLocales": ["de"],
"files": [
{
"include": ["docs/en/**/*.md", "docs/en/**/*.mdx"],
"exclude": ["docs/en/private/**/*"]
}
]
}Una exclusión solo se aplica a su entrada; otra entrada puede seguir incluyendo el archivo. La detección omite .git y node_modules, pero no todo el contenido de .gitignore. Los patrones posicionales de envío restringen aún más la selección a los archivos que también coinciden con los orígenes configurados y cambian el modo de planificación. Escríbelos entre comillas en la línea de comandos.
Selección de formato #
Los formatos configurados son json, jsonc, md, mdx, markdoc, yaml-openapi, po, flutter, xcode-strings, yaml, android, typescript, xcode-xcstrings, srt, xliff, xcode-stringsdict, php, yaml-root-key, html, txt, csv y properties.
| Sufijo | Formato inferido |
|---|---|
.json, .jsonc | JSON o JSONC. |
.md, .mdx, .mdoc | Markdown, MDX, Markdoc. |
.html, .htm | HTML. |
.po, .arb | Gettext, Flutter. |
.strings, .xcstrings, .stringsdict | Formato de Apple correspondiente. |
.ts, .mts, .cts | TypeScript. |
.srt, .xlf, .xliff, .php | SubRip, XLIFF, PHP. |
.txt | Texto sin formato, solo si el patrón termina en .txt o se especifica el formato txt. |
.csv | CSV, solo si el patrón termina en .csv o se especifica el formato csv. |
.properties | Archivos properties de Java, solo si el patrón termina en el formato .properties o properties. |
.yaml, .yml | Especifica explícitamente yaml, yaml-root-key u OpenAPI basado en yaml. |
.xml | Especifica android explícitamente; no se admite XML genérico. |
Para OpenAPI, el identificador exacto es yaml-openapi. Seleccionar el formato de forma explícita tampoco permite eludir la lista de sufijos admitidos por el proceso de detección. Un archivo .txt, .csv o .properties solo se asocia a una entrada cuyo patrón termine en esa extensión o que especifique el formato correspondiente, txt, csv o properties. Esa entrada solo selecciona archivos con dicha extensión. Los archivos .js, .tsx, .pot, MJML y VTT no están configurados como archivos de entrada de la CLI. La extracción de React TSX es una operación distinta.
La traducción de HTML actualiza el texto y los atributos seleccionados en el código de origen y conserva el marcado, los comentarios y el formato que no se hayan modificado. Un elemento <html> explícito recibe el idioma de destino en su atributo lang; los fragmentos siguen siendo fragmentos. Consulta HTML para conocer cómo se selecciona el texto y cómo se genera la salida.
Formatos describe el comportamiento de los analizadores, incluidas las estructuras que se omiten y los límites de reconstrucción. Los procesadores compartidos del servidor no amplían esta enumeración de la CLI.
Rutas de salida #
Usa una plantilla explícita cuando las rutas de origen no indiquen su idioma:
{
"sourceLocale": "en",
"targetLocales": ["de", "fr"],
"files": [
{
"pattern": "docs/**/*.md",
"sourceRoot": "docs",
"targetPath": "i18n/[locale]/docs/[path]"
}
]
}docs/start.md se convierte en i18n/de/docs/start.md y i18n/fr/docs/start.md. [locale] usa la representación del idioma de la entrada; [path] elimina la raíz de origen respetando los límites de los segmentos. Una raíz de docs no elimina parte de docsite.
Las plantillas requieren [locale]; las entradas con patrones glob también requieren [path]. Estos son los únicos marcadores de posición. Se rechazan las rutas absolutas, .., las raíces con patrones glob, las raíces fuera de las entradas y las salidas que se vuelven a detectar como orígenes configurados. sourceRoot sin targetPath no es válido. El envío también comprueba si hay colisiones entre las rutas de salida sin distinguir entre mayúsculas y minúsculas.
El envío, la descarga y la purga también siguen las rutas del sistema de archivos: si un origen, un destino, .lingo/lock.json o .lingo/config.json se resuelve fuera de la raíz del proyecto o dentro de .git, por ejemplo mediante un enlace simbólico, el comando se detiene con un error antes de leer, escribir o eliminar nada allí. Los enlaces que permanecen dentro del proyecto siguen funcionando, pero no se escribe a través de un destino o un Lockfile que sea en sí mismo un enlace. En un monorepositorio, ejecuta los comandos desde una raíz que contenga los archivos compartidos en lugar de enlazarlos desde un paquete.
Sin una plantilla, la ruta se deriva probando, por este orden, un directorio del idioma de origen, el nombre completo del archivo sin extensión y las estructuras de las plataformas; como último recurso, se inserta un directorio de idioma y se emite una advertencia. Algunos ejemplos son locales/en.json → locales/de.json, app_en.arb → app_de.arb, Base.lproj → un destino .lproj y, en Android, values → recursos específicos del idioma. Lee las advertencias y confirma que la aplicación carga ese destino.
XCStrings y CSV almacenan todos los idiomas en el archivo de origen y rechazan targetPath. Las salidas de varios idiomas comparten ese archivo de forma intencionada; que exista no demuestra que contenga cada idioma. La purga omite el archivo compartido, por lo que no puede eliminar las entradas de un idioma concreto.
Seleccionar metadatos y texto de componentes #
Cuando se omite la opción, la traducción de la familia Markdown selecciona title y description de los metadatos de cabecera. Una lista vacía desactiva la selección; una lista explícita selecciona otros campos. Las rutas anidadas de valores escalares y listas requieren metadatos de cabecera que se puedan analizar; si están mal formados, se puede recurrir al análisis del nivel superior.
{
"pattern": "docs/en/**/*.mdx",
"translateFrontmatterFields": ["title", "description"],
"translateComponentProps": ["aria-label", { "component": ["Card", "Callout"], "props": ["title"] }]
}Una cadena selecciona una propiedad sin filtrar por componente. Un objeto selecciona props y puede restringir los nombres de los componentes. Estas reglas seleccionan contenido literal traducible, no el código de los componentes ni todos sus atributos. Markdown, MDX y Markdoc funcionan de forma distinta; comprueba el procesador al cambiar de rutas.
Para dar indicaciones de traducción en JSONC, coloca @context inmediatamente antes de la cadena correspondiente. La salida general de JSONC conserva las marcas @orphan, pero elimina los demás comentarios. Por eso, los metadatos @src de React necesitan la política de carga del catálogo; no des por hecho que la descarga los conserva.
En los entornos de documentación, elige los directorios reales de origen y salida por separado del enrutamiento. OpenAPI usa yaml-openapi; las raíces de idioma al estilo de Rails usan yaml-root-key; YAML genérico usa yaml. Que la extensión coincida no basta para seleccionar la semántica adecuada.
Idiomas #
La configuración valida que las cadenas no estén vacías, en lugar de comprobarlas contra una enumeración exhaustiva de idiomas. Usa los identificadores que necesiten tu modelo y tu aplicación, incluida la región o el sistema de escritura. localeFormat controla las rutas: bcp47 conserva los guiones, underscore produce pt_BR y android produce formas como pt-rBR o b+zh+Hans. El formato Android selecciona la representación de Android salvo que se indique otra; esto también afecta a las coincidencias de origen.
Completa las actualizaciones habituales pendientes del origen antes de añadir un destino y generar los archivos que le faltan. Añadir un idioma explica cómo este orden mantiene al día los idiomas existentes. Eliminar un destino impide que se seleccione en el futuro, pero no borra los archivos existentes. Los metadatos de idioma integrados y los catálogos compartidos deben seguir las reglas de su procesador. Una ruta escrita correctamente no garantiza la dirección del texto, el enrutamiento ni la calidad lingüística.
Rutas del catálogo #
Para la extracción y la comprobación, se aplican primero los valores explícitos de --out/--types, después los ajustes de i18n y, por último, los valores predeterminados. --source-locale tiene como valor predeterminado en, independientemente del ajuste de localización sourceLocale. Cambiar messagesPath no actualiza files[]; selecciona la ruta del JSONC generado para traducirlo.
Monorepositorios #
Una configuración raíz permite compartir idiomas y un motor de localización entre rutas de paquetes recursivas o explícitas. Como alternativa, las configuraciones por paquete permiten mantener independientes los idiomas, la configuración y los archivos Lockfile. Ejecuta los comandos desde la raíz del paquete que quieras usar para que la búsqueda de la configuración más cercana no seleccione por sorpresa la de un directorio superior.
Una matriz de directorios de CI debe conservar la salida recopilada de cada proyecto y evitar que se solapen las operaciones de escritura. Los punteros de ejecución locales del directorio personal dependen de raíces absolutas y no se comparten mediante un Lockfile. lingo check compara cada archivo de origen seleccionado por files con el Lockfile a nivel de archivo; no comprueba las claves de su interior.
Configuración de puntuación #
lingo score usa el archivo ejecutable lingo.config.ts, cargado mediante Jiti. Es independiente del JSON del proyecto y no registra cargadores locales de formatos arbitrarios. Mantén separados los complementos de puntuación de confianza y los ajustes remotos de localización de archivos.