Configuración de i18n.json

i18n.json es un archivo de configuración estándar que controla el comportamiento de Lingo.dev CLI y las integraciones CI/CD de Lingo.dev.

i18n.json implementa una configuración basada en esquemas que separa la configuración de idiomas, los patrones de descubrimiento de archivos y la configuración del motor de traducción de IA en secciones distintas. Como resultado, los desarrolladores comprenden exactamente cómo funciona su flujo de trabajo de localización al leer el archivo de configuración.

Esta guía asume que tienes instalado Lingo.dev CLI y estás configurando un flujo de trabajo de traducción. Al finalizar, comprenderás la estructura completa de i18n.json, las opciones de configuración y cómo cada sección controla el comportamiento de la traducción.

Versión

El campo version especifica la versión del esquema de configuración:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": 1.8
}

Elementos de configuración:

  • $schema — Apunta a la definición del esquema JSON para autocompletado y validación en el IDE. El esquema ayuda a detectar errores de configuración tempranamente proporcionando documentación en línea y verificación de tipos.
  • version — Versión del esquema de configuración para compatibilidad de migración.

Lingo.dev CLI utiliza este campo para la migración automática de configuración cuando se lanzan nuevas versiones del esquema.

Configuración de localización

La sección locale define qué idiomas procesa Lingo.dev CLI:

{
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "ja", "de"]
  }
}

Los códigos de idioma siguen el estándar BCP 47 para etiquetas de idioma, que incorpora códigos de idioma de ISO 639 y códigos de región opcionales de ISO 3166-1. Los ejemplos incluyen en, en-US, es-ES y zh-Hans.

Lingo.dev CLI también admite formatos de localización específicos de plataforma como la convención en-rUS de Android para directorios de recursos. Para obtener la lista completa de códigos de localización admitidos, ejecuta:

npx lingo.dev@latest show locale sources  # Idiomas de origen disponibles
npx lingo.dev@latest show locale targets  # Idiomas de destino disponibles

Si tu código de localización no está admitido, ¡por favor abre una pull request para añadirlo!

Elementos de configuración:

  • locale.source — Código del idioma de origen que identifica qué archivos contienen el contenido autoritativo. Todas las traducciones fluyen desde el origen hacia los destinos.
  • locale.targets — Array de códigos de idiomas de destino que representan tus mercados objetivo. Cada código corresponde a un archivo separado o sección dentro de un archivo, dependiendo del formato.

Comandos de verificación de idioma:

Configuración del proveedor

La sección provider determina qué servicio de traducción de IA utiliza Lingo.dev CLI. Esta sección es opcional y, cuando se omite, utiliza por defecto el motor de traducción de IA de Lingo.dev.

Para acceso directo a la API de LLM:

{
  "provider": {
    "id": "openai",
    "model": "gpt-4o-mini",
    "prompt": "Tu prompt de traducción personalizado con marcadores {source} y {target}"
  }
}

Para el motor de Lingo.dev:

Para utilizar el motor de Lingo.dev, omite completamente la sección provider. El motor selecciona automáticamente los modelos y prompts basándose en investigaciones de optimización y en tu configuración del motor de Lingo.dev.

Elementos de configuración:

  • provider.id — Identificador del servicio de traducción de IA (p. ej. "openai" o "anthropic").
  • provider.model — Nombre del modelo de traducción de IA (p. ej. "gpt-4o-mini" para OpenAI o "claude-3-haiku" para Anthropic).
  • provider.prompt — Prompt del sistema que guía el comportamiento de traducción. Los marcadores {source} y {target} se reemplazan con los códigos de idioma reales en tiempo de ejecución.

Configuración de buckets

Los buckets definen patrones de descubrimiento de archivos y reglas de procesamiento. Cada bucket representa un formato de archivo con patrones específicos de inclusión/exclusión.

{
  "buckets": {
    "json": {
      "include": ["locales/[locale].json", "app/[locale]/*.json"],
      "exclude": ["locales/[locale]/internal.json"],
      "lockedKeys": ["app/version", "config/apiUrl"],
      "injectLocale": ["settings.language"]
    },
    "markdown": {
      "include": ["docs/[locale]/*.md"],
      "exclude": ["docs/[locale]/drafts/*.md"]
    }
  }
}

