Formatos

La CLI traduce dieciocho formatos de archivo. El formato se deduce a partir de la extensión del archivo; para sobrescribirlo, configura format en una entrada files[], algo imprescindible en los tres formatos que siempre lo requieren (yaml-openapi, yaml-root-key, android).

npx degit lingodotdev/lingo.dev/demo/new-cli my-lingo-demo
cd my-lingo-demo

JSON y JSONC#

Traducción sencilla de clave/valor. Se traduce cada valor de texto, salvo que un control de clave indique lo contrario.

{ "pattern": "content/en/app.json", "lockedKeys": ["meta.version"] }

JSONC, además, conserva los comentarios, que el motor interpreta como contexto. Consulta notas para traductores.

{ "pattern": "content/en/settings.jsonc", "preservedKeys": ["featureFlags"] }

Markdown, MDX y Markdoc#

La prosa del cuerpo se traduce por defecto. El frontmatter y los componentes incrustados no se traducen a menos que lo actives expresamente.

Frontmatter#

Indica con translateFrontmatterFields qué campos del frontmatter quieres traducir:

{
  "pattern": "content/en/guide.md",
  "translateFrontmatterFields": ["title", "description"]
}

Props de componentes MDX#

En MDX, puedes traducir props concretas de componentes concretos con translateComponentProps:

{
  "pattern": "content/en/landing.mdx",
  "translateFrontmatterFields": ["title"],
  "translateComponentProps": [{ "component": ["Hero", "Callout"], "props": ["title", "body"] }]
}

Esto traduce las props title y body de <Hero> y <Callout>, y deja intactas todas las demás.

Markdoc#

Markdoc funciona como Markdown, conservando el frontmatter y los atributos de las etiquetas:

{
  "pattern": "content/en/changelog.mdoc",
  "translateFrontmatterFields": ["title"]
}

YAML#

El YAML genérico se detecta automáticamente a partir de .yaml/.yml: se traduce cada valor de texto y se conservan las claves y la estructura:

{ "pattern": "content/en/strings.yaml" }

Las especificaciones OpenAPI son un caso especial: comparten la extensión .yaml, pero necesitan un format explícito para que el motor traduzca solo los campos visibles para las personas (resúmenes, descripciones) y deje intactas las claves del esquema, las rutas y los ID de operación:

{ "pattern": "content/en/api.yaml", "format": "yaml-openapi" }

Los archivos de idioma con formato Rails son el otro caso especial: el idioma es la clave raíz de YAML (en:) y el archivo de destino debe tener como raíz el idioma de destino (es:). En estos casos, configura también format explícitamente:

{ "pattern": "config/locales/en.yml", "format": "yaml-root-key" }

Formatos de apps y frameworks#

PO, Flutter ARB, Xcode .strings, Xcode .stringsdict, módulos de idioma de TypeScript, XLIFF, SubRip y PHP siguen la misma regla: se traduce el texto traducible y se conserva todo lo estructural (claves, ID, metadatos, marcadores de posición, códigos de tiempo, código, formato). Cada uno se detecta automáticamente por su extensión; solo tienes que apuntar un patrón al archivo fuente:

{ "pattern": "lib/l10n/app_en.arb" }
{ "pattern": "locales/en.po" }
{ "pattern": "Localizable.strings" }
{ "pattern": "l10n/en.xlf" }

Hay uno que necesita un format explícito porque su extensión es demasiado ambigua para detectarla automáticamente:

{ "pattern": "res/values/strings.xml", "format": "android" }

Catálogos de cadenas de Xcode#

Un archivo .xcstrings (String Catalog) contiene todos los idiomas en un solo archivo. No hay una ruta de salida por idioma: el CLI lee el idioma de origen y vuelve a escribir cada destino en ese mismo archivo:

{ "pattern": "Localizable.xcstrings" }

Las cadenas marcadas con "shouldTranslate": false en el catálogo se omiten: la CLI las deja sin traducir y sin tocar.

Rutas de salida#

El patrón da nombre a tu archivo de origen; a partir de él se derivan todas las rutas de destino. Se aplican cuatro reglas, en este orden:

1. Un segmento completo de la ruta o un nombre de archivo que sea el idioma — el caso más habitual. content/en/app.json → content/de/app.json, locales/en.json → locales/de.json.
2. Un idioma al final de un segmento o de un nombre de archivo, en las estructuras que lo expresan así: Android, Xcode .strings/.stringsdict, Flutter y yaml-root-key. res/values-en/ → res/values-de/, app_en.arb → app_de.arb, devise.en.yml → devise.de.yml.
3. El nombre reservado de una plataforma para el idioma predeterminado, sin que aparezca ningún idioma en la ruta. El res/values/ a secas de Android pasa a ser res/values-de/, y el Base.lproj de Xcode pasa a ser de.lproj.
4. El String Catalog, donde la ruta de destino es la ruta de origen, porque un único archivo contiene todos los idiomas.

Android es la única plataforma cuyas rutas de destino no siguen BCP 47: la CLI escribe el calificador de recursos que Android realmente utiliza, así que pt-BR va a parar a values-pt-rBR/ y zh-Hans a values-b+zh+Hans/.

Si ninguna de las reglas encaja —el idioma de origen no aparece en ninguna parte de la ruta—, la CLI recurre a crear un directorio <locale>/ junto al archivo, y lingo push te avisa de que ha hecho esa suposición. Tómalo como una señal de que el patrón no es correcto. Consulta Configuration.

¿Vienes del CLI heredado?#

La mayoría de los formatos del CLI heredado ya están disponibles en el CLI actual (PO, XLIFF, cadenas de Android/Xcode, Flutter ARB y más; consulta la tabla de arriba). Algunos formatos menos habituales (por ejemplo, CSV, HTML, MJML, .properties) aún no están disponibles; hasta que llegue el tuyo, la documentación del CLI heredado te lo cubre.