Formatos compatibles

El CLI de Lingo.dev usa tipos de bucket para analizar y traducir distintos formatos de archivo. Cada tipo de bucket cuenta con un parser específico para un formato en particular. Configura uno o varios buckets en tu i18n.json para definir qué archivos debe traducir el CLI.

Tipos de bucket#

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

Modos de salida#

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

Archivos separados por idioma - el CLI crea un archivo distinto para cada idioma de destino. Los patrones de inclusión deben incluir el placeholder [locale]:

json

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

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

Modifica el archivo fuente - el CLI escribe las traducciones en el mismo archivo que contiene el contenido fuente. El placeholder [locale] no se usa:

json

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

Los archivos CSV normalmente almacenan todos los idiomas en columnas dentro de un solo archivo. Los catálogos de Xcode .xcstrings y los YAML con claves raíz funcionan de forma similar.

Ejemplos de configuración#

App 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"]
    }
  }
}

App 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 múltiples 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 por bucket#

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

Función	Buckets compatibles	Descripción
Key Locking	Formatos de clave-valor (JSON, YAML, etc.)	Copia los valores fuente 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 actualizaciones
Translator Notes	JSONC, XCStrings	Añade contexto mediante comentarios para mejorar la traducción

Reglas de los patrones de inclusión#

Los patrones son relativos a la ubicación del archivo i18n.json
Usa [locale] como placeholder para los códigos de idioma (obligatorio en los buckets de "archivos separados")
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 de forma predeterminada; agrega tus propias entradas exclude encima según lo necesites (requiere CLI 0.135.0+)
Las extensiones de archivo no afectan el análisis: el tipo de bucket determina el parser

Siguientes pasos#

i18n.json

Referencia completa de configuración

Key Locking

Protege claves específicas de la traducción

Existing Translations

Agrega el CLI a un proyecto que ya tiene traducciones

Setup

Instala y configura el CLI