diff --git a/README.md b/README.md index c3c85a6..6150943 100644 --- a/README.md +++ b/README.md @@ -26,8 +26,6 @@ luban相较于常规的excel导表工具有以下核心优势： - 完善的工作流支持。如id的外键引用检查;资源合法性检查;灵活的数据源定义（拆表或者多表合一）;灵活的分组导出机制；多种本地化支持;生成极快（日常迭代300ms以内）；Excel2TextDiff工具方便diff查看excel文件的版本间差异； - **=== LubanAssistant Excel插件 ===**。支持把json、lua、xml等文本格式的配置数据加载到excel中，批量编辑处理，最后再保存回原文件，较好地解决大型项目中多人合作数据编辑冲突合并的问题，较好解决在编辑器中制作的配置难以在excel中批量修改的问题。 -====**如果觉得不错，烦请点个star，你的支持会给予我们巨大动力 ^_^**==== - ## 文档 - [主页](https://focus-creative-games.github.io/luban/index.html) @@ -35,6 +33,7 @@ luban相较于常规的excel导表工具有以下核心优势： - [快速上手](docs/install.md) - [Excel 配置数据简介](docs/data_excel.md) - [client&server安装与使用说明](docs/luban_install_manual.md) +- [本地化](docs/l10n.md) - [文档目录](docs/catalog.md) - [完整手册](docs/manual.md) - **示例项目** ([github](https://github.com/focus-creative-games/luban_examples)) ([gitee](https://gitee.com/focus-creative-games/luban_examples)) diff --git a/docs/l10n.md b/docs/l10n.md index 833a952..8adf650 100644 --- a/docs/l10n.md +++ b/docs/l10n.md @@ -1,81 +1,139 @@ ## 本地化 +支持多种本地化机制，分别处理不同的场合，它们可以同时使用。 +### 静态文本值本地化 +对于需要本地化的文本值，在配置导出时既已完成本地化的转化，适用于不同地区打不同包或者不同配置的情形。通过以下几个方面来实现静态文本值本地化： +- 使用 text 类型标识需要本地化的字符串。 text类型由两个字段构成, key和value。 +- 使用本地化映射表提供text到其他语言的映射 +- 未完成本地化的text单独输出到一个文件，方便得知哪些文本值未完成本地化映射 -### 静态本地化 +#### 需要本地化的示例表 -单独提供了text类型来支持文本的本地化。 text类型由两个字段构成, key和value。 考虑到大多数项目是优先做了主地区配置后，再进行本地化，因此luban特地支持在配置中原地填写text的key和主地区文本值。制作其他地区配置时，通过指定本地化映射表的方式，再将该text转换为目标语言的文本值。 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
idnamedesccount
inttextstringint
1/demo/key1苹果这是一个苹果100
2/demo/key2香蕉这是香蕉100
3/demo/key3西瓜这是西瓜100
-![pipeline](images/examples/c_21.jpg) +#### 文本值映射文件 -主语言导出数据为 (只截取了部分数据) + +| key | origin_text | text_tw | text_en | +| - | - | - | - | +|本地化key| 原始值 | 繁体值 | 英文 | +|本地化key| 原始值 | 繁体值 | 英文 | +|/demo/key1|苹果|苹果|apple| +|/demo/key2|香蕉|香蕉|banana| + +### Luban.Client 命令 +有三个参数跟静态文本值本地化相关 +- input_l10n_text_files 本地化映射文件 +- l10n_text_field_name 映射的目标字段名。因为有可能多个语言都在同一个映射表内(如text_tw和text_en) +- output_l10n_not_translated_text_file 未完成文本值本地化映射的text + +以下为一个示例脚本 +```bat +%GEN_CLIENT% -h %LUBAN_SERVER_IP% -j cfg --^ + -d %DEFINE_FILE%^ + --input_data_dir %CONF_ROOT%\Datas ^ + --output_code_dir Gen ^ + --output_data_dir config_data ^ + --gen_types data_json ^ + -s all ^ +--input_l10n_text_files l10n/cn/TextTable_CN.xlsx ^ +--l10n_text_field_name text_en ^ +--output_l10n_not_translated_text_file NotLocalized_CN.txt +``` + +### 示例输出结果 + +导出json文件内容为 ```json [ { - "id": 11, + "id": 1, "text": { - "key": "/demo/1", - "text": "测试1" - } + "key": "/demo/key1", + "text": "apple" + }, + "desc": "这是一个苹果", + "count": 100 }, { - "id": 12, + "id": 2, "text": { - "key": "/demo/2", - "text": "测试2" - } + "key": "/demo/key2", + "text": "banana" + }, + "desc": "这是香蕉", + "count":100 }, { - "id": 13, + "id": 3, "text": { - "key": "/demo/3", - "text": "测试3" - } + "key": "/demo/key3", + "text": "西瓜" + }, + "desc":"这是西瓜", + "count": 100 } ] ``` -制作本地化映射表 +示例中 /demo/key3 在本地化映射表中未提供，因为output_l10n_not_translated_text_file 指定的未映射本地化文本值列表内容为。 -![pipeline](images/examples/c_22.jpg) - -映射到英语后的导出数据（只截取了部分数据）为 -```json -[ - { - "id": 11, - "text": { - "key": "/demo/1", - "text": "test1" - } - }, - { - "id": 12, - "text": { - "key": "/demo/2", - "text": "test2" - } - }, - { - "id": 13, - "text": { - "key": "/demo/3", - "text": "test3" - } - } -] +```text +/demo/key3|这是西瓜 ``` -### 动态本地化 -运行时动态切换语言到目标语言。 -生成的cfg.Tables包含TranslateText函数， 以c#为例。只需要提供一个 (string key, string origin_value) -> (string target_value) 的转换器， -就能自动将所有配置表中的text类型字段替换为目标语言的文本。程序不需要根据id去本地化映射表里查询，简化了使用。 +### 文本值动态本地化 +运行时动态切换text类型字段到目标语言，程序不需要根据id去本地化映射表里查询，简化了使用。注意，目前只有bean中text类型字段才支持，像list,text之类的暂未支持。通过以下几个方面支持文本值动态本地化： +- 标识字段为text类型 +- 提供 (string key, string origin_value) => (string target_value) 的本地化映射函数 +- 运行时调用 cfg.Tables.TranslateText函数，一键切换配置中所有text类型值到目标语言 + +本地化映射函数实现比较简单，核心在于如何制作文本值本地化映射配置？使用者既可以使用自定义本地化映射表，可以使用普通的 luban配置表来提供 文本值映射配置，如下图: +| key | origin_text | text_tw | text_en | +| - | - | - | - | +| string| string| string| string| +|本地化key| 原始值 | 繁体值 | 英文 | +|/demo/key1|苹果|苹果|apple| +|/demo/key2|香蕉|香蕉|banana| + +假设配置表的表名为 l10n.TbTextMapper，示例c#版本地化映射函数如下： ```c# -public void TranslateText(System.Func translator) +string TextMapper(string key, string originText) { - TbItem.TranslateText(translator); - ... + return tables.TbTextMapper.GetOrDefault(key) ?? originText; } ``` @@ -85,4 +143,10 @@ public void TranslateText(System.Func translator) ### 时间本地化 -datetime类型数据在指定了本地化时区后，会根据目标时区，生成相应时刻的UTC时间，方便程序使用 +datetime类型数据在指定了本地化时区后，会根据目标时区，生成相应时刻的UTC时间，方便程序使用. + +通过Luban.Client的参数来指定时区： + + -t,--l10n_timezone + +该时区为linux下的时区名，例如: -t "Asia/Shanghai" 指定目标时区为 亚洲上海（也即北京时间）