i18n.json es el archivo de configuración que controla el CLI de Lingo.dev y las integraciones de CI/CD. Define qué idiomas se traducen, dónde está el contenido traducible y qué backend de traducción se usa.
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 compatibilidad con las migraciones automáticas.
Idioma#
La sección locale define los idiomas de origen y 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 | Arreglo de idiomas de destino. Cada uno genera un archivo (o sección) independiente, 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 plataformas como el en-rUS de Android son compatibles.
Para ver la lista de 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 patrones de detección de archivos y 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 | Arreglo de patrones de archivos con el marcador [locale]. Admite comodines glob (*). |
exclude | Opcional. Arreglo 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 completamente excluidas de la traducción: no aparecen en los archivos de destino. Consulta Key Ignoring. |
preservedKeys | Opcional. Claves inicializadas una sola vez desde el origen y luego protegidas contra 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 se resuelve con los códigos de idioma configurados en tiempo de ejecución:
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. En su lugar, usa rutas de directorio explícitas.
Delimitadores de idioma personalizados#
De forma predeterminada, los códigos de idioma en los nombres de archivo usan un guion (-) como delimitador: en-US.json. Para 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 ruta de claves#
Los arreglos lockedKeys, ignoredKeys y preservedKeys usan la notación con barra diagonal (/) para claves anidadas y asterisco (*) para 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 de LLM directo para traducción. Esta sección es opcional: si se omite, el CLI usa 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 reemplazan 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 al motor#
Para enrutar las traducciones a través de un motor de localización específico, agrega 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 se establece LINGO_API_KEY, el CLI usa el motor predeterminado de tu organización.
Para ver la guía completa de configuración, 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 API personalizada (para entornos self-hosted 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 versiones#
El CLI migra automáticamente las configuraciones antiguas de i18n.json a la versión más reciente del esquema. Crea una copia de respaldo de tu archivo actual, actualiza el esquema y conserva toda la configuración. No se requiere intervención manual.
