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 del bucket, como el bloqueo de claves

Configurar buckets es un paso esencial para establecer un pipeline de traducción con Lingo.dev CLI.

Tipos de bucket

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 bucket 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" 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 mutan el archivo donde existe el contenido fuente mientras que otros buckets crean archivos separados para cada locale 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 bucket.

Por ejemplo, al usar el bucket CSV, los archivos .csv se mutan directamente. Esto se debe a que es típico que los archivos CSV almacenen contenido localizado para cada locale en el mismo archivo, en columnas separadas:

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

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

Esto es importante de entender por un par de razones:

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

Crear 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 soportados, 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.

Incluir 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 (ej., "some/dir/labels.json")
patrón glob (ej., "some/dir/*.json")

Estos valores son siempre relativos al archivo i18n.json.

Placeholder `[locale]`

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

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

Este placeholder se reemplaza en tiempo de ejecución y afecta dónde el CLI:

busca el contenido fuente
genera el contenido localizado

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

La posición del placeholder [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 include, las extensiones de archivo no importan. Lingo.dev CLI intentará analizar los archivos especificados según el tipo de bucket, independientemente de la extensión.

Exclusión de 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 buckets

Algunos buckets tienen ciertas características que otros no tienen. Esto se debe normalmente a que las características solo tienen sentido lógico en el contexto de esos buckets.

Las características específicas de buckets incluyen:

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