格式
选择合适的文件处理器,翻译文本,同时保留应用所需的文件结构。
语言区域文件承载的不只是文字:键将消息与代码关联起来,占位符接收应用传入的值,文件结构则告诉框架如何加载结果。文档还包含标题、链接、示例和元数据。文件翻译既要转换语言,也要保留这些关联。
Lingo.dev 使用格式处理器提取可翻译文本,并重建翻译后的文件。选择处理器时,请以文件的实际用途为准。Rails 消息目录和 OpenAPI 规范的文件名都可能以 .yml 结尾,但如果不加区分地翻译所有字符串,两者会出现不同的问题:Rails 的语言区域根节点必须更改,而 API 的操作标识符必须保持不变。
查找所需格式 #
| 源文件 | 处理器类型 | 参考 |
|---|---|---|
| 嵌套 JSON 消息目录 | json | JSON |
| 带上下文注释的 JSON | jsonc | JSONC |
| YAML 消息目录 | yaml | YAML |
| 包含单个语言区域根节点的 YAML | yaml-root-key | 语言区域根节点 YAML |
| 静态 TypeScript 语言区域模块 | typescript | TypeScript |
| 静态 PHP 语言区域数组 | php | PHP |
| Markdown 文档 | md | Markdown |
| 带 JSX 组件的 Markdown | mdx | MDX |
| Markdoc 文档 | markdoc | Markdoc |
| OpenAPI 3.x YAML | yaml-openapi | OpenAPI |
| Android 资源 XML | android | Android |
| Flutter 应用资源包 | flutter | Flutter ARB |
| Apple 字符串表 | xcode-strings | Apple strings |
| Apple 复数资源 plist | xcode-stringsdict | Apple stringsdict |
| Apple 多语言区域目录 | xcode-xcstrings | Apple 字符串目录 |
| Gettext PO 消息目录 | po | Gettext |
| XLIFF 交换文档 | xliff | XLIFF |
| SubRip 字幕 | srt | SubRip |
| 逐行翻译的纯文本 | txt | 纯文本 |
| HTML 文档或片段 | html | HTML |
| 每个语言区域各占一列的 CSV 表格 | csv | CSV |
| Java 属性资源包 | properties | Java 属性 |
| 选定的 Payload CMS 字段 | payload | Payload |
这些参考文档介绍了现有的文件处理器及其在内容提取和重建方面的限制。除 Payload 外,CLI 和 GitHub App 支持上方列出的 22 种已配置类型。HTML 通过 .html 和 .htm 推断识别;输出会保留未经改动的源内容,并将显式声明的 <html> 元素的 lang 设置为目标语言区域。请在仓库配置中明确选择所需的 YAML 变体或 Android 格式。与 Apple 字符串目录一样,CSV 会将所有语言区域保留在源文件中。CLI 快速入门以单个文件为例,带你完成从设置到获取文件的流程;GitHub 文档则介绍托管仓库工作流。
现有的提供方连接按各自的集成契约选取和写入内容。
如需直接翻译结构化数据,请提交内联 JSON。如需上传源文件并保留原有格式,请参阅文件文档。两种方式使用相同的翻译任务生命周期。
将源文件修订版本与对应译文一同保存 #
增量文件翻译会比较当前源文件与上一版源文件,并使用与上一版对应的现有目标文件。借助这些输入,未更改的消息可以保留已认可的译文,新增或更改的消息则会得到翻译。
键让这种比较更有意义:即使 checkout.title 和 account.title 包含完全相同的英文文本,也能各自保留不同的译文。数组位置、字幕条目编号、纯文本行位置和文档结构也会用于匹配。移动条目或调整已翻译文档的结构,都可能改变对应关系。因此,请将目标文件与生成该文件时所用的源文件修订版本配对保存。
大多数格式会为每个目标语言区域生成单独的文件,Apple 字符串目录则会将各语言区域合并到源文件中。Payload 产物或字符串目录也可能只包含部分目标值,其他值仍然缺失。请审核实际的目标条目,而不只是确认文件是否存在。
分别控制文本选择与输出 #
将文本排除在翻译范围之外,可以有不同的处理方式。锁定的目录值取自源文件,保留的值取自现有目标文件,而忽略的值可能不会出现在输出中。具体有哪些控制选项,取决于文件格式和调用接口。
对于 JSON/JSONC、YAML、语言区域根节点 YAML、PHP 和 TypeScript,请使用 CLI 键范围。部分更新会保留选定范围之外的现有译文,但仅存在于源文件中的条目和数组位置如何处理,则取决于具体格式。请对照相应的格式参考文档检查完整结果。
上下文元数据也有各自明确的处理规则。JSONC 的 @context 注释用于描述下一个字符串值,ARB 的 @message.description 用于描述对应消息,Gettext 的 msgctxt 则用于区分消息并提供上下文。普通注释可以在文件重建后保留,但不会被当作翻译指令。React 的 @src 和 @orphan 注解属于其消息目录维护工作流。
获取文件后,请用实际使用该文件的系统加载它。除了核对译文含义,还要检查所选语言区域、变量、复数形式、链接和受保护的数据。应用指南会带你完成 Web 应用、原生资源和静态内容的这些检查。