本地化静态内容
将译文文档和翻译资源集映射到站点或渲染器读取的文件,再验证结构、链接和最终交付结果。
站点的源文件树已经将文章与路由、元数据、导航和渲染器关联起来。将译文文件放到这套系统能够加载的位置。首个有实际价值的成果,是在预定路由上呈现一个完整的目标语言页面:链接正常可用,代码示例与源文档一致。
按读取文件的系统梳理文件清单 #
将长篇文档、结构化翻译资源集和专用资源分开处理。Markdown、MDX 和 Markdoc 需要渲染器和结构规范。JSON、YAML、TypeScript 和 PHP 翻译资源集需要加载器。PO 和 XLIFF 对接各自的消息系统。SRT 则属于带时间轴的媒体工作流。
从每组中选取一个有代表性的源文件,确定输出路径,以及读取该文件的加载器。确保生成的目标文件不会被源文件匹配模式选中。保留文档 ID、URL、代码示例、翻译资源键,以及通过属性值控制行为的组件属性。
通过 格式选择实际使用的处理器。普通 YAML 与以语言区域为根键的 YAML、OpenAPI YAML 并不相同。.xml 不会自动识别 Android 资源。扩展名相同,并不代表处理器能理解文档的结构。
遵循站点的目录约定 #
以下布局选择需要结合项目的加载器逐一确认:
| 站点 | 翻译前需要确认的事项 |
|---|---|
| Docusaurus | 哪些源文档会生成 i18n/<locale>/docusaurus-plugin-content-docs/current/ 下的文件,哪些版本化文档或主题字符串需要单独的输入。 |
| Nextra | 当前安装的配置加载的是各语言区域的页面、字典,还是另一套内容树;为每种输入单独建立映射。 |
| Hugo | content/<locale>/ 下的哪些文件对应同一内容的不同语言版本,以及语言链接如何解析。 |
| Astro | 各路由的内容来自哪些语言区域专属内容集合和界面字典。 |
| VitePress | 生成译文页面时使用哪些语言区域目录前缀和导航配置。 |
| MkDocs | 当前安装的项目使用哪个 i18n 插件,以及各语言区域的文档如何布局。 |
以源文档位于 docs/ 下的 Docusaurus 项目为例,在项目根目录安装并关联 CLI:
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es --files 'docs/**/*.md' --yes
lingo link保留 .lingo/config.json 中的组织 ID 和本地化引擎 ID。由于这些源路径不包含语言区域,请将文件条目替换为明确指定的输出模板:
{
"pattern": "docs/**/*.md",
"sourceRoot": "docs",
"targetPath": "i18n/[locale]/docusaurus-plugin-content-docs/current/[path]"
}对于 docs/setup/install.md,[path] 会变为 setup/install.md,因此西班牙语输出会写入 i18n/es/docusaurus-plugin-content-docs/current/setup/install.md。确认已安装的插件及其版本能够读取该目录。配置说明了模板验证和冲突规则。
有选择地翻译读者可见的文档字段 #
对于 Markdown,选择读者可见的前置元数据字段,例如标题和描述。标识信息和发布元数据应保持不变。对于 MDX 和 Markdoc,还需找出面向读者的组件属性,例如提示框标题。控制行为的属性和组件名称属于应用的结构规范。
使用合适的处理器,不要假定所有 Markdown 系列文件都能互换处理。保存为 .md 的 Markdoc 文档需要明确指定 markdoc 格式,才能按 Markdoc 处理。请查看 Markdown、MDX 和 Markdoc,了解内容选择和文档重建的限制。保留围栏代码块,作为可执行的验证依据;翻译代码块周围的说明,不要改动命令。
运行缺失文件回填:
lingo push --backfill-missing --wait完成后,构建站点并打开生成的目标路由。检查标题、描述、正文、自定义组件、代码块和一个链接。如果标题 ID 根据文本生成,请实际访问译文中的片段链接。即使 URL 保持不变,其指向的位置也必须存在。Markdoc 与 Next.js 指南提供了按语言区域加载内容的示例。
确保结构化翻译资源集符合约定 #
翻译 JSON 和通用 YAML 中的字符串值,同时通过处理器的键控制选项保护 ID、端点和其他非语言数据。在当前 CLI 的源配置中,为通用 YAML 明确设置 format: "yaml":仅靠扩展名推断,无法推送尚未配置的 YAML 源。当语言区域作为根键时,使用 yaml-root-key;当结构为 OpenAPI 文档时,使用 yaml-openapi。TypeScript 和 PHP 应使用受支持的翻译资源集形式;翻译文件并不意味着能够安全地执行任意源代码。
对于 PO,保留消息标识、上下文、复数结构,以及目标端使用的编译步骤。对于 XLIFF,保留受支持变体的源文本、目标文本和占位符结构。验证实际读取这些文件的系统能否完成导入或构建,而不只是检查输出文件是否存在。
纯文本 .txt 文件(如应用商店描述)会逐行翻译,并保留源文件的行结构。请在文件匹配模式中包含 .txt(如 metadata/en/*.txt),或设置 "format": "txt":像 docs/en/**/* 这样的宽泛匹配模式不会选中这些文件。请参阅纯文本。每个语言区域各占一列的 CSV 表格会直接在原文件中翻译:请在匹配模式中包含 .csv,或设置 "format": "csv",详见 CSV。当前 CLI 不提供以下可配置格式:每个语言区域独立一个 CSV 文件、WebVTT 或 Java .properties。CLI v0 格式参考供已安装相关版本、仍在使用这些旧版工作流的用户参考;其中的命令和配置仅适用于特定版本。请通过迁移参考选择受支持的迁移方案,避免在未获提示的情况下丢失这些资源。
结合媒体检查字幕 #
对于 SRT,翻译字幕文本,并对照源文件检查字幕序号和时间。使用目标语言字幕播放有代表性的场景。在实际播放器中检查字幕的阅读长度、换行、说话者上下文和格式标签。保留时间戳,并不代表译文能在对应时间段内读完。请参阅 SubRip 了解文件约定;不要仅因 WebVTT 也是字幕格式,就用它替代 SRT。
沿已验证的交付路径逐步扩展 #
将配置、源文件、已接受的目标文件和 CLI Lockfile 保存在一起。修改段落后,使用 lingo push --wait 处理常规增量,再对比目标文件中的该段落和一个未修改的部分。保留旧版源文件及其对应的目标文件;重组文档结构可能使复用关系变得不明确。按位置匹配的模式采用不同的范围规划语义。大规模重新翻译前,使用估算工作流,将估算结果作为规划参考,而非报价。
如果需要保护本地目标文件中的修正,避免差异被覆盖,请在提交时不使用 --wait,并在获取结果前检查 lingo pull --dry-run;直接等待并回写的方式没有这道检查关卡。请遵循保留已审核的翻译。
确认一组内容能够正确构建后,再选择 GitHub App 或 CI 配置示例。在这一流程中保留站点构建、结构规范验证、链接检查和内容审核;lingo check 并不能证明文档完整。每次更新后,都应保留一个可读的目标页面,以及团队可用于下一次修改的源文件修订版本。