Configuración de la CLI

Define cómo detectar 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 los archivos de destino. La CLI busca la configuración más cercana desde el directorio de trabajo hacia los directorios superiores y usa esa raíz para resolver las rutas relativas al proyecto. Los comandos locales de catálogo usan cwd cuando no hay una configuración.

json
{
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "files": [{ "pattern": "locales/en.json" }]
}

Ejecuta link para agregar los ID de la organización y del motor de localización necesarios para la traducción remota. La extracción puede usar la configuración de i18n de forma local sin esos ID. Usa JSON estricto: no se aceptan comentarios ni comas finales.

Campos raíz #

CampoSignificado
orgId, engineIdID de recursos no vacíos; juntos establecen la vinculación remota.
sourceLocaleCadena no vacía que indica el idioma de origen.
targetLocalesEntradas con cadenas no vacías; durante la ejecución se eliminan los duplicados y la coincidencia exacta con el idioma de origen.
filesEntradas de origen descritas a continuación.
i18n.messagesPathDirectorio del catálogo para extracción, verificación y limpieza; valor predeterminado: locales.
i18n.typesPathRuta de declaraciones para extracción y verificación; valor predeterminado: lingo.d.ts.
github.workflows.onPushToDefaultBranch.enabledActivador opcional de la integración para la rama predeterminada.
github.workflows.onPullRequest.enabledActivador opcional de la integración para solicitudes de incorporación de cambios.
github.safety.requireApprovalConfiguración 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 de escritura puede dejar vigente un valor predeterminado en lugar de provocar el rechazo de todo el archivo.

Init escribe la configuración 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. La configuración de GitHub no instala la aplicación ni hace que un push de la CLI active la automatización del repositorio; usa la configuración de la integración.

Campos de las entradas de archivo #

CampoSignificado
patternUn patrón de origen no vacío.
includePatrones de origen; tienen prioridad sobre pattern, incluso si la lista está vacía.
excludePatrones excluidos de esta entrada.
formatFormato explícito de la lista de formatos compatibles que aparece a continuación.
localeFormatRepresentación de ruta bcp47, underscore o android.
targetPath, sourceRootPlantilla de salida y prefijo opcional que se elimina para [path].
translateFrontmatterFieldsCampos de metadatos seleccionados por los procesadores de la familia Markdown.
translateComponentPropsNombres de propiedades o reglas de propiedades filtradas por componente.
lockedKeys, preservedKeys, ignoredKeysArreglos no vacíos de rutas de claves para los procesadores que los admiten.
injectLocaleBooleano o { "enabled": true, "key": "language" }.
keyColumnSolo CSV: encabezado de la columna de claves; de forma predeterminada, se usa la primera celda del encabezado.
lockedPatternsSolo para propiedades: las expresiones regulares RE2 no se traducen en los valores.

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 quién controla los valores y los límites de cada formato.

Patrones de archivo #

El comparador 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 extglob se comportan como en otra biblioteca de patrones glob.

