Merge pull request #5 from ZhangYingchun-OPPO/main

i18n for cards in quickapp project

Author: xiaomin1397

rfcs/1300/0001-快应用卡片多语言.md

@@ -0,0 +1,122 @@
+- 提案时间: 2023-10-20
+- 影响版本: 1.3.0.0
+- 相关 Issues: 无
+
+## 【必填】概述
+
+快应用卡片无法使用 $t 和 $tc 语法实现多语言覆盖，期望快应用卡片与快应用能力保持一致，也支持 $t 和 $tc。
+参考文档：https://doc.quickapp.cn/framework/i18n.html
+
+## 【必填】动机
+
+方便快应用混合工程（工程内同时包含快应用和卡片）卡片适配多语言。
+
+## 【必填】API规格和使用案例
+
+#### 资源文件
+在卡片路由路径下定义i18n文件夹，内部放置每个语言地区下的资源定义文件即可；其中文件名定义如：`zh-CN.json`。每个 JSON 文件的内容格式如下：
+```json
+{
+  "message": {
+    "card": {
+      "text": "pure-text-content",
+      "format": {
+        "object": "type-{name}",
+        "array": "type-{0}"
+      },
+      "array": [
+        "item-type-string",
+        {
+          "key": "item-type-object-attribute"
+        },
+        ["item-type-array"]
+      ],
+      "plurals": {
+        "double": "car | cars",
+        "three": "no apples | one apple | {count} apples",
+        "format": {
+          "object": "type-{name}",
+          "array": "type-{0}"
+        }
+      }
+    }
+  }
+}
+```
+
+#### 接口定义
+在卡片页面ux文件的`<template`或`<script>`中可以使用`$t`和`$tc`获取多语言文本。
+
+##### 代码示例
+```html
+<template>
+  <div>
+    <text>{{ $t('message.card.text') }}</text>
+    <text>{{ $t('message.card.format.object', { name: 'arg-object' }) }}</text>
+    <text>{{ $t('message.card.format.array', ['arg-array']) }}</text>
+  </div>
+</template>
+
+<script>
+  export default {
+    onInit () {
+      // 简单格式化：
+      this.$t('message.card.text')
+      this.$t('message.card.format.object', { name: 'arg-object' })
+      this.$t('message.card.format.array', ['arg-array'])
+
+      // 单复数格式化：
+      // 示例：message的值为两个选项时，传递数值不为单数
+      // 输出："cars"
+      this.$tc('message.card.plurals.double', 0)
+      // 示例：message的值为两个选项时，传递数值为单数
+      // 输出："car"
+      this.$tc('message.card.plurals.double', 1)
+      // 示例：message的值为两个选项时，传递数值不为单数
+      // 输出："cars"
+      this.$tc('message.card.plurals.double', 2)
+    }
+  }
+</script>
+```
+
+##### 简单格式化方法
+
+| 属性 | 类型  | 参数  | 描述  |
+| --- | --- | --- | --- |
+|  $t   | Function    | path: String 资源路径; arg0: object    | array 格式化参数，非必要参数，根据系统语言完成简单的替换：`this.$t('message.pageA.text')`    |
+
+##### 单复数格式化方法
+| 属性 | 类型  | 参数  | 描述  |
+| --- | --- | --- | --- |
+|  $tc   | Function    | path: String 资源路径; count: number要表达的值    | 根据系统语言完成单复数替换：`this.$tc('message.plurals.double')`，注意：定义资源的内容通过 | 分隔为多个选项    |
+
+
+## 【必填】提案人员是否愿意自行实现该功能
+
+是
+
+## 详细设计
+
+卡片内多语言覆盖逻辑与快应用保持一致：
+1. 开发者在卡片路由路径下新增 `i18n文件夹`，用于存放多语言资源；
+2. hap-toolkit打包工具需要在编译过程中将卡片的 `i18n` 资源拷贝到rpk文件对应的路径；
+3. 快应用引擎在卡片加载时，根据当前系统的语言地区返回对应的语言资源。
+
+## 缺陷
+
+我们是不是可以不做这个功能，请考虑：
+
+- 实现这个功能的投入：包括代码的复杂度、代码体积的增加、实现功能投入的人力
+- 这个功能是不是不需要 hapjs提供，使用 hapjs的开发者也可以在应用层实现，甚至实现得更好
+- 对 hapjs既有惯用开发习惯的影响
+- 对已发布版本和现有功能的影响，以及用户进行迁移的成本
+- 对其它未有代码实现的 RFC 提案的影响
+
+## 替代选择
+
+还有其他的方案也可以实现这个功能吗？
+
+## 适配策略
+
+如果我们实现了这个提案，有没有什么办法可以帮助开发者更好地适应这个改动？