Buckets

Introducción

En el archivo i18n.json, la propiedad buckets define:

los analizadores utilizados para extraer contenido localizable de los archivos
dónde existe el contenido localizable en el sistema de archivos
ciertas características específicas de los buckets, como el bloqueo de claves

Configurar los buckets es un paso esencial en la configuración de un pipeline de traducción con Lingo.dev CLI.

Tipos de buckets

Lingo.dev CLI es compatible con una amplia gama de formatos de archivo estándar de la industria (y algunos menos estándar). Cada uno de estos formatos está asociado con un tipo específico de bucket.

Los tipos de buckets son generalmente sinónimos de formatos de archivo, pero no siempre es una correspondencia uno a uno. Por ejemplo, los buckets "json" y "json-dictionary" ambos manejan contenido localizable en archivos JSON, pero el CLI espera que los archivos estén estructurados de manera diferente, por lo que los buckets son distintos.

Modo de salida

Al localizar contenido, algunos buckets modifican el archivo donde existe el contenido fuente mientras que otros buckets crean archivos separados para cada localización de destino.

La razón de esta diferencia en el comportamiento es porque cualquiera de las opciones tiene más sentido dependiendo del bucket. No existe una única opción correcta que pueda funcionar para todos los tipos de buckets.

Por ejemplo, cuando se utiliza el bucket CSV, los archivos .csv se modifican directamente. Esto se debe a que es típico que los archivos CSV almacenen contenido localizado para cada localización en el mismo archivo, en columnas separadas:

KEY,en,es
welcome_message,Welcome to our application,Bienvenido a nuestra aplicación

Cuando se utiliza el bucket Markdown, por otro lado, el contenido localizado se envía a archivos separados porque no es típico almacenar todas las variaciones localizadas en un solo archivo.

Esto es importante entenderlo por un par de razones:

No es inmediatamente obvio que diferentes buckets se comporten de diferentes maneras.
Tienes que definir los patrones include y exclude de manera diferente según cómo se generen los archivos.

Creación de buckets

Para crear un bucket, añade una entrada al objeto buckets en el archivo i18n.json:

{
  "buckets": {
    "json": {}
  }
}

Cada clave debe corresponder a uno de los tipos de bucket compatibles, mientras que el valor debe ser un objeto que contenga una configuración válida para ese bucket.

La propiedad buckets debe tener al menos una entrada válida.

Inclusión de archivos

Como mínimo, los buckets deben tener una propiedad include que defina el contenido a localizar:

{
  "buckets": {
    "json": {
      "include": []
    }
  }
}

Esta propiedad debe ser un array de strings.

Cada string puede ser uno de los siguientes:

ruta de archivo (p. ej., "some/dir/labels.json")
patrón glob (p. ej., "some/dir/*.json")

Estos valores son siempre relativos al archivo i18n.json.

Marcador de posición `[locale]`

Cuando un bucket genera contenido localizado en archivos separados (es decir, no modifica un archivo existente), los patrones include deben contener un marcador de posición especial [locale]:

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

Este marcador de posición se reemplaza en tiempo de ejecución y afecta dónde la CLI:

busca el contenido de origen
genera el contenido localizado

Por ejemplo, si el idioma de origen es "en" y el idioma de destino es "es", entonces [locale]/*.mdx encuentra todos los archivos MDX en el directorio en/ y genera archivos localizados en el directorio es/.

La posición del marcador de posición [locale] no es importante, lo que significa que todos estos son patrones válidos:

content/[locale]/*.mdx
[locale]/*.mdx
*.[locale].mdx

Patrones glob recursivos

Lingo.dev CLI no admite patrones glob recursivos. Esto significa que patrones como "**/*.json" no funcionan. Si intentas configurar un patrón glob recursivo, se generará un error.

Extensiones de archivo

En los patrones de include, las extensiones de archivo no importan. Lingo.dev CLI intentará analizar cualquier archivo especificado según el tipo de bucket, independientemente de la extensión.

Excluyendo archivos

Además de los patrones include, los buckets también admiten patrones exclude para excluir rutas de archivo o patrones glob de la localización:

{
  "buckets": {
    "json": {
      "include": ["[locale]/*.mdx"],
      "exclude": ["[locale]/ignored/*.mdx"],
    }
  }
}

Estos patrones siguen las mismas reglas que los patrones include.

Características específicas de bucket

Algunos buckets tienen ciertas características que otros no tienen. Esto es típicamente porque las características solo tienen sentido lógico en el contexto de esos buckets.

Las características específicas de bucket incluyen:

Para obtener más información sobre estas características, consulta la documentación enlazada.