【更新】更新本地化相关文档

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))

docs/l10n.md

@@ -1,81 +1,139 @@
 ## 本地化
+支持多种本地化机制，分别处理不同的场合，它们可以同时使用。
+### 静态文本值本地化
+对于需要本地化的文本值，在配置导出时既已完成本地化的转化，适用于不同地区打不同包或者不同配置的情形。通过以下几个方面来实现静态文本值本地化：
+- 使用 text 类型标识需要本地化的字符串。 text类型由两个字段构成, key和value。
+- 使用本地化映射表提供text到其他语言的映射
+- 未完成本地化的text单独输出到一个文件，方便得知哪些文本值未完成本地化映射
 
-### 静态本地化
+#### 需要本地化的示例表
 
-单独提供了text类型来支持文本的本地化。 text类型由两个字段构成, key和value。 考虑到大多数项目是优先做了主地区配置后，再进行本地化，因此luban特地支持在配置中原地填写text的key和主地区文本值。制作其他地区配置时，通过指定本地化映射表的方式，再将该text转换为目标语言的文本值。
+<table border="1">
+<tr align="center">
+  <td>id</td>
+  <td colspan="2">name</td>
+  <td>desc</td>
+  <td>count</td>
+</tr>
+<tr align="center">
+  <td>int</td>
+  <td colspan="2">text</td>
+  <td>string</td>
+  <td>int</td>
+</tr>
+<tr align="center">
+  <td>1</td>
+  <td>/demo/key1</td><td>苹果</td>
+  <td>这是一个苹果</td>
+  <td>100</td>
+</tr>
+<tr align="center">
+  <td>2</td>
+  <td>/demo/key2</td><td>香蕉</td>
+  <td>这是香蕉</td>
+  <td>100</td>
+</tr>
+<tr align="center">
+  <td>3</td>
+  <td>/demo/key3</td><td>西瓜</td>
+  <td>这是西瓜</td>
+  <td>100</td>
+</tr>
+</table>
 
-![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",
+      "key": "/demo/key1",
-      "text": "测试1"
+      "text": "apple"
-    }
+    },
+    "desc": "这是一个苹果",
+    "count": 100
   },
   {
-    "id": 12,
+    "id": 2,
     "text": {
-      "key": "/demo/2",
+      "key": "/demo/key2",
-      "text": "测试2"
+      "text": "banana"
-    }
+    },
+    "desc": "这是香蕉",
+    "count":100
   },
   {
-    "id": 13,
+    "id": 3,
     "text": {
-      "key": "/demo/3",
+      "key": "/demo/key3",
-      "text": "测试3"
+      "text": "西瓜"
-    }
+    },
+    "desc":"这是西瓜",
+    "count": 100
   }
 ]
 ```
 
-制作本地化映射表 
+示例中 /demo/key3 在本地化映射表中未提供，因为output_l10n_not_translated_text_file 指定的未映射本地化文本值列表内容为。
 
-![pipeline](images/examples/c_22.jpg)
+```text
-
+/demo/key3|这是西瓜
-映射到英语后的导出数据（只截取了部分数据）为
-```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"
-    }
-  }
-]
 ```
 
-### 动态本地化
-运行时动态切换语言到目标语言。
 
-生成的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<string, string, string> 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<string, string, string> translator)
 
 
 ### 时间本地化
-datetime类型数据在指定了本地化时区后，会根据目标时区，生成相应时刻的UTC时间，方便程序使用
+datetime类型数据在指定了本地化时区后，会根据目标时区，生成相应时刻的UTC时间，方便程序使用.
+
+通过Luban.Client的参数来指定时区：
+
+  -t,--l10n_timezone <timezone>   
+
+该时区为linux下的时区名，例如: -t "Asia/Shanghai"  指定目标时区为 亚洲上海（也即北京时间）