Formatos compatibles

La CLI de Lingo.dev utiliza tipos de bucket para analizar y traducir distintos formatos de archivo. Cada tipo de bucket es un parser específico diseñado para un formato concreto. Configura uno o varios buckets en tu i18n.json para definir qué archivos debe traducir la CLI.

Tipos de bucket#

Tipo de bucket	Formato	Modo de salida	¿Requiere `[locale]`?
`json`	Archivos JSON	Archivos independientes por idioma	Sí
`json5`	Archivos JSON5	Archivos independientes por idioma	Sí
`jsonc`	Archivos JSONC (con comentarios)	Archivos independientes por idioma	Sí
`json-dictionary`	Diccionario JSON (clave-valor plano)	Archivos independientes por idioma	Sí
`yaml`	Archivos YAML	Archivos independientes por idioma	Sí
`yaml-root-key`	YAML con claves raíz de idioma	Modifica el archivo de origen	No
`markdown`	Archivos Markdown	Archivos independientes por idioma	Sí
`mdx`	Archivos MDX	Archivos independientes por idioma	Sí
`markdoc`	Archivos Markdoc	Archivos independientes por idioma	Sí
`html`	Archivos HTML	Archivos independientes por idioma	Sí
`mjml`	Plantillas de email en MJML	Archivos independientes por idioma	Sí
`android`	Recursos XML de Android	Archivos independientes por idioma	Sí
`xcode-strings`	Archivos `.strings` de Xcode	Archivos independientes por idioma	Sí
`xcode-stringsdict`	Archivos `.stringsdict` de Xcode	Archivos independientes por idioma	Sí
`xcode-xcstrings`	Catálogos `.xcstrings` de Xcode	Modifica el archivo de origen	No
`flutter`	Archivos ARB de Flutter	Archivos independientes por idioma	Sí
`po`	Archivos PO de GNU gettext	Archivos independientes por idioma	Sí
`properties`	Archivos `.properties` de Java	Archivos independientes por idioma	Sí
`csv`	Archivos CSV	Modifica el archivo de origen	No
`csv-per-locale`	Archivos CSV (uno por idioma)	Archivos independientes por idioma	Sí
`xml`	Archivos XML genéricos	Archivos independientes por idioma	Sí
`xliff`	Archivos XLIFF	Archivos independientes por idioma	Sí
`srt`	Archivos de subtítulos SRT	Archivos independientes por idioma	Sí
`vtt`	Archivos de subtítulos VTT	Archivos independientes por idioma	Sí
`php`	Arrays de localización en PHP	Archivos independientes por idioma	Sí
`typescript`	Archivos TypeScript	Archivos independientes por idioma	Sí
`vue-json`	Bloques JSON de Vue i18n	Archivos independientes por idioma	Sí
`txt`	Archivos de texto plano	Archivos independientes por idioma	Sí

Modos de salida#

Los buckets funcionan en uno de estos dos modos de salida:

Archivos independientes por idioma: la CLI crea un archivo distinto para cada idioma de destino. Los patrones include deben contener el marcador [locale]:

json

{
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}

Esto genera locales/en.json, locales/es.json, locales/fr.json, etc.

Modifica el archivo de origen: la CLI escribe las traducciones en el mismo archivo que contiene el contenido original. En este caso, no se utiliza el marcador [locale]:

json

{
  "buckets": {
    "csv": {
      "include": ["translations.csv"]
    }
  }
}

Los archivos CSV suelen almacenar todos los idiomas en columnas dentro de un único archivo. Los catálogos .xcstrings de Xcode y los archivos YAML con claves raíz funcionan de forma parecida.

Ejemplos de configuración#

Aplicación web con JSON#

json

{
  "buckets": {
    "json": {
      "include": ["src/locales/[locale].json"],
      "lockedKeys": ["brand/name"]
    }
  }
}

Sitio de documentación con Markdown#

json

{
  "buckets": {
    "markdown": {
      "include": ["docs/[locale]/*.md"],
      "exclude": ["docs/[locale]/drafts/*.md"]
    }
  }
}

Aplicación móvil (iOS + Android)#

json

{
  "buckets": {
    "xcode-xcstrings": {
      "include": ["ios/Localizable.xcstrings"]
    },
    "android": {
      "include": ["android/app/src/main/res/values-[locale]/strings.xml"]
    }
  }
}

Monorepo con varios formatos#

json

{
  "buckets": {
    "json": {
      "include": ["apps/web/locales/[locale].json"]
    },
    "mdx": {
      "include": ["packages/docs/content/[locale]/*.mdx"]
    },
    "flutter": {
      "include": ["apps/mobile/lib/l10n/app_[locale].arb"]
    }
  }
}

Funciones específicas de cada bucket#

Algunos buckets admiten funciones adicionales más allá de los patrones include/exclude:

Función	Buckets compatibles	Descripción
Key Locking	Formatos de clave-valor (JSON, YAML, etc.)	Copia los valores de origen sin traducirlos
Key Ignoring	Formatos de clave-valor	Excluye por completo las claves de los archivos de destino
Key Preserving	Formatos de clave-valor	Las inicializa una vez y luego las protege de futuras actualizaciones
Translator Notes	JSONC, XCStrings	Aporta contexto mediante comentarios para mejorar la traducción

Reglas de los patrones `include`#

Los patrones son relativos a la ubicación del archivo i18n.json
Usa [locale] como marcador para los códigos de idioma (obligatorio en los buckets de "archivos independientes")
El asterisco (*) coincide con cualquier nombre de archivo: locales/[locale]/*.json
Los patrones recursivos (**) coinciden con archivos a cualquier nivel de profundidad: src/**/[locale].json, config/locales/**/[locale].yml. Cuando un patrón usa **, node_modules, .git, dist, build, .next y .turbo se excluyen por defecto; añade tus propias entradas exclude además según lo necesites (requiere CLI 0.135.0+)
Las extensiones de archivo no afectan al análisis: el tipo de bucket determina qué parser se utiliza

Siguientes pasos#

i18n.json

Referencia completa de configuración

Key Locking

Protege claves concretas de la traducción

Existing Translations

Añade la CLI a un proyecto que ya tiene traducciones

Setup

Instala y configura la CLI