json
{
  "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 incluir el mismo archivo. La detección omite .git y node_modules, no todo el contenido de .gitignore. Los patrones posicionales de push restringen aún más la selección a su intersección con los orígenes configurados y cambian el modo de planificación. Escríbelos entre comillas en el intérprete 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.

SufijoFormato inferido
.json, .jsoncJSON o JSONC.
.md, .mdx, .mdocMarkdown, MDX, Markdoc.
.html, .htmHTML.
.po, .arbGettext, Flutter.
.strings, .xcstrings, .stringsdictFormato de Apple correspondiente.
.ts, .mts, .ctsTypeScript.
.srt, .xlf, .xliff, .phpSubRip, XLIFF, PHP.
.txtTexto sin formato, solo para un patrón que termine en .txt o que use el formato txt.
.csvCSV, solo para un patrón que termine en .csv o que use el formato csv.
.propertiesPropiedades de Java, solo para patrones que terminen en el formato .properties o properties.
.yaml, .ymlConfigura explícitamente yaml, yaml-root-key u OpenAPI basado en yaml.
.xmlConfigura android explícitamente; no se admite XML genérico.

Para OpenAPI, el identificador exacto es yaml-openapi. Seleccionar el formato de forma explícita no permite eludir la lista de sufijos admitidos por el proceso de detección. Un archivo .txt, .csv o .properties solo corresponde a una entrada cuyo patrón termina con esa extensión o que especifica el formato correspondiente, txt, csv o properties. Esa entrada selecciona únicamente archivos con esa 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 fuente original y conserva el marcado, los comentarios y el formato que no se modifican. 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 del analizador, incluidas las estructuras omitidas 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 identifiquen su idioma:

json
{
  "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 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 vuelven a detectarse como orígenes configurados. sourceRoot sin targetPath no es válido. Push también comprueba si hay colisiones entre rutas de salida sin distinguir mayúsculas de minúsculas.

Push, pull y purge también siguen el sistema de archivos: si un origen, 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 algo 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 derivación prueba, en este orden, un directorio del idioma de origen, el nombre completo del archivo sin extensión, las estructuras de plataforma y, por último, la inserción de un directorio de idioma con una advertencia. Algunos ejemplos son locales/en.json → locales/de.json, app_en.arb → app_de.arb, Base.lproj → un .lproj de destino y Android values → recursos con identificador de idioma. Lee las advertencias y confirma que la aplicación cargue 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 intencional; que el archivo exista no demuestra que contenga todos los idiomas. Purga omite el archivo compartido, por lo que no puede eliminar entradas de idiomas individuales.

Seleccionar metadatos y texto de componentes #

La traducción de la familia Markdown selecciona title y description de los metadatos iniciales cuando se omite la opción. Una lista vacía desactiva la selección; una lista explícita selecciona otros campos. Las rutas anidadas de valores escalares y arreglos requieren metadatos iniciales que se puedan analizar; si están mal formados, se puede recurrir al escaneo de nivel superior.

json
{
  "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 componentes. Estas reglas seleccionan contenido literal traducible, no el código del componente ni todos sus atributos. Markdown, MDX y Markdoc funcionan de manera distinta; revisa el procesador al cambiar de rutas.

Para dar indicaciones al traductor en JSONC, coloca @context inmediatamente antes de su cadena. La salida general de JSONC conserva las marcas @orphan, pero elimina los demás comentarios. Por eso, para los metadatos @src de React debes seguir la política de carga del catálogo, en lugar de asumir que pull los conserva.

Para 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. Una extensión coincidente, por sí sola, no permite seleccionar la semántica correcta.

Idiomas #

La configuración valida que las cadenas no estén vacías, en lugar de compararlas con 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 la coincidencia de los orígenes.

Completa las actualizaciones habituales pendientes del origen antes de agregar un destino y generar los archivos que le faltan. Agregar un idioma explica cómo ese orden mantiene actualizados los idiomas existentes. Eliminar un destino impide que se seleccione en el futuro, sin borrar 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 determina la dirección, el enrutamiento ni la calidad del idioma.

Rutas del catálogo #

Para la extracción y la verificación, los valores explícitos de --out/--types tienen prioridad sobre la configuración de i18n; después se usan los valores predeterminados. --source-locale usa en como valor predeterminado, independientemente de sourceLocale de localización. Cambiar messagesPath no actualiza files[]; selecciona la ruta JSONC generada para la traducción.

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, una configuración por paquete permite mantener separados los idiomas, la configuración y los archivos Lockfile. Ejecuta los comandos desde la raíz del paquete deseado para evitar que la búsqueda de la configuración más cercana seleccione inesperadamente la de un directorio superior.

Una matriz de directorios de CI debe conservar la salida recopilada de cada proyecto y evitar operaciones de escritura superpuestas. 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 verifica las claves que contienen.

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 para formatos arbitrarios. Mantén separados los complementos de puntuación de confianza y la configuración remota de localización de archivos.