存储桶

简介

在 i18n.json 文件中，buckets 属性定义了：

用于从文件中提取可本地化内容的解析器
文件系统中可本地化内容的位置
某些存储桶特定功能，例如 key locking

配置存储桶是使用 Lingo.dev CLI 搭建翻译流水线的关键步骤。

存储桶类型

Lingo.dev CLI 兼容多种行业标准文件格式（以及部分非标准格式）。每种格式都对应特定类型的存储桶。

存储桶类型通常与文件格式同义，但并非总是一一对应。例如，"json" 和 "json-dictionary" 存储桶都处理 JSON 文件中的可本地化内容，但 CLI 期望文件结构不同，因此存储桶也不同。

输出模式

在本地化内容时，部分存储桶会直接修改源内容所在的文件，而其他存储桶则会为每个目标语言创建单独的文件。

出现这种行为差异的原因在于，不同存储桶采用哪种方式更为合理。没有一种通用的正确方式适用于所有存储桶类型。

例如，使用 CSV 存储桶时，.csv 文件会被直接修改。这是因为 CSV 文件通常会在同一个文件中、不同的列中存储每个语言的本地化内容：

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

而使用 Markdown 存储桶时，本地化内容会输出到单独的文件，因为通常不会将所有语言版本存储在同一个文件中。

理解这一点很重要，原因有以下几点：

不同的 bucket 行为方式不同，这一点并不直观。
你需要根据文件输出方式，分别定义 include 和 exclude 模式。

创建 bucket

要创建 bucket，请在 buckets 对象中添加一个条目，位于 i18n.json 文件中：

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

每个 key 必须对应一个受支持的 bucket 类型，而 value 必须是包含该 bucket 有效配置的对象。

buckets 属性必须至少有一个有效条目。

包含文件

bucket 至少需要有一个 include 属性，用于定义需要本地化的内容：

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

该属性必须是字符串数组。

每个字符串可以是以下之一：

文件路径（例如，"some/dir/labels.json"）
glob 模式（例如，"some/dir/*.json"）

这些值始终是相对于 i18n.json 文件的。

`[locale]` 占位符

当 bucket 将本地化内容输出到单独文件（即不修改现有文件）时，include 模式中必须包含一个特殊的 [locale] 占位符：

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

此占位符会在运行时被替换，并影响 CLI 的以下行为：

查找源内容的位置
输出本地化内容的位置

例如，如果源语言环境为 "en"，目标语言环境为 "es"，那么 [locale]/*.mdx 会在 en/ 目录下查找所有 MDX 文件，并将本地化文件输出到 es/ 目录。

[locale] 占位符的位置无关紧要，以下所有模式都是有效的：

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

递归 glob 模式

Lingo.dev CLI 不支持递归 glob 模式。这意味着像 "**/*.json" 这样的模式无法使用。如果你尝试配置递归 glob 模式，将会抛出错误。

文件扩展名

在 include 模式中，文件扩展名无关紧要。Lingo.dev CLI 会根据 bucket 类型尝试解析指定的所有文件，无论扩展名如何。

排除文件

除了 include 模式外，buckets 还支持 exclude 模式，用于从本地化中排除文件路径或 glob 模式：

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

这些模式遵循与 include 模式相同的规则。

Bucket 专属功能

某些 bucket 具有其他 bucket 不具备的特定功能。这通常是因为这些功能只在相关 bucket 的上下文中才有意义。

这些 bucket 专属功能包括：

如需了解更多这些功能，请参阅相关文档链接。

简介