CSV
翻译 CSV 表格:所有语言区域保存在同一个文件中,各占一列,并以你指定的列作为键。
CSV 翻译表把源文本和所有译文放在同一个文件里:每条消息一行,每个语言区域一列。csv 文件处理器会填充该文件中目标语言区域的单元格,并将结果写回源路径。它只写入目标语言区域的单元格;如果某个语言区域还没有对应的列,则会新增一列,详见哪些行会被翻译。其他列、行顺序、引号和换行符都保持不变。文件开头的 UTF-8 字节顺序标记(BOM)不会保留,写入后的文件不带该标记。如果你的电子表格应用依赖该标记来识别 UTF-8,可能需要手动以 UTF-8 编码导入文件。
规划表格布局 #
第一行既非空行、也不只包含空白字符的内容即为表头。其中一列存放用于标识每一行的键,一列存放源文本,每个目标语言区域各占一列:
id,en,notes,de
checkout.title,Complete your order,Shown on the last step,Bestellung abschließen
checkout.pay,"Pay now, or later",,- 语言区域列。 列标题与语言区域代码匹配(不区分大小写)时,该列即属于对应的语言区域:
de和DE都是德语列,而de-DE则是另一个语言区域。源列的标题即配置中的sourceLocale。 - 键列。 默认以第一个表头单元格所在的列作为键列。如需使用其他列,请在该文件的配置条目中设置
keyColumn。当源文本本身就是键时,键列可以直接使用源列。 - 其他列。 既不是键列、也不是语言区域列的列(例如
notes)会逐字节原样保留,绝不会被发送去翻译。 - 语法。 单元格之间以逗号分隔。如果单元格中包含逗号、引号或换行符,需要用双引号括起来,其中的引号要连写两次(
"")。不支持以分号或制表符分隔的文件。
配置 CSV 翻译 #
只有满足以下条件之一的文件配置条目才会选中 CSV 文件:匹配模式以 .csv 结尾(此时会自动推断格式),或条目中设置了 "format": "csv"。设置了 "format": "csv" 的条目只会选中 .csv 文件。未设置该格式时,像 data/**/* 这样宽泛的匹配模式绝不会选中 CSV 文件,因此现有条目不会意外改写无关的数据文件。扩展名区分大小写:名为 strings.CSV 的文件不会被翻译,请将其重命名为 strings.csv。
{
"sourceLocale": "en",
"targetLocales": ["de", "fr"],
"files": [{ "pattern": "i18n/strings.csv", "keyColumn": "id" }]
}对每个语言区域而言,该文件本身就是目标文件,因此此格式不支持 targetPath。CSV 行不会与键控制规则进行匹配,因此同样不支持 lockedKeys、preservedKeys 和 ignoredKeys。这套配置在 CLI 和 GitHub App 中通用。
哪些行会被翻译 #
| 行 | 结果 |
|---|---|
| 有键和源文本 | 当语言区域单元格为空或已过时,进行翻译。 |
| 有键,源单元格为空 | 原样保留,其语言区域单元格不作改动。 |
| 有源文本,键单元格为空或仅含空格 | 原样保留,不进行翻译。为其设置键后即可翻译。 |
| 键和源文本均为空,或为空白行 | 原样保留,仅含空格的行也是如此。 |
仅含空格的语言区域单元格视为空单元格。只要某一行的源文本自上次推送以来没有变化,该行已填充的单元格就会被复用。一旦源文本发生变化,该行所有语言区域单元格都会重新翻译。自上次推送后新增的行会保留已填充的单元格,只翻译空单元格;键发生变化的行也视为新增行。以下情况同样会保留已填充的单元格:首次推送该文件时;使用 CLI --force 时;GitHub App 命令指定了文件但未带 --force 时;以及此前推送的文件中没有唯一的源列或键列可供比较时(例如其中某一列被重命名后)。带有 --force 的 GitHub App 命令则会重新翻译文件中的每一行。
以下源文本会直接复制,不进行翻译:仅由 ASCII 数字 0 至 9 组成的文本,例如 100;符合以下条件的 URL:以 // 开头,或协议名仅由字母、数字或下划线组成,后接 ://,且 // 后的地址以 localhost 开头,或包含至少一个字符、一个点及点后至少两个字符,例如 https://lingo.dev/docs;仅由字母和数字组成、长度为 22 个字符的 ID,且至少包含一个大写字母、一个小写字母和一个数字;以及 ISO 8601 格式的日期或日期和时间,例如 2024-01-15 或 2024-01-15T10:00:00Z。源文本会写入所在行的每个目标语言区域单元格,覆盖单元格的原有内容;该行不会提交翻译,也不会计费。其他值仍会翻译,例如 1.5、100%、电子邮件地址,以及其他格式的日期(如 15.01.2024)。mailto: 和 tel: 链接、协议名包含其他字符的 URL(如 git+ssh://),以及地址不以 localhost 开头且不含上述点结构的 URL(如 https://intranet 或 https://a.b),也会翻译。
如果某个目标语言区域没有对应的列,会在表头末尾追加该列;需要新增多列时,按语言区域代码的字母顺序排列。随后每一行都会用空单元格补齐,确保表格保持规整的矩形结构。行本身绝不会被重新排序、添加或删除。
错误 #
出现以下任一情况时,该文件会在翻译和计费之前直接失败,错误消息会指明具体问题:
- 表头中找不到配置的
keyColumn,或第一个表头单元格为空且未设置keyColumn; - 两行的键相同,这会导致译文写入错误的行;
- 表头中没有源语言区域对应的列;
- 键列同时也是某个目标语言区域的列;
- 表头中多次出现配置的
keyColumn、源语言区域或某个目标语言区域; - 某一行的单元格数量多于表头;
- 带引号的单元格缺少闭合引号;
- 同一单元格中,闭合引号之后还有其他文本。
修复文件后重新推送即可。CLI 只会在该文件下方列出一次错误消息,而不会针对每个语言区域重复显示;如果整次运行失败,末尾的 Run failed: 行还会再次显示该消息。GitHub App 则会在检查运行中显示该消息。
修正现有译文 #
如需精确调整措辞,直接编辑对应单元格即可。如需重新生成某条译文,请清空该单元格、保留该行其余内容,然后执行一次普通推送:
lingo push --waitCLI --force 会复用已填充的单元格,这一点与处理 Apple 字符串目录 时一致。--key 无法缩小 CSV 文件的处理范围:CLI 会报错并中止推送,GitHub App 则会跳过该文件。CLI 清除也会跳过该文件,因为它的源文件和输出文件共用同一路径。提交之前,请审核整个文件的差异。