本地化（L10N）
Luban 提供几类可叠加使用的本地化能力：
- datetime 时区（
--timeZone） - text 类型校验（key 是否存在于文本表）
- 静态替换（生成期把 key 换成某语言文案）
- 字段变体（见 variants）
未设置 -x l10n.provider=... 时，text 校验与静态本地化都会关闭。
文本表（DefaultTextProvider）
逻辑上等价于一张「key + 各语言列」的表：
| key | zh | en |
|---|---|---|
| item.gold.name | 金币 | Gold |
| item.potion.name | 药水 | Potion |
可用 Excel，也可用 json 等（须符合 Luban 数据源格式）。json 一个文件多条时路径必须带 *@：
-x l10n.provider=default
-x l10n.textFile.path=*@Datas/l10n/texts.json
-x l10n.textFile.keyFieldName=key
| 参数 | 说明 |
|---|---|
l10n.provider | default 等；不设则关闭 text 相关 |
l10n.textFile.path | 文本数据路径；json 列表用 *@file.json |
l10n.textFile.keyFieldName | key 字段名，如 key |
只做 key 合法性校验时，语言列可以没有；静态替换才需要语言列。
texts.json 示意
[
{ "key": "item.gold.name", "zh": "金币", "en": "Gold" },
{ "key": "item.potion.name", "zh": "药水", "en": "Potion" }
]
text 类型（配置里写 key）
text 是语法糖，等价 string#text=1。字段语义是本地化 key，不是最终显示字符串。
<bean name="Item">
<var name="id" type="int"/>
<var name="name" type="text"/>
</bean>
| ##var | id | name |
|---|---|---|
| ##type | int | text |
| 1001 | item.gold.name | |
| 1002 | item.potion.name |
开启校验（key 必须出现在文本表）：
-x l10n.provider=default ^
-x l10n.textFile.path=*@Datas/l10n/texts.json ^
-x l10n.textFile.keyFieldName=key
静态替换（生成期 key → 文案）
在校验参数基础上再指定语言列，并打开转换开关：
-x l10n.provider=default ^
-x l10n.textFile.path=*@Datas/l10n/texts.json ^
-x l10n.textFile.keyFieldName=key ^
-x l10n.textFile.languageFieldName=zh ^
-x l10n.convertTextKeyToValue=1
导出后 name 字段直接是「金币」，运行时不必再查表。适合语言在打包时已固定的包体。
（l10n.languageFieldName 与 l10n.textFile.languageFieldName 在部分版本可互通，以 级联选项 为准。）
datetime 时区
datetime 按目标时区解释后写成 UTC 秒。默认本地时区；用 --timeZone 指定：
--timeZone "Asia/Shanghai"
# Windows 也可用：
--timeZone "China Standard Time"
注意：短选项 -t 是 target，不是时区。
导出待翻译 key 列表
用 dataTarget text-list 收集配置中出现的全部 text key：
dotnet Luban.dll --conf luban.conf -t all -d text-list ^
--validationFailAsError ^
-x outputDataDir=../Output/text ^
-x l10n.textListFile=texts.txt
与 variants 怎么选
| 需求 | 更合适 |
|---|---|
| 长文案、翻译流程、key 复用 | text + 文本表 |
| 同一数值/短字段多地区不同值，导出定死一版 | variants |
| 仅时间按地区解释 | --timeZone |
常见坑
- json 文本表忘了
*@前缀 → 加载失败。 - 配了
text字段却未设l10n.provider→ 校验静默关闭，错 key 进包。 - 静态替换未设
languageFieldName/convertTextKeyToValue→ 仍导出 key。 - 与 variants 两套同时维护同一文案 → 难同步。