From bd4b7ea561776d9d73cf8ad27f2a49f737e9f377 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Leslie=20Leigh=20=28=E6=9D=8E=E7=9A=84=E5=BA=8F=29?= Date: Fri, 9 Jun 2023 14:41:27 +0800 Subject: [PATCH 01/11] ContribDoc: i18n guidelines --- docs/contribution/i18n-zh.md | 68 ++++++++++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 docs/contribution/i18n-zh.md diff --git a/docs/contribution/i18n-zh.md b/docs/contribution/i18n-zh.md new file mode 100644 index 00000000000..835b22f2b55 --- /dev/null +++ b/docs/contribution/i18n-zh.md @@ -0,0 +1,68 @@ +# 国际化 + +本文描述在贡献引擎功能到本仓库时，如何将功能国际化。具体来说，本文描述： + +- 如何国际化一个 cc 类对象的可编辑属性。 + +## 术语 + +- `cc 类` + + 指那些用 `@ccclass` 装饰器装饰的类。 + +- `cc 类名` + + 指传给 `@ccclass()` 的类名参数。 + +- `编辑器属性` + + 指 cc 类中，那些用 `@editable`、`@visible` 等装饰器装饰的属性。这些属性会在编辑器中展示。 + +- `字典` + + 位于 `<本仓库>/editor/i18n/(en|zh)/localization.js` 中，里面以 JSON 形式记录了某些文本的中文、英文表示。 + +## 国际化 CC 类对象的可编辑属性 + +假设要操作类的 cc 类名为 `a.b.C`，要操作的属性在代码中的字段名为 `p`，为了在编辑器中国际化属性 `p` 的显示名称或工具提示，则需要保证字典中具有以下层级结构的数据： + +```js +{ + classes: { + 'a': { + 'b': { + 'C': { + properties: { + 'p': { + displayName: '<此属性的编辑器显示名称>', + tooltip: '<此属性的工具提示。>', + }, + }, + }, + }, + }, + }, +} +``` + +很多时候，类的属性来自于基类。这种情况下，子类的字典中可以通过 `__extends__` 来继承基类的字典： + +```js +{ + classes: { + 'base': { + properties: { + 'baseProp': { /* ... */ } + }, + }, + 'sub': { + properties: { + __extends__: 'classes.base.properties', // 注意，这里要填入的是基类字典的 `properties` 属性的完整路径。 + 'subProp': { /* ... */ } + }, + }, + }, +} +``` + +其效果就等同于子类的 `properties` 中也有了 `baseProp` 的部分。 From 6cabcb28929de016fe007834221e3faccfe94cbd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Leslie=20Leigh=20=28=E6=9D=8E=E7=9A=84=E5=BA=8F=29?= Date: Fri, 9 Jun 2023 14:49:21 +0800 Subject: [PATCH 02/11] Update i18n-zh.md --- docs/contribution/i18n-zh.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/contribution/i18n-zh.md b/docs/contribution/i18n-zh.md index 835b22f2b55..262ddc3bdad 100644 --- a/docs/contribution/i18n-zh.md +++ b/docs/contribution/i18n-zh.md @@ -24,16 +24,16 @@ ## 国际化 CC 类对象的可编辑属性 -假设要操作类的 cc 类名为 `a.b.C`，要操作的属性在代码中的字段名为 `p`，为了在编辑器中国际化属性 `p` 的显示名称或工具提示，则需要保证字典中具有以下层级结构的数据： +假设要操作类的 cc 类名为 `cc.animation.AnimationController`，要操作的属性在代码中的字段名为 `graph`，为了在编辑器中国际化该属性的的显示名称或工具提示，则需要保证字典中具有以下层级结构的数据： ```js { classes: { - 'a': { - 'b': { - 'C': { + 'cc': { + 'animation': { + 'AnimationController': { properties: { - 'p': { + 'graph': { displayName: '<此属性的编辑器显示名称>', tooltip: '<此属性的工具提示。>', }, From 858edf420b511fc5a67b63da2eff4239c23b50a0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Leslie=20Leigh=20=28=E6=9D=8E=E7=9A=84=E5=BA=8F=29?= Date: Fri, 9 Jun 2023 15:04:51 +0800 Subject: [PATCH 03/11] Update i18n-zh.md --- docs/contribution/i18n-zh.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/contribution/i18n-zh.md b/docs/contribution/i18n-zh.md index 262ddc3bdad..8081e587c32 100644 --- a/docs/contribution/i18n-zh.md +++ b/docs/contribution/i18n-zh.md @@ -45,6 +45,8 @@ } ``` +> 其实你不用写外层的 `classes: { "cc": { /* ... */ } }`，因为已经有这个部分了。 + 很多时候，类的属性来自于基类。这种情况下，子类的字典中可以通过 `__extends__` 来继承基类的字典： ```js From 43b3ee27033ab63e3d8461c3dab51ef47dd54450 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Leslie=20Leigh=20=28=E6=9D=8E=E7=9A=84=E5=BA=8F=29?= Date: Fri, 9 Jun 2023 15:09:08 +0800 Subject: [PATCH 04/11] Update i18n-zh.md --- docs/contribution/i18n-zh.md | 28 ++++++++++++---------------- 1 file changed, 12 insertions(+), 16 deletions(-) diff --git a/docs/contribution/i18n-zh.md b/docs/contribution/i18n-zh.md index 8081e587c32..66f72e33a44 100644 --- a/docs/contribution/i18n-zh.md +++ b/docs/contribution/i18n-zh.md @@ -24,29 +24,25 @@ ## 国际化 CC 类对象的可编辑属性 -假设要操作类的 cc 类名为 `cc.animation.AnimationController`，要操作的属性在代码中的字段名为 `graph`，为了在编辑器中国际化该属性的的显示名称或工具提示，则需要保证字典中具有以下层级结构的数据： +假设要操作类的 cc 类名为 `cc.animation.Animation`，要操作的属性在代码中的字段名为 `clips` 和 `defaultClip`，为了在编辑器中国际化这些属性的显示名称或工具提示，只需在字典的 `classes.cc` 对象里面，加入以下数据： ```js -{ - classes: { - 'cc': { - 'animation': { - 'AnimationController': { - properties: { - 'graph': { - displayName: '<此属性的编辑器显示名称>', - tooltip: '<此属性的工具提示。>', - }, - }, +'animation': { + 'AnimationController': { + properties: { + 'clips': { + displayName: '<属性 clips 的编辑器显示名称>', + tooltip: '<属性 clips 的工具提示。>', + }, + 'defaultClip': { + displayName: '<属性 defaultClip 的编辑器显示名称>', + tooltip: '<属性 defaultClip 的工具提示。>', }, }, }, - }, -} +}, ``` -> 其实你不用写外层的 `classes: { "cc": { /* ... */ } }`，因为已经有这个部分了。 - 很多时候，类的属性来自于基类。这种情况下，子类的字典中可以通过 `__extends__` 来继承基类的字典： ```js From 0a6a5faae9393c567be51bbe3cc418042ad1da65 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Leslie=20Leigh=20=28=E6=9D=8E=E7=9A=84=E5=BA=8F=29?= Date: Fri, 9 Jun 2023 15:10:22 +0800 Subject: [PATCH 05/11] Update i18n-zh.md --- docs/contribution/i18n-zh.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/contribution/i18n-zh.md b/docs/contribution/i18n-zh.md index 66f72e33a44..57271d0e977 100644 --- a/docs/contribution/i18n-zh.md +++ b/docs/contribution/i18n-zh.md @@ -27,6 +27,7 @@ 假设要操作类的 cc 类名为 `cc.animation.Animation`，要操作的属性在代码中的字段名为 `clips` 和 `defaultClip`，为了在编辑器中国际化这些属性的显示名称或工具提示，只需在字典的 `classes.cc` 对象里面，加入以下数据： ```js +// 确保这一段包裹在字典的 `classes.cc` 对象中。 'animation': { 'AnimationController': { properties: { From 3c74be695555082ea59674fdc69a10bfeb1c4d2e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Leslie=20Leigh=20=28=E6=9D=8E=E7=9A=84=E5=BA=8F=29?= Date: Fri, 9 Jun 2023 15:13:25 +0800 Subject: [PATCH 06/11] Update i18n-zh.md --- docs/contribution/i18n-zh.md | 35 ++++++++++++++++++++++------------- 1 file changed, 22 insertions(+), 13 deletions(-) diff --git a/docs/contribution/i18n-zh.md b/docs/contribution/i18n-zh.md index 57271d0e977..e31b09f1893 100644 --- a/docs/contribution/i18n-zh.md +++ b/docs/contribution/i18n-zh.md @@ -24,23 +24,32 @@ ## 国际化 CC 类对象的可编辑属性 -假设要操作类的 cc 类名为 `cc.animation.Animation`，要操作的属性在代码中的字段名为 `clips` 和 `defaultClip`，为了在编辑器中国际化这些属性的显示名称或工具提示，只需在字典的 `classes.cc` 对象里面，加入以下数据： +假设要操作类的 cc 类名为 `cc.Animation`，要操作的属性在代码中的字段名为 `clips` 和 `defaultClip`，为了在编辑器中国际化这些属性的显示名称或工具提示，只需在字典的 `classes.cc` 对象里面，加入以下数据： ```js // 确保这一段包裹在字典的 `classes.cc` 对象中。 -'animation': { - 'AnimationController': { - properties: { - 'clips': { - displayName: '<属性 clips 的编辑器显示名称>', - tooltip: '<属性 clips 的工具提示。>', - }, - 'defaultClip': { - displayName: '<属性 defaultClip 的编辑器显示名称>', - tooltip: '<属性 defaultClip 的工具提示。>', - }, - }, +'Animation': { + properties: { + 'clips': { + displayName: '<属性 clips 的编辑器显示名称>', + tooltip: '<属性 clips 的工具提示。>', + }, + 'defaultClip': { + displayName: '<属性 defaultClip 的编辑器显示名称>', + tooltip: '<属性 defaultClip 的工具提示。>', }, + }, +}, +``` + +又比如，你的 cc 类名是 `cc.physics.BoxCollidier`，那么只需在 `BoxCollidier` 外套个命名空间即可： + +``` +// 确保这一段包裹在字典的 `classes.cc` 对象中。 +'physics': { + 'BoxCollidier': { + properties: { /* ... */ }, + } }, ``` From 25aa2468d2287fac08163607aaa01799c00a9eb2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Leslie=20Leigh=20=28=E6=9D=8E=E7=9A=84=E5=BA=8F=29?= Date: Fri, 9 Jun 2023 15:20:42 +0800 Subject: [PATCH 07/11] Update i18n-zh.md --- docs/contribution/i18n-zh.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/contribution/i18n-zh.md b/docs/contribution/i18n-zh.md index e31b09f1893..ca6db349f68 100644 --- a/docs/contribution/i18n-zh.md +++ b/docs/contribution/i18n-zh.md @@ -20,7 +20,12 @@ - `字典` - 位于 `<本仓库>/editor/i18n/(en|zh)/localization.js` 中，里面以 JSON 形式记录了某些文本的中文、英文表示。 + 每个目标语言都有一个字典文件。里面存储的是一些文本在该语言中的表示。 本仓库目前支持简体中文和英文两种语言： + + - [简体中文](/editor/i18n/zh/localization.js) + - [英文](/editor/i18n/en/localization.js) + + > 该字典文件是用 JS 代码生成的。模块 `localization` 导出的内容就是字典对象的内容。 ## 国际化 CC 类对象的可编辑属性 @@ -44,7 +49,7 @@ 又比如，你的 cc 类名是 `cc.physics.BoxCollidier`，那么只需在 `BoxCollidier` 外套个命名空间即可： -``` +```js // 确保这一段包裹在字典的 `classes.cc` 对象中。 'physics': { 'BoxCollidier': { From dc6b867e1bcf10c1f9032b07212c044e8a4c9836 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Leslie=20Leigh=20=28=E6=9D=8E=E7=9A=84=E5=BA=8F=29?= Date: Fri, 9 Jun 2023 15:21:36 +0800 Subject: [PATCH 08/11] Update i18n-zh.md --- docs/contribution/i18n-zh.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/contribution/i18n-zh.md b/docs/contribution/i18n-zh.md index ca6db349f68..4ebe474c861 100644 --- a/docs/contribution/i18n-zh.md +++ b/docs/contribution/i18n-zh.md @@ -23,9 +23,10 @@ 每个目标语言都有一个字典文件。里面存储的是一些文本在该语言中的表示。 本仓库目前支持简体中文和英文两种语言： - [简体中文](/editor/i18n/zh/localization.js) + - [英文](/editor/i18n/en/localization.js) - > 该字典文件是用 JS 代码生成的。模块 `localization` 导出的内容就是字典对象的内容。 + > 该字典文件是用 JS 代码生成的。该 JS 模块导出的内容就是字典对象的内容。 ## 国际化 CC 类对象的可编辑属性 From 20c47e4c6da2a4eb33e7fcb9bd10a74f1bd40b65 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Leslie=20Leigh=20=28=E6=9D=8E=E7=9A=84=E5=BA=8F=29?= Date: Fri, 9 Jun 2023 15:23:04 +0800 Subject: [PATCH 09/11] Update i18n-zh.md --- docs/contribution/i18n-zh.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/contribution/i18n-zh.md b/docs/contribution/i18n-zh.md index 4ebe474c861..b6b49af9564 100644 --- a/docs/contribution/i18n-zh.md +++ b/docs/contribution/i18n-zh.md @@ -1,8 +1,8 @@ # 国际化 -本文描述在贡献引擎功能到本仓库时，如何将功能国际化。具体来说，本文描述： +本文描述在贡献引擎功能到本仓库时，如何将功能中出现的一些文本国际化。具体来说，本文描述： -- 如何国际化一个 cc 类对象的可编辑属性。 +- 如何让一个 cc 类对象的可编辑属性的 **显示名称**、**工具提示** 有贴合当前语言环境的表现。 ## 术语 From 863c26dd7ffa2f3210bd1257c4d160dc2eab780a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Leslie=20Leigh=20=28=E6=9D=8E=E7=9A=84=E5=BA=8F=29?= Date: Fri, 9 Jun 2023 15:28:13 +0800 Subject: [PATCH 10/11] Update i18n-zh.md --- docs/contribution/i18n-zh.md | 41 ++++++++++++++++++++++++++++++------ 1 file changed, 35 insertions(+), 6 deletions(-) diff --git a/docs/contribution/i18n-zh.md b/docs/contribution/i18n-zh.md index b6b49af9564..edf74bb85b1 100644 --- a/docs/contribution/i18n-zh.md +++ b/docs/contribution/i18n-zh.md @@ -30,7 +30,20 @@ ## 国际化 CC 类对象的可编辑属性 -假设要操作类的 cc 类名为 `cc.Animation`，要操作的属性在代码中的字段名为 `clips` 和 `defaultClip`，为了在编辑器中国际化这些属性的显示名称或工具提示，只需在字典的 `classes.cc` 对象里面，加入以下数据： +假设有以下 cc 类： + +```ts +@ccclass('cc.Animation') +class Animation { + @editable + clips: AnimationClip[] = []; + + @editable + defaultClip: AnimationClip | null = null; +} +``` + +为了在编辑器中多语言展示属性 `clips` 和 `defaultClip` 的显示名称或工具提示，只需在 **各个语言字典** 的 `classes.cc` 对象里面，加入以下数据： ```js // 确保这一段包裹在字典的 `classes.cc` 对象中。 @@ -59,19 +72,36 @@ }, ``` -很多时候，类的属性来自于基类。这种情况下，子类的字典中可以通过 `__extends__` 来继承基类的字典： +很多时候，类的属性来自于基类。例如： + +```ts +@ccclass('Base') +class Base { + @editable + baseProp = 1; +} + +@ccclass('Sub') +class Sub extends Base { + @editable + subProp = false; +} +``` + +为了声明这种属性继承关系，子类的字典中可以通过 `__extends__` 来继承基类的字典： ```js { classes: { - 'base': { + 'base': { // 基类字典 properties: { 'baseProp': { /* ... */ } }, }, - 'sub': { + + 'sub': { // 子类字典 properties: { - __extends__: 'classes.base.properties', // 注意，这里要填入的是基类字典的 `properties` 属性的完整路径。 + __extends__: 'classes.base.properties', // 继承基类字典的所有属性。注意，这里要填入的是基类字典的 `properties` 属性的完整路径。 'subProp': { /* ... */ } }, }, @@ -79,4 +109,3 @@ } ``` -其效果就等同于子类的 `properties` 中也有了 `baseProp` 的部分。 From 973f9048e43a4a3682f67fecc61e167834baee37 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Leslie=20Leigh=20=28=E6=9D=8E=E7=9A=84=E5=BA=8F=29?= Date: Fri, 9 Jun 2023 15:28:54 +0800 Subject: [PATCH 11/11] Update i18n-zh.md --- docs/contribution/i18n-zh.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/contribution/i18n-zh.md b/docs/contribution/i18n-zh.md index edf74bb85b1..1fc5a799d36 100644 --- a/docs/contribution/i18n-zh.md +++ b/docs/contribution/i18n-zh.md @@ -72,6 +72,8 @@ class Animation { }, ``` +### 字典继承 + 很多时候，类的属性来自于基类。例如： ```ts