Java properties

逐键翻译 Java .properties 资源包,完整保留注释、空行和每一行的布局。

.properties 文件将键映射到消息,每行一个条目,供 Java 的 ResourceBundle 和 Spring 的 MessageSource 读取。properties 文件处理器会翻译每个键的值,并写入源文件的副本中。注释、空行、键的顺序、分隔符和间距都会原样保留,唯一变化的只有已翻译键的值。

配置 properties 翻译 #

properties 文件只会归入满足以下条件之一的文件条目:匹配模式以 .properties 结尾(此时会自动推断格式),或设置了 "format": "properties"。设置了 "format": "properties" 的条目只会选中 .properties 文件。像 src/main/resources/**/* 这样的宽泛模式,如果没有指定该格式,就不会选中任何 properties 文件,因此 application.properties 等配置文件不会被意外翻译。

如果文件名中包含语言区域(例如 messages_en.properties),每个目标文件都会生成在源文件旁边,并在文件名的相同位置替换为目标语言区域。语言区域采用 Java 的下划线形式 pt_BR,以便 ResourceBundle 查找:

json
{
  "sourceLocale": "en",
  "targetLocales": ["de", "pt-BR"],
  "files": [{ "pattern": "src/main/resources/messages_en.properties" }]
}

这样会写入 messages_de.properties 和 messages_pt_BR.properties。带地区的源语言区域也按同样方式查找:设置 "sourceLocale": "en-US" 时,源文件为 messages_en_US.properties。如需使用其他形式,可在条目上设置 localeFormat,例如为 pt-BR 使用 "bcp47"。如果源文件是文件名中不含语言区域的默认资源包 messages.properties,请声明目标路径:

json
{
  "pattern": "src/main/resources/messages.properties",
  "targetPath": "src/main/resources/messages_[locale].properties"
}

同一套配置在 CLI 和 GitHub App 中均可使用。

文件读取方式 #

键和值的读取方式与 java.util.Properties 完全一致:

  • 单元。 每个键就是一个单元。同一个键出现两次时只会翻译一次,采用 Java 实际读取的值,也就是最后一个值。该键出现的每一处都会写入译文。
  • 分隔符。 键和值之间可用 =、: 或空白字符分隔,= 和 : 两侧可以留有空格。
  • 注释和空行。 第一个非空白字符为 # 或 ! 的行即为注释。注释和空行永远不会发送去翻译。
  • 续行。 以 \ 结尾的行会延续到下一行,下一行开头的空格会被去除。跨行的值写回时会合并为一行。
  • 转义。 \uXXXX、\t、\n、\r、\f、\=、\:、\ 、\\ 以及其他所有转义字符都会在翻译前解码。\u 转义格式错误时,文件会处理失败,这与 Java 的行为保持一致。
  • 空值。 值为空或仅含空格的键会原样保留,不做翻译。目标文件中的空值视为未翻译,但 preservedKeys 中的键除外,其空值会被保留。

文件按 UTF-8 读取。不支持以 ISO-8859-1 保存且直接包含重音字符原始字节的文件;请将其另存为 UTF-8,或将这些字符写成 \uXXXX。文件开头的 UTF-8 字节顺序标记不会保留。

译文写入方式 #

每个翻译后的值都会经过转义,确保 Java 读回时内容不变。转义对象包括:反斜杠、换行符、制表符、换页符及其他控制字符,以及位于开头的空格、= 或 :。非 ASCII 字符如何写入,取决于文件中已有的值(注释不计在内):

目标文件中的值(首个目标文件生成前,则看源文件中的值)é 或 中 等字符的写入方式
已包含未转义的 UTF-8 文本原样写入
仅包含 ASCII写为 \u00E9、\u4E2D

采用转义形式时,写入的每个值都会转义,包括在源文件中含有未转义文本的锁定值或保留值。转义后的文件既能用 UTF-8 读取器加载,也能用按 ISO-8859-1 读取的 Properties.load(InputStream) 加载。

{0}、{name} 和 %s 等占位符会在译文中保留。Java MessageFormat 的引号规则(例如在带参数的消息中用 '' 表示单引号)不会自动替你处理。

保留键和文本不翻译 #

lockedKeys、preservedKeys 和 ignoredKeys 会匹配整个键,与旧版 CLI 的行为一致:模式会匹配与其完全相同的键、在其后以 .、/ 或 - 延续的键,或按通配符规则与其匹配的键。因此,app 匹配 app.title,app.* 匹配 app.title 和 app.menu.save,*.port 匹配 server.port。以 $ 开头的模式则作为针对键的 JSONPath 查询,例如 $["app.title"]。

选项目标文件中的结果
lockedKeys使用源值,永远不会发送去翻译。
preservedKeys使用目标文件中的现有值;没有现有值时使用源值。
ignoredKeys整个条目都会被省略,续行也一并省略。

lockedPatterns 可让值中的部分内容保持不翻译。每个条目都是一个采用 RE2 语法的正则表达式,每个值中的所有匹配内容都会被锁定;^ 和 $ 可在值内部的换行处匹配:

json
{
  "pattern": "src/main/resources/messages_en.properties",
  "lockedPatterns": ["\\{\\{[^}]+\\}\\}"]
}

匹配内容会作为必须保留的标记发送给模型,并逐字节原样写回。如果译文丢失或改动了匹配内容,就会被拒绝,绝不会写入。模式只在每个值内部匹配,不会跨行、跨键或跨注释。在含有匹配内容的值中,{0} 和 %s 等占位符也会以同样方式受到保护。

RE2 的运行时间与文本长度成正比,因此不支持环视((?=、(?!、(?<=、(?<!)和反向引用(\1、\k<name>)。非 ASCII 字符请写成 \x{00E9},而不是 \u00E9。CLI 和 GitHub App 在读取配置时会拒绝非正则表达式的模式;如果模式用到了 RE2 不支持的语法,推送会失败并指出是哪个模式。lockedPatterns 仅适用于 properties 文件:其他格式的条目若设置了该选项,会被拒绝。

--key 可将推送范围缩小到其指定的键,匹配方式与 lockedKeys 相同。

复用与修正 #

只要某个键的源值自上次推送以来没有变化,就会沿用现有译文。源值一旦变化,该键就会重新翻译。仅存在于目标文件中的键会被移除,目标文件中的键会遵循源文件的顺序和布局。

使用 --key 推送时,则改为编辑现有目标文件:只有选中的值会改变,目标文件中的其他行(包括仅它自己拥有的键及其注释)均保持原样。目标文件中缺少的选中键会追加到文件末尾。

如需修正某条译文,直接在目标文件中编辑即可。如需重新生成,请使用 --key 再次推送:

sh
lingo push --key checkout.title --wait