El CLI de Lingo.dev traduce archivos estáticos de tu repositorio —Markdown, MDX, Markdoc, JSON, YAML, subtítulos y más— con un motor de localización configurado. Solo apúntalo a tu contenido, ejecútalo una vez y obtén los archivos traducidos junto a los originales.
Tipos de contenido compatibles#
La CLI detecta el formato de cada archivo por su extensión; no hay ningún tipo de bucket que configurar. El idioma va en la ruta (content/en/x.md pasa a ser content/de/x.md), así que no hace falta el placeholder [locale].
| Tipo de contenido | Formato | Ruta de ejemplo |
|---|---|---|
| Documentación | Markdown | docs/en/getting-started.md |
| Documentación | MDX | docs/en/getting-started.mdx |
| Documentación | Markdoc | docs/en/getting-started.mdoc |
| Datos estructurados | JSON | data/en.json |
| Datos estructurados | YAML | data/en.yaml |
| Artículos de blog | Markdown / MDX | blog/en/post-slug.md |
| Localización | Gettext PO | locale/en/messages.po |
| Localización | XLIFF | locale/en.xliff |
| Subtítulos | SRT | subs/en/intro.srt |
Consulta la Referencia de formatos para ver la lista completa de tipos de archivo compatibles.
Aún no es compatible con la nueva CLI
Los archivos CSV (csv-per-locale), los subtítulos VTT, los archivos de texto sin formato .txt y Java .properties aún no son compatibles con el nuevo CLI. Por ahora, mantén esos archivos en el legacy CLI y sigue el changelog para enterarte de las novedades.
Requisitos previos#
En cada ejecución, el contenido pasa por un motor de localización: la configuración que define qué modelo de LLM, glosario, voz de marca y reglas se aplican. Crea uno en el panel de Lingo.dev y luego configura el CLI (Node 22+):
npm install -g @lingo.dev/cli
lingo login
lingo init
lingo linklingo init y lingo link crean .lingo/config.json y conectan la CLI con tu organización y tu motor. Haz commit de este archivo para que todos los entornos compartan la misma configuración.
{
"orgId": "org_abc123",
"engineId": "eng_abc123",
"sourceLocale": "en",
"targetLocales": ["es", "fr", "de", "ja"],
"files": [{ "pattern": "docs/en/getting-started.md" }]
}En CI, omite lingo login y proporciona LINGO_API_KEY como variable de entorno. Puedes generar una desde API keys.
Sitios de documentación#
La mayoría de los frameworks de documentación organizan el contenido traducido en directorios por idioma. Agrega un patrón por archivo fuente (o un glob) a files. La CLI conserva el frontmatter, los bloques de código y la sintaxis de componentes mientras traduce Markdown, MDX y Markdoc.
{
"orgId": "org_abc123",
"engineId": "eng_abc123",
"sourceLocale": "en",
"targetLocales": ["es", "fr", "de", "ja"],
"files": [
{ "pattern": "docs/en/getting-started.md" },
{ "pattern": "docs/en/setup.mdx" }
]
}Ejecuta la primera traducción para completar todos los idiomas de destino:
lingo push --backfill-missingEn las siguientes ejecuciones, lingo push traduce solo lo que cambió. Usa lingo pull para traer traducciones generadas en otro lugar.
Ajusta la ruta de origen para que coincida con la convención de directorios de tu framework:
| Framework | Convención de directorios por idioma | Referencia |
|---|---|---|
| Docusaurus | i18n/[locale]/docusaurus-plugin-content-docs/current/ | Guía de i18n de Docusaurus |
| Nextra | Páginas por idioma o diccionarios JSON | Documentación de Nextra |
| Hugo | content/[locale]/ | Guía multilingüe de Hugo |
| Astro | src/content/[locale]/ o diccionarios JSON | Guía de i18n de Astro |
| VitePress | Prefijo de directorio [locale]/ | i18n de VitePress |
| MkDocs | docs/ por idioma con plugin de i18n | Plugin de i18n de MkDocs |
Componentes MDX
La traducción de MDX conserva la sintaxis de componentes JSX. Los componentes personalizados como <Callout>, <Tabs> y <CodeBlock> pasan sin cambios; solo se traduce el contenido de texto dentro de ellos.
Datos estructurados#
Los archivos JSON y YAML se traducen automáticamente según su extensión. Usa controles de claves para evitar que se modifiquen valores no traducibles (ID, URL y flags de configuración).
{
"orgId": "org_abc123",
"engineId": "eng_abc123",
"sourceLocale": "en",
"targetLocales": ["es", "fr", "de", "ja"],
"files": [
{ "pattern": "content/en.json" },
{ "pattern": "data/en.yaml" }
]
}El YAML genérico no necesita un campo format. Solo yaml-openapi, yaml-root-key y android requieren un "format" explícito en la entrada del archivo.
YAML con clave raíz de idioma
Los archivos YAML que usan el código de idioma como clave raíz (algo común en Rails y Hugo) requieren un "format": "yaml-root-key" explícito: la clave raíz se reescribe al idioma de destino. Consulta la Referencia de formatos.
Subtítulos#
Los archivos de subtítulos SRT se traducen según su extensión. La CLI conserva todos los datos de tiempo, los índices de cues y las etiquetas de formato; solo se traduce el contenido de texto.
{
"orgId": "org_abc123",
"engineId": "eng_abc123",
"sourceLocale": "en",
"targetLocales": ["es", "fr", "de", "ja"],
"files": [{ "pattern": "subs/en/intro.srt" }]
}VTT aún no es compatible
Los subtítulos WebVTT (.vtt) todavía no son compatibles con la nueva CLI. Por ahora, deja los archivos VTT en la CLI heredada y sigue el changelog para enterarte de las novedades.
Cómo trabajar con grandes volúmenes de contenido#
Los repositorios de contenido estático pueden contener miles de archivos. La CLI lo maneja de forma eficiente:
| Mecanismo | Cómo ayuda |
|---|---|
| Estado de ejecución | .lingo/lock.json registra las huellas del contenido fuente, así que lingo push solo traduce archivos nuevos o modificados. Hazle commit; se regenera en cada push. |
| Paralelismo del lado del servidor | El motor paraleliza la traducción por ti; no hay ninguna opción de concurrencia que ajustar. |
| Ejecuciones dirigidas | Limita una ejecución a archivos específicos con un glob: lingo push "docs/en/**". |
Para comprobar que las traducciones estén actualizadas sin escribir archivos —útil como control en CI—, ejecuta lingo check.
