La 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. Apúntala a tu contenido, ejecútala 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 marcador [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 compatible con la nueva CLI
CSV (csv-per-locale), subtítulos VTT, archivos de texto sin formato .txt y .properties de Java todavía no son compatibles con la nueva CLI. Por ahora, mantén esos archivos en la legacy CLI y consulta el registro de cambios para conocer las novedades.
Requisitos previos#
En cada ejecución, el contenido pasa por un motor de localización: la configuración que determina qué modelo de LLM, glosario, voz de marca y reglas se aplican. Crea uno en el panel de Lingo.dev y, después, configura la CLI (Node 22+):
npm install -g @lingo.dev/cli
lingo login
lingo init
lingo linklingo init y lingo link crean .lingo/config.json, conectando 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 las API keys.
Sitios de documentación#
La mayoría de los frameworks de documentación organizan el contenido traducido en directorios por idioma. Añade 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 los 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" }
]
}Lanza la primera traducción para rellenar todos los idiomas de destino:
lingo push --backfill-missingEn ejecuciones posteriores, lingo push traduce solo lo que ha cambiado. Usa lingo pull para recuperar traducciones generadas en otro lugar.
Ajusta la ruta de origen para que encaje con la convención de directorios de tu framework:
| Framework | Convención de directorio 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 el plugin de i18n | Plugin de i18n de MkDocs |
Componentes MDX
La traducción de MDX conserva la sintaxis de los componentes JSX. Los componentes personalizados como <Callout>, <Tabs> y <CodeBlock> pasan sin cambios; solo se traduce el contenido de texto que contienen.
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 e indicadores 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 (habitual en Rails y Hugo) necesitan 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 temporización, los índices de las entradas 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 compatible
Los subtítulos WebVTT (.vtt) todavía no son compatibles con la nueva CLI. Mantén los archivos VTT en la CLI heredada y sigue el registro de cambios para enterarte de las novedades.
Trabajo con grandes volúmenes de contenido#
Los repositorios de contenido estático pueden contener miles de archivos. La CLI lo gestiona de forma eficiente:
| Mecanismo | Cómo ayuda |
|---|---|
| Estado de ejecución | .lingo/lock.json hace seguimiento de las huellas del contenido fuente, así que lingo push solo traduce los archivos nuevos o modificados. Haz commit de este archivo; se regenera en cada push. |
| Paralelización en el servidor | El motor paraleliza la traducción por ti; no hay ninguna opción de concurrencia que ajustar. |
| Ejecuciones específicas | Limita una ejecución a archivos concretos con un glob: lingo push "docs/en/**". |
Para comprobar que las traducciones están al día sin escribir archivos —útil como control en CI—, ejecuta lingo check.
