i18n.json es el archivo de configuración que controla la CLI de Lingo.dev y las integraciones de CI/CD. Define qué idiomas traducir, dónde está el contenido traducible y qué backend de traducción utilizar.
Ejemplo mínimo#
{
"$schema": "https://lingo.dev/schema/i18n.json",
"version": "1.15",
"locale": {
"source": "en",
"targets": ["es", "fr", "ja"]
},
"buckets": {
"json": {
"include": ["locales/[locale].json"]
}
}
}El campo $schema habilita el autocompletado y la validación en el IDE. El campo version registra la versión del esquema para garantizar la compatibilidad con las migraciones automáticas.
Idioma#
La sección locale define los idiomas de origen y de destino:
{
"locale": {
"source": "en",
"targets": ["es", "fr", "de", "ja"]
}
}| Campo | Descripción |
|---|---|
locale.source | El idioma en el que está escrito tu contenido de origen. Todas las traducciones parten de este idioma. |
locale.targets | Lista de idiomas de destino. Cada uno genera un archivo independiente (o una sección), según el formato del bucket. |
Los códigos de idioma siguen el estándar BCP 47: en, en-US, es-ES, zh-Hans y formatos específicos de plataforma como el en-rUS de Android son compatibles.
Para ver los códigos de idioma disponibles:
npx lingo.dev@latest show locale sources # Available source languages
npx lingo.dev@latest show locale targets # Available target languagesBuckets#
Los buckets definen los patrones de detección de archivos y las reglas de procesamiento. Cada clave de bucket especifica un formato de archivo y su valor configura qué archivos se incluyen o se excluyen:
{
"buckets": {
"json": {
"include": ["locales/[locale].json"],
"exclude": ["locales/[locale]/internal.json"]
},
"markdown": {
"include": ["docs/[locale]/*.md"]
}
}
}| Campo | Descripción |
|---|---|
include | Lista de patrones de archivo con el marcador [locale]. Compatible con comodines glob (*). |
exclude | Opcional. Lista de patrones que se omiten durante el procesamiento. |
lockedKeys | Opcional. Claves cuyos valores se copian desde el origen sin traducirse. Consulta Key Locking. |
ignoredKeys | Opcional. Claves excluidas por completo de la traducción: no aparecen en los archivos de destino. Consulta Key Ignoring. |
preservedKeys | Opcional. Claves que se inicializan una vez desde el origen y luego quedan protegidas frente a actualizaciones automáticas. Consulta Key Preserving. |
injectLocale | Opcional. Claves en las que el código del idioma de destino se inserta automáticamente. |
Patrones de inclusión#
Los patrones de inclusión usan el marcador [locale], que en tiempo de ejecución se resuelve con los códigos de idioma que hayas configurado:
locales/[locale].json→locales/en.json,locales/es.jsondocs/[locale]/*.md→docs/en/*.md,docs/es/*.md
Los patrones glob recursivos (**/*.json) no son compatibles. Usa rutas de directorio explícitas en su lugar.
Delimitadores de idioma personalizados#
Por defecto, los códigos de idioma en los nombres de archivo usan un guion (-) como delimitador: en-US.json. Si prefieres usar guiones bajos, pasa un objeto con un campo delimiter:
{
"include": [
"standard/[locale].json",
{ "path": "legacy/[locale].json", "delimiter": "_" }
]
}Esto genera legacy/en_US.json en lugar de legacy/en-US.json.
Notación de rutas de claves#
Las listas lockedKeys, ignoredKeys y preservedKeys usan la barra (/) para las claves anidadas y el asterisco (*) para los comodines:
{
"lockedKeys": ["brand/name", "config/*"]
}Para ver la lista completa de tipos de bucket compatibles, consulta Supported Formats.
Proveedor#
La sección provider configura un proveedor LLM directo para la traducción. Esta sección es opcional: si se omite, la CLI utiliza un motor de localización en Lingo.dev.
{
"provider": {
"id": "openai",
"model": "gpt-4o-mini",
"prompt": "Translate the provided text from {source} to {target}."
}
}| Campo | Descripción |
|---|---|
provider.id | Identificador del proveedor: openai, anthropic, google, mistral, openrouter o ollama. |
provider.model | Nombre del modelo del proveedor (por ejemplo, gpt-4o-mini, claude-3-haiku). |
provider.prompt | Prompt del sistema. {source} y {target} se sustituyen por códigos de idioma en tiempo de ejecución. |
provider.baseUrl | Opcional. Endpoint de API personalizado (obligatorio para Ollama: http://localhost:11434). |
Conexión con el motor#
Para dirigir las traducciones a través de un motor de localización concreto, añade el campo engineId:
{
"engineId": "eng_SxjMwMsfOIsvV1wh"
}Cuando se establece engineId, cada solicitud de traducción aplica automáticamente la voz de marca, el glosario, las instrucciones y la configuración del modelo de tu motor. Si se omite y LINGO_API_KEY está definido, la CLI utiliza el motor predeterminado de tu organización.
Para ver la guía de configuración completa, consulta Connect Your Engine.
Variables de entorno#
| Variable | Obligatorio | Descripción |
|---|---|---|
LINGO_API_KEY | Para Lingo.dev Engine | Tu clave de API de Lingo.dev. |
LINGO_API_URL | No | URL base de la API personalizada (para entornos autohospedados o de staging). |
OPENAI_API_KEY | Para el proveedor OpenAI | Clave de API de OpenAI. |
ANTHROPIC_API_KEY | Para el proveedor Anthropic | Clave de API de Anthropic. |
GOOGLE_API_KEY | Para el proveedor Google | Clave de API de Google. |
MISTRAL_API_KEY | Para el proveedor Mistral | Clave de API de Mistral. |
OPENROUTER_API_KEY | Para el proveedor OpenRouter | Clave de API de OpenRouter. |
Ejemplo completo#
{
"$schema": "https://lingo.dev/schema/i18n.json",
"version": "1.15",
"locale": {
"source": "en",
"targets": ["es", "fr", "de", "ja"]
},
"buckets": {
"json": {
"include": ["locales/[locale].json"],
"lockedKeys": ["brand/name", "brand/tagline"],
"ignoredKeys": ["internal/*"]
},
"markdown": {
"include": ["docs/[locale]/*.md"]
}
},
"engineId": "eng_SxjMwMsfOIsvV1wh"
}Migración de versión#
La CLI migra automáticamente las configuraciones antiguas de i18n.json a la versión más reciente del esquema. Crea una copia de seguridad de tu archivo actual, actualiza el esquema y conserva todos los ajustes. No hace falta intervenir manualmente.