Elementos de configuración:

  • buckets.[bucket-type] — Grupo de configuración para un bucket de formato de archivo específico.
    • buckets.[bucket-type].include — Array de patrones de descubrimiento de archivos. Puede contener strings u objetos.
      • buckets.[bucket-type].include.[string] — Patrón simple de ruta de archivo con marcador [locale].
      • buckets.[bucket-type].include.[object] — Configuración avanzada de patrones con las siguientes propiedades:
        • path — El patrón de ruta de archivo con marcador [locale].
        • delimiter — El delimitador a utilizar para los códigos de locale. Por defecto es - (guion), puede cambiarse a _ (guion bajo). Anula el delimitador de la configuración de locale.
    • buckets.[bucket-type].exclude — Array de patrones de exclusión de archivos que se omitirán durante el procesamiento.
    • buckets.[bucket-type].lockedKeys — Array de claves que no deben traducirse. Utiliza la barra diagonal / como separador para claves anidadas.
    • buckets.[bucket-type].ignoredKeys — Array de claves que deben ignorarse durante la traducción. Utiliza la barra diagonal / como separador para claves anidadas.
    • buckets.[bucket-type].injectLocale — Array de claves donde el código de locale debe inyectarse automáticamente.

Estructura básica de patrones

Los patrones de inclusión utilizan una sintaxis similar a glob con el marcador especial [locale]:

  • locales/[locale].json → locales/en.json, locales/es.json
  • docs/[locale]/*.md → docs/en/*.md, docs/es/*.md

Los patrones de exclusión evitan el procesamiento de archivos específicos dentro de los patrones de inclusión.

Opciones avanzadas de patrones

Delimitadores de localización personalizados para diferentes formatos de nombres de archivo:

{
  "include": [
    "standard/[locale].json",
    {
      "path": "underscore/[locale].json",
      "delimiter": "_"
    }
  ]
}

Delimitadores disponibles:

  • - (guion): en-US.json
  • _ (guion bajo): en_US.json

Consejo: Esta configuración controla el delimitador utilizado en el nombre del archivo, por lo que puede usarlo en una configuración de monorepo donde diferentes proyectos tienen diferentes convenciones de delimitadores.

Tipos de buckets compatibles

Lingo.dev CLI admite los siguientes tipos de buckets para diferentes formatos de archivo:

  • android — Archivos de recursos XML de Android
  • csv — Archivos CSV con archivos separados para cada idioma de destino
  • flutter — Archivos ARB de Flutter
  • html — Archivos HTML con archivos separados para cada idioma de destino
  • json — Archivos JSON con archivos separados para cada idioma de destino
  • markdown — Archivos Markdown con archivos separados para cada idioma de destino
  • mdx — Archivos MDX con archivos separados para cada idioma de destino
  • xcode-strings — Archivos .strings heredados de Xcode
  • xcode-stringsdict — Archivos .stringsdict de Xcode para pluralización
  • xcode-xcstrings — Archivos de catálogo de strings de Xcode
  • yaml — Archivos YAML con archivos separados para cada idioma de destino
  • yaml-root-key — Archivos YAML con claves raíz basadas en la localización
  • properties — Archivos .properties de Java
  • po — Archivos .po de GNU gettext
  • xml — Archivos XML genéricos con archivos separados para cada idioma de destino
  • php — Archivos de array de PHP
  • vue-json — Archivos JSON de i18n de Vue.js
  • typescript — Archivos TypeScript con archivos separados para cada idioma de destino

Ejemplos de configuración

Configuración básica

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": 1.8,
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}

Configuración de monorepo

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": 1.8,
  "locale": {
    "source": "en-US",
    "targets": ["es-ES", "fr-FR"]
  },
  "buckets": {
    "json": {
      "include": ["apps/web/locales/[locale].json"]
    },
    "mdx": {
      "include": ["packages/docs/content/[locale]/*.mdx"]
    },
    "xcode-xcstrings": {
      "include": ["ios/Localizable.xcstrings"]
    },
    "android": {
      "include": ["android/values-[locale]/strings.xml"]
    }
  }
}

Migración de versiones

i18n.json implementa una migración inteligente de versiones que actualiza automáticamente su configuración a versiones más recientes del esquema mientras preserva todos los ajustes del usuario.

Cuando Lingo.dev CLI detecta una versión de configuración anterior:

  1. Crea una copia de seguridad de su archivo i18n.json actual
  2. Migra la configuración a la última versión del esquema
  3. Conserva todos los ajustes incluyendo proveedores personalizados, configuraciones de buckets y claves bloqueadas
  4. Actualiza el campo de versión para que coincida con el esquema actual

Comportamiento de migración:

La migración se activa automáticamente durante cualquier operación de CLI que lea el archivo de configuración. No se requiere intervención manual, y su flujo de trabajo de traducción continúa sin interrupciones.

Este sistema de migración asegura que las configuraciones de i18n.json permanezcan compatibles con las actualizaciones de Lingo.dev CLI mientras mantiene la compatibilidad con proyectos existentes.