存储桶

介绍

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

用于从文件中提取可本地化内容的解析器
文件系统中可本地化内容的位置
某些特定的 bucket 功能，例如键锁定

配置 buckets 是使用 Lingo.dev CLI 设置翻译流程的关键步骤。

Bucket 类型

Lingo.dev CLI 兼容多种行业标准文件格式（以及一些非标准格式）。每种格式都与特定类型的 bucket 相关联。

Bucket 类型通常与文件格式同义，但并不总是一一对应。例如，"json" 和 "json-dictionary" buckets 都处理 JSON 文件中的可本地化内容，但由于 CLI 期望文件的结构不同，这些 buckets 是独立的。

输出模式

在本地化内容时，某些 buckets 会修改源内容所在的文件，而其他 buckets 会为每个目标语言创建单独的文件。

这种行为差异的原因是，根据 bucket 的不同，任一选项可能是最合理的选择。没有一种单一的正确选项适用于所有 bucket 类型。

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

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

另一方面，当使用 Markdown bucket 时，本地化内容会输出到单独的文件中，因为通常不会在单个文件中存储所有语言的本地化变体。

理解这一点很重要，原因如下：

不同 buckets 的行为差异并不显而易见。
您需要根据文件的输出方式不同来定义 include 和 exclude 模式。

创建存储桶

要创建存储桶，请在 i18n.json 文件的 buckets 对象中添加一个条目：

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

每个键必须对应一个支持的存储桶类型，而值必须是包含该存储桶有效配置的对象。

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

包含文件

存储桶至少必须有一个 include 属性，用于定义需要本地化的内容：

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

此属性必须是一个字符串数组。

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

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

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

`[locale]` 占位符

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

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

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

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

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

[locale] 占位符的位置并不重要，这意味着以下模式都是有效的：

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

递归通配符模式

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

文件扩展名

在 include 模式中，文件扩展名无关紧要。Lingo.dev CLI 将根据存储桶类型尝试解析指定的文件，而不考虑扩展名。

排除文件

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

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

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

存储桶特定功能

某些存储桶具有其他存储桶没有的特定功能。这通常是因为这些功能仅在这些存储桶的上下文中才有逻辑意义。

存储桶特定功能包括：

要了解更多关于这些功能的信息，请参阅链接的文档。

介绍