CLI v0 格式
根据语言区域布局选择匹配的已安装旧版解析器,并验证重建后的原生文件。
根据要提取的数据和期望输出的文件选择存储桶。V0 按存储桶类型选择解析器,文件扩展名不会改变这一选择。因此,即使都包含消息文本,JSON 目录和多语言区域的 Xcode 目录也需要不同的配置。
先确定输出模式 #
大多数存储桶通过路径中的 [locale] 为每个语言区域分别写入文件。CSV、Xcode 字符串目录、JSON 字典和 Vue i18n 块则可以在同一个文件中容纳多个语言区域。输出到共享文件时,请在翻译后同时检查目标部分和源部分。
| 存储桶 | 内容 | 文档说明的输出模式 |
|---|---|---|
json, json5, jsonc | 结构化 JSON 变体 | 各语言区域的独立文件 |
json-dictionary | 包含以语言区域为键的对象的 JSON 值 | 共享文件 |
yaml | YAML 目录 | 各语言区域的独立文件 |
yaml-root-key | 嵌套在输出语言区域根键下的 YAML | 各语言区域的独立文件 |
markdown, mdx, markdoc | Markdown 系列文档 | 各语言区域的独立文件 |
html, mjml | HTML 和电子邮件标记 | 各语言区域的独立文件 |
android | Android XML 资源 | 各语言区域的独立文件 |
xcode-strings, xcode-stringsdict | Apple 字符串和复数资源 | 各语言区域的独立文件 |
xcode-xcstrings | Xcode 字符串目录 | 共享文件 |
flutter | ARB 目录 | 各语言区域的独立文件 |
po | Gettext PO | 各语言区域的独立文件 |
properties | Java 属性文件 | 各语言区域的独立文件 |
csv | 多语言区域 CSV | 共享文件 |
csv-per-locale | 每个语言区域一个 CSV 文件 | 各语言区域的独立文件 |
xml, xliff | XML 和 XLIFF | 各语言区域的独立文件 |
srt, vtt | 字幕 | 各语言区域的独立文件 |
php | PHP 本地化数组 | 各语言区域的独立文件 |
typescript | TypeScript 本地化内容 | 各语言区域的独立文件 |
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,同一个路径模式可用于指定源文件和各个独立的目标文件:
{
"buckets": {
"json": { "include": ["src/locales/[locale].json"] }
}
}共享 Xcode 目录与 Android 各语言区域的专用资源并用时:
{
"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。其他生成的内容需要显式排除:
{
"buckets": {
"markdown": {
"include": ["docs/[locale]/*.md"],
"exclude": ["docs/[locale]/drafts/*.md"]
}
}
}涉及多个软件包时,请根据所用语言和本地化引擎的归属,选择共享配置或各软件包独立配置。限定路径范围,可以避免生成的输出意外被用作源输入。
检查各格式的保护机制 #
对于键值目录,请根据各值的归属应用键控制。JSONC 和 Xcode 目录中的注释可以承载译者备注。自由格式文档和字幕不一定以相同方式使用这些功能。
请检查解析器重建的内容:目录中的键和值、文档标记和链接、字幕时间标记或原生资源标识符。只有在使用这些输出的解析器或构建流程能够正常处理它们后,才应接受输出。迁移时,请查阅当前的格式手册以及调用工具的支持列表,不要假定这份旧版对照表在迁移后仍然适用。