CLI v0 格式

根据语言区域布局选择匹配的已安装旧版解析器,并验证重建后的原生文件。

根据要提取的数据和期望输出的文件选择存储桶。V0 按存储桶类型选择解析器,文件扩展名不会改变这一选择。因此,即使都包含消息文本,JSON 目录和多语言区域的 Xcode 目录也需要不同的配置。

先确定输出模式 #

大多数存储桶通过路径中的 [locale] 为每个语言区域分别写入文件。CSV、Xcode 字符串目录、JSON 字典和 Vue i18n 块则可以在同一个文件中容纳多个语言区域。输出到共享文件时,请在翻译后同时检查目标部分和源部分。

存储桶内容文档说明的输出模式
json, json5, jsonc结构化 JSON 变体各语言区域的独立文件
json-dictionary包含以语言区域为键的对象的 JSON 值共享文件
yamlYAML 目录各语言区域的独立文件
yaml-root-key嵌套在输出语言区域根键下的 YAML各语言区域的独立文件
markdown, mdx, markdocMarkdown 系列文档各语言区域的独立文件
html, mjmlHTML 和电子邮件标记各语言区域的独立文件
androidAndroid XML 资源各语言区域的独立文件
xcode-strings, xcode-stringsdictApple 字符串和复数资源各语言区域的独立文件
xcode-xcstringsXcode 字符串目录共享文件
flutterARB 目录各语言区域的独立文件
poGettext PO各语言区域的独立文件
propertiesJava 属性文件各语言区域的独立文件
csv多语言区域 CSV共享文件
csv-per-locale每个语言区域一个 CSV 文件各语言区域的独立文件
xml, xliffXML 和 XLIFF各语言区域的独立文件
srt, vtt字幕各语言区域的独立文件
phpPHP 本地化数组各语言区域的独立文件
typescriptTypeScript 本地化内容各语言区域的独立文件
vue-json以语言区域为键的 Vue i18n JSON 块共享文件
txt纯文本各语言区域的独立文件

这里列出的是旧版存储桶类型,并非其他工具的兼容性列表。某些条目可能是在较早的 v0 版本之后才加入的。TypeScript、PHP 和 Vue 解析器只处理各自支持的本地化结构;提供这些解析器并不意味着可以任意改写可执行源代码。

0.138.10 分发器还包含 ail、ejs、twig、dato 和 xcode-xcstrings-v2。在检查输入和输出之前,请继续使用已安装项目原有的解析器。仅凭模式定义中的枚举值不足以判断是否支持:旧版模式也列出了 compiler,但这条分发路径没有对应的加载器。

yaml-root-key 只重建所选语言区域的根节点。不要将源和目标指向同一个共享 YAML 文件:写入操作可能覆盖文件中的其他根节点。请使用各语言区域的专用路径,例如 locales/[locale].yml。这与 JSON 字典或 Vue 块不同,后两者会明确将新的语言区域合并到原始结构中。

配置一个有代表性的文件 #

对于 JSON,同一个路径模式可用于指定源文件和各个独立的目标文件:

json
{
  "buckets": {
    "json": { "include": ["src/locales/[locale].json"] }
  }
}

共享 Xcode 目录与 Android 各语言区域的专用资源并用时:

json
{
  "buckets": {
    "xcode-xcstrings": { "include": ["ios/Localizable.xcstrings"] },
    "android": {
      "include": ["android/app/src/main/res/values-[locale]/strings.xml"]
    }
  }
}

请根据应用调整 Android 语言区域的写法和资源目录。首次运行后,请用相应的构建工具验证两种原生格式,并确认应用能加载所选目标。配置被接受,并不代表该路径就能正常工作。

查找文件时避开生成的输出 #

路径相对于 i18n.json 解析;* 在同一层级内匹配。递归匹配 ** 从 0.135.0 开始提供,默认排除 node_modules、.git、dist、build、.next 和 .turbo。其他生成的内容需要显式排除:

json
{
  "buckets": {
    "markdown": {
      "include": ["docs/[locale]/*.md"],
      "exclude": ["docs/[locale]/drafts/*.md"]
    }
  }
}

涉及多个软件包时,请根据所用语言和本地化引擎的归属,选择共享配置或各软件包独立配置。限定路径范围,可以避免生成的输出意外被用作源输入。

检查各格式的保护机制 #

对于键值目录,请根据各值的归属应用键控制。JSONC 和 Xcode 目录中的注释可以承载译者备注。自由格式文档和字幕不一定以相同方式使用这些功能。

请检查解析器重建的内容:目录中的键和值、文档标记和链接、字幕时间标记或原生资源标识符。只有在使用这些输出的解析器或构建流程能够正常处理它们后,才应接受输出。迁移时,请查阅当前的格式手册以及调用工具的支持列表,不要假定这份旧版对照表在迁移后仍然适用。