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 de CI/CD de Lingo.dev.

i18n.json implementa una configuración basada en esquemas que separa los ajustes de idioma, 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 opera su flujo de trabajo de localización al leer el archivo de configuración.

Esta guía asume que tiene Lingo.dev CLI instalado y está configurando un flujo de trabajo de traducción. Al finalizar, comprenderá la estructura completa de i18n.json, las opciones de configuración y cómo cada sección controla el comportamiento de 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.10"
}

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 de forma temprana al proporcionar 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 publican nuevas versiones del esquema.

Configuración de locale

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 locale 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 locale admitidos, ejecute:

npx lingo.dev@latest show locale sources  # Available source languages
npx lingo.dev@latest show locale targets  # Available target languages

Si su código de locale no es compatible, por favor abra un pull request para agregarlo.

Elementos de configuración:

  • locale.source — Código de idioma de origen que identifica qué archivos contienen el contenido autorizado. Todas las traducciones fluyen del origen a los destinos.
  • locale.targets — Array de códigos de idioma de destino que representan sus 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 por defecto utiliza el motor de traducción de IA de Lingo.dev cuando se omite.

Para acceso directo a la API de LLM:

{
  "provider": {
    "id": "openai",
    "model": "gpt-4o-mini",
    "prompt": "Your custom translation prompt with {source} and {target} placeholders"
  }
}

Para Lingo.dev Engine:

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

Elementos de configuración:

  • provider.id — Identificador del servicio de traducción de IA (por ejemplo, "openai" o "anthropic").
  • provider.model — Nombre del modelo de traducción de IA (por ejemplo, "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 de posición {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 de ruta de archivo simple con marcador de posición [locale].
      • buckets.[bucket-type].include.[object] — Configuración de patrón avanzada con las siguientes propiedades:
        • path — El patrón de ruta de archivo con marcador de posición [locale].
        • delimiter — El delimitador a usar para los códigos de locale. Por defecto es - (guion), puede ser reemplazado por _ (guion bajo). Reemplaza el delimitador de la configuración de locale.
    • buckets.[bucket-type].exclude — Array de patrones de exclusión de archivos para omitir durante el procesamiento.
    • buckets.[bucket-type].lockedKeys — Array de claves que no deben ser traducidas. Usa la barra diagonal / como separador para claves anidadas. Usa el asterisco * para coincidir con múltiples claves.
    • buckets.[bucket-type].ignoredKeys — Array de claves que deben ser ignoradas durante la traducción. Usa la barra diagonal / como separador para claves anidadas. Usa el asterisco * para coincidir con múltiples claves.
    • buckets.[bucket-type].injectLocale — Array de claves donde el código de locale debe ser inyectado automáticamente. Usa la barra diagonal / como separador para claves anidadas. Usa el asterisco * para coincidir con múltiples claves.

Estructura básica de patrones

Los patrones de inclusión utilizan sintaxis tipo 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 locale personalizados para diferentes formatos de nombre 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 puedes usarla en una configuración de monorepo donde diferentes proyectos tienen diferentes convenciones de delimitadores.

Tipos de bucket compatibles

Lingo.dev CLI admite los siguientes tipos de bucket 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 locale
  • 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.10",
  "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.10",
  "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 de versiones inteligente que actualiza automáticamente tu configuración a versiones de esquema más recientes 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 tu archivo i18n.json actual
  2. Migra la configuración a la última versión del esquema
  3. Preserva todos los ajustes incluyendo proveedores personalizados, configuraciones de bucket y claves bloqueadas
  4. Actualiza el campo de versión para que coincida con el esquema actual

Comportamiento de la 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 tu flujo de trabajo de traducción continúa sin interrupciones.

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