Buckets

Configuring buckets in Lingo.dev CLI

Introduction

In the i18n.json file, the buckets property defines:

  • the parsers used to extract localizable content from files
  • where localizable content exists on the file system
  • certain bucket-specific features, such as key locking

Configuring buckets is an essential step in setting up a translation pipeline with Lingo.dev CLI.

Bucket types

Lingo.dev CLI is compatible with a wide-range of industry-standard file formats (and some less standard ones). Each of these formats are associated with a specific type of bucket.

Bucket types are generally synonymous with file formats, but it's not always a one-to-one mapping. For example, the "json" and "json-dictionary" buckets both handle localizable content in JSON files, but the CLI expects the files to be structured differently, so the buckets are distinct.

Output mode

When localizing content, some buckets mutate the file where the source content exists while other buckets create separate files for each target locale.

The reason for this difference in behavior is because either option makes the most sense depending on the bucket. There is no single, correct option that could work for all bucket types.

For example, when using the CSV bucket, .csv files are mutated directly. This is because it's typical for CSV files to store localized content for each locale in the same file, in separate columns:

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

When using the Markdown bucket, on the other hand, the localized content is output to separate files because it's not typical to store all localized variations in a single file.

This is important to understand for a couple of reasons:

  • It's not immediately obvious that different buckets behave in different ways.
  • You have to define the include and exclude patterns differently based on how files are output.

Creating buckets

To create a bucket, add an entry to the buckets object in the i18n.json file:

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

Each key must correspond to one of the supported bucket types, while the value must be an object that contains valid configuration for that bucket.

The buckets property must have at least one valid entry.

Including files

At a minimum, buckets must have a include property that defines the content to be localized:

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

This property must be an array of strings.

Each string can be one of the following:

  • file path (e.g., "some/dir/labels.json")
  • glob pattern (e.g., "some/dir/*.json")

These values are always relative to the i18n.json file.

[locale] placeholder

When a bucket outputs localized content to separate files (i.e., it does not mutate an existing file), the include patterns must contain a special [locale] placeholder:

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

This placeholder is replaced at runtime and affects where the CLI:

  • looks for the source content
  • outputs the localized content

For example, if the source locale is "en" and the target locale is "es", then [locale]/*.mdx finds all MDX files in the en/ directory and outputs localized files to the es/ directory.

The position of the [locale] placeholder is not important, meaning all of these are valid patterns:

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

Recursive glob patterns

Lingo.dev CLI does not support recursive glob patterns. This means patterns like "**/*.json" do not work. If you try to configure a recursive glob pattern, an error will be thrown.

File extensions

In the include patterns, the file extensions do not matter. Lingo.dev CLI will attempt to parse whatever files are specified based on the bucket type, regardless of the extension.

Excluding files

In addition to include patterns, buckets also support exclude patterns for excluding file paths or glob patterns from localization:

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

These patterns follow the same rules as the include patterns.

Bucket-specific features

Some buckets have certain features that others don't. This is typically because the features only make logical sense in the context of those buckets.

The bucket-specific features include:

To learn more about these features, see the linked documentation.