From baa108406d8c019986b59085a943bdad1faca3c3 Mon Sep 17 00:00:00 2001 From: koishi-bot <105629226+koishi-bot@users.noreply.github.com> Date: Thu, 7 Dec 2023 00:46:03 +0800 Subject: [PATCH] i18n: update translations (#128) --- .vitepress/config/en-US.json | 60 +++++----- .vitepress/config/fr-FR.json | 80 ++++++------- de-DE/api/core/app.md | 13 +- de-DE/guide/basic/element.md | 2 +- de-DE/guide/develop/publish.md | 34 ++++-- de-DE/guide/develop/script.md | 12 +- de-DE/guide/i18n/index.md | 84 +++++++++++-- de-DE/manual/usage/market.md | 22 ++-- de-DE/plugins/adapter/wechat-official.md | 2 +- en-US/about/contact.md | 14 +-- en-US/about/license.md | 16 +-- en-US/about/releases.md | 18 +-- en-US/about/team.md | 2 +- en-US/api/core/app.md | 13 +- en-US/api/service/events.md | 2 +- en-US/cookbook/design/disposable.md | 2 +- en-US/cookbook/index.md | 2 +- en-US/cookbook/practice/testing.md | 2 +- en-US/guide/basic/element.md | 26 ++-- en-US/guide/develop/publish.md | 145 ++++++++++++----------- en-US/guide/develop/script.md | 50 ++++---- en-US/guide/develop/workspace.md | 88 +++++++------- en-US/guide/i18n/index.md | 84 +++++++++++-- en-US/guide/i18n/translation.md | 2 +- en-US/index.md | 2 +- en-US/manual/starter/boilerplate.md | 6 +- en-US/manual/starter/direct.md | 2 +- en-US/manual/usage/adapter.md | 6 +- en-US/manual/usage/market.md | 70 ++++++----- en-US/manual/usage/platform.md | 4 +- en-US/plugins/adapter/wechat-official.md | 2 +- en-US/plugins/console/market.md | 2 +- en-US/releases/v4.14.md | 2 +- fr-FR/about/events.md | 2 +- fr-FR/about/releases.md | 2 +- fr-FR/about/team.md | 2 +- fr-FR/about/upgrade.md | 2 +- fr-FR/api/core/app.md | 13 +- fr-FR/cookbook/design/disposable.md | 2 +- fr-FR/cookbook/design/framework.md | 2 +- fr-FR/cookbook/design/storage.md | 2 +- fr-FR/cookbook/practice/testing.md | 2 +- fr-FR/guide/basic/element.md | 2 +- fr-FR/guide/develop/publish.md | 38 +++--- fr-FR/guide/develop/script.md | 12 +- fr-FR/guide/i18n/index.md | 84 +++++++++++-- fr-FR/guide/i18n/translation.md | 2 +- fr-FR/manual/starter/android.md | 2 +- fr-FR/manual/starter/boilerplate.md | 2 +- fr-FR/manual/starter/docker.md | 2 +- fr-FR/manual/starter/linux.md | 2 +- fr-FR/manual/starter/macos.md | 2 +- fr-FR/manual/starter/windows.md | 2 +- fr-FR/manual/usage/market.md | 44 +++---- fr-FR/plugins/adapter/wechat-official.md | 2 +- ja-JP/api/core/app.md | 13 +- ja-JP/guide/basic/element.md | 2 +- ja-JP/guide/develop/publish.md | 38 +++--- ja-JP/guide/develop/script.md | 12 +- ja-JP/guide/i18n/index.md | 84 +++++++++++-- ja-JP/manual/usage/market.md | 20 ++-- ja-JP/plugins/adapter/wechat-official.md | 2 +- ru-RU/api/core/app.md | 13 +- ru-RU/guide/basic/element.md | 2 +- ru-RU/guide/develop/publish.md | 34 ++++-- ru-RU/guide/develop/script.md | 12 +- ru-RU/guide/i18n/index.md | 84 +++++++++++-- ru-RU/manual/usage/market.md | 18 +-- ru-RU/plugins/adapter/wechat-official.md | 2 +- zh-TW/api/core/app.md | 13 +- zh-TW/guide/basic/element.md | 2 +- zh-TW/guide/develop/publish.md | 38 +++--- zh-TW/guide/develop/script.md | 12 +- zh-TW/guide/i18n/index.md | 84 +++++++++++-- zh-TW/manual/usage/market.md | 36 +++--- zh-TW/plugins/adapter/wechat-official.md | 2 +- 76 files changed, 1028 insertions(+), 591 deletions(-) diff --git a/.vitepress/config/en-US.json b/.vitepress/config/en-US.json index e2670ff5117a..12435446821a 100644 --- a/.vitepress/config/en-US.json +++ b/.vitepress/config/en-US.json @@ -43,7 +43,7 @@ "link": "/guide/" }, { - "text": "进阶指南", + "text": "Advanced Guide", "link": "/cookbook/" }, { @@ -125,7 +125,7 @@ "link": "/manual/starter/docker.md" }, { - "text": "Create Template Project", + "text": "Create from Template", "link": "/manual/starter/boilerplate.md" }, { @@ -216,7 +216,7 @@ "link": "/guide/develop/config.md" }, { - "text": "Bootstrap Script", + "text": "Launch Script", "link": "/guide/develop/script.md" }, { @@ -354,11 +354,11 @@ "text": "Internationalization", "items": [ { - "text": "基本用法", + "text": "Basic Usage", "link": "/guide/i18n/index.md" }, { - "text": "本地化文件", + "text": "Localization File", "link": "/guide/i18n/translation.md" }, { @@ -374,7 +374,7 @@ { "items": [ { - "text": "→ 进阶指南", + "text": "→ Advanced Guide", "link": "/cookbook/" } ] @@ -441,11 +441,11 @@ "text": "Built-in Services", "items": [ { - "text": "事件系统 (Events)", + "text": "Events", "link": "/api/service/events.md" }, { - "text": "过滤器 (Filter)", + "text": "Filter", "link": "/api/service/filter.md" }, { @@ -457,11 +457,11 @@ "link": "/api/service/i18n.md" }, { - "text": "加载器 (Loader)", + "text": "Loader", "link": "/api/service/loader.md" }, { - "text": "权限管理 (Permissions)", + "text": "Permissions", "link": "/api/service/permissions.md" }, { @@ -494,23 +494,23 @@ "link": "/api/resources/role.md" }, { - "text": "交互 (Interaction)", + "text": "Interaction", "link": "/api/resources/interaction.md" }, { - "text": "登录状态 (Login)", + "text": "Login", "link": "/api/resources/login.md" }, { - "text": "消息 (Message)", + "text": "Message", "link": "/api/resources/message.md" }, { - "text": "表态 (Reaction)", + "text": "Reaction", "link": "/api/resources/reaction.md" }, { - "text": "用户 (User)", + "text": "User", "link": "/api/resources/user.md" } ] @@ -622,14 +622,14 @@ ] }, { - "text": "设计原理", + "text": "Design", "items": [ { - "text": "项目架构", + "text": "Infrastructure", "link": "/cookbook/design/structure.md" }, { - "text": "可逆的插件系统", + "text": "Disposable Plugin System", "link": "/cookbook/design/disposable.md" }, { @@ -647,7 +647,7 @@ ] }, { - "text": "最佳实践", + "text": "Cookbook", "items": [ { "text": "资源转存", @@ -666,7 +666,7 @@ "link": "/cookbook/practice/bundle.md" }, { - "text": "编写测试", + "text": "Writing Tests", "link": "/cookbook/practice/testing.md" } ] @@ -743,7 +743,7 @@ "link": "/plugins/adapter/telegram.md" }, { - "text": "微信公众号", + "text": "WeChat Official", "link": "/plugins/adapter/wechat-official.md" }, { @@ -858,7 +858,7 @@ "link": "/plugins/console/logger.md" }, { - "text": "插件市场 (Market)", + "text": "Plugin Manager (Market)", "link": "/plugins/console/market.md" }, { @@ -1028,7 +1028,7 @@ ], "/about/": [ { - "text": "关于", + "text": "About", "items": [ { "text": "License", @@ -1039,7 +1039,7 @@ "link": "/about/contact.md" }, { - "text": "认识团队", + "text": "Meet the Team", "link": "/about/team.md" }, { @@ -1076,13 +1076,13 @@ "link": "/releases/index.md" }, { - "text": "更新日志", + "text": "Changelog", "link": "https://github.com/koishijs/koishi/releases" } ] }, { - "text": "贡献", + "text": "Contribution", "items": [ { "text": "Infrastructure", @@ -1152,15 +1152,15 @@ "link": "/releases/v4.12.md" }, { - "text": "v4.13 版本介绍", + "text": "Release Notes: v4.13", "link": "/releases/v4.13.md" }, { - "text": "v4.14 版本介绍", + "text": "Release Notes: v4.14", "link": "/releases/v4.14.md" }, { - "text": "v4.15 版本介绍", + "text": "Release Notes: v4.15", "link": "/releases/v4.15.md" } ] @@ -1169,7 +1169,7 @@ "text": "", "items": [ { - "text": "更新日志", + "text": "Change Log", "link": "https://github.com/koishijs/koishi/releases" } ] diff --git a/.vitepress/config/fr-FR.json b/.vitepress/config/fr-FR.json index d2de4af1bee7..43f05fbbc5ea 100644 --- a/.vitepress/config/fr-FR.json +++ b/.vitepress/config/fr-FR.json @@ -75,11 +75,11 @@ "text": "À propos", "items": [ { - "text": "参与讨论", + "text": "Communauté de Koishi", "link": "/about/contact.md" }, { - "text": "各版本介绍", + "text": "Notes des versions", "link": "/releases/index.md" } ], @@ -354,19 +354,19 @@ "text": "Internationalisation", "items": [ { - "text": "基本用法", + "text": "Utilisation de base", "link": "/guide/i18n/index.md" }, { - "text": "本地化文件", + "text": "Fichier de localisation", "link": "/guide/i18n/translation.md" }, { - "text": "语言包开发", + "text": "Développement de paquet de langage", "link": "/guide/i18n/lang-pack.md" }, { - "text": "接入 Crowdin", + "text": "Collaboration avec Crowdin", "link": "/guide/i18n/crowdin.md" } ] @@ -629,19 +629,19 @@ "link": "/cookbook/design/structure.md" }, { - "text": "可逆的插件系统", + "text": "Système réversible de plugin", "link": "/cookbook/design/disposable.md" }, { - "text": "从元框架到框架", + "text": "Du méta-framework au framework", "link": "/cookbook/design/framework.md" }, { - "text": "零占用的存储", + "text": "Stockage avec zéro volume", "link": "/cookbook/design/storage.md" }, { - "text": "深入工作区", + "text": "Approfondis sur l'escape de travail", "link": "/cookbook/design/workspace.md" } ] @@ -650,7 +650,7 @@ "text": "Meilleures pratiques", "items": [ { - "text": "资源转存", + "text": "Cache des fichiers de ressources", "link": "/cookbook/practice/assets.md" }, { @@ -662,11 +662,11 @@ "link": "/cookbook/practice/online.md" }, { - "text": "整合包开发", + "text": "Développement de paquet intégré", "link": "/cookbook/practice/bundle.md" }, { - "text": "编写测试", + "text": "Écrit des tests", "link": "/cookbook/practice/testing.md" } ] @@ -1028,7 +1028,7 @@ ], "/about/": [ { - "text": "关于", + "text": "À propos", "items": [ { "text": "Licence ", @@ -1039,7 +1039,7 @@ "link": "/about/contact.md" }, { - "text": "认识团队", + "text": "À propos de l'équipe", "link": "/about/team.md" }, { @@ -1047,42 +1047,42 @@ "link": "/about/faq.md" }, { - "text": "社区资源", + "text": "Ressources Communautaires", "link": "/about/community.md" }, { - "text": "大事件", + "text": "Le Grand Événement", "link": "/about/events.md" } ] }, { - "text": "更新", + "text": "Mettre à jour", "items": [ { "text": "Histoire", "link": "/about/history.md" }, { - "text": "更新计划", + "text": "Mettre à jour l'horaire", "link": "/about/releases.md" }, { - "text": "从低版本迁移", + "text": "Migration depuis une version ancienne", "link": "/about/upgrade.md" }, { - "text": "各版本介绍", + "text": "Notes des versions", "link": "/releases/index.md" }, { - "text": "更新日志", + "text": "Notes de mise à jour", "link": "https://github.com/koishijs/koishi/releases" } ] }, { - "text": "贡献", + "text": "Contributions", "items": [ { "text": "Structure du projet", @@ -1100,67 +1100,67 @@ "text": "", "items": [ { - "text": "各版本介绍", + "text": "Notes des versions", "link": "/releases/index.md" }, { - "text": "v4.1 版本介绍", + "text": "Notes de version : v4.1", "link": "/releases/v4.1.md" }, { - "text": "v4.2 版本介绍", + "text": "Notes de version : v4.2", "link": "/releases/v4.2.md" }, { - "text": "v4.3 版本介绍", + "text": "Notes de version : v4.3", "link": "/releases/v4.3.md" }, { - "text": "v4.4 版本介绍", + "text": "Notes de version : v4.4", "link": "/releases/v4.4.md" }, { - "text": "v4.5 版本介绍", + "text": "Notes de version : v4.5", "link": "/releases/v4.5.md" }, { - "text": "v4.6 版本介绍", + "text": "Notes de version : v4.6", "link": "/releases/v4.6.md" }, { - "text": "v4.7 版本介绍", + "text": "Notes de version : v4.7", "link": "/releases/v4.7.md" }, { - "text": "v4.8 版本介绍", + "text": "Notes de version : v4.8", "link": "/releases/v4.8.md" }, { - "text": "v4.9 版本介绍", + "text": "Notes de version : v4.9", "link": "/releases/v4.9.md" }, { - "text": "v4.10 版本介绍", + "text": "Notes de version : v4.10", "link": "/releases/v4.10.md" }, { - "text": "v4.11 版本介绍", + "text": "Notes de version : v4.11", "link": "/releases/v4.11.md" }, { - "text": "v4.12 版本介绍", + "text": "Notes de version : v4.12", "link": "/releases/v4.12.md" }, { - "text": "v4.13 版本介绍", + "text": "Notes de version : v4.13", "link": "/releases/v4.13.md" }, { - "text": "v4.14 版本介绍", + "text": "Notes de version : v4.14", "link": "/releases/v4.14.md" }, { - "text": "v4.15 版本介绍", + "text": "Notes de version : v4.15", "link": "/releases/v4.15.md" } ] @@ -1169,7 +1169,7 @@ "text": "", "items": [ { - "text": "更新日志", + "text": "Notes de mise à jour", "link": "https://github.com/koishijs/koishi/releases" } ] diff --git a/de-DE/api/core/app.md b/de-DE/api/core/app.md index c01b54ca7836..9ecda1457034 100644 --- a/de-DE/api/core/app.md +++ b/de-DE/api/core/app.md @@ -91,13 +91,13 @@ interface DelayOptions { ## 国际化设置 -### options.i18n.locales +### options.i18n.locales {#i18n-locales} - 类型：`string[]` 可用的语言列表。按照回退顺序排列。 -### options.i18n.output +### options.i18n.output {#i18n-output} - 类型：`string` @@ -106,15 +106,6 @@ interface DelayOptions { - `prefer-user`: 优先使用用户语言 - `prefer-channel`: 优先使用频道语言 -## 高级设置 - -### options.maxListeners - -- 类型：`number` -- 默认值：`64` - -每种钩子的最大数量。如果超过这个数量，Koishi 会认定为发生了内存泄漏，将产生一个警告。 - ## 请求设置 ### options.request.proxyAgent diff --git a/de-DE/guide/basic/element.md b/de-DE/guide/basic/element.md index e526981f01bd..a1fcc6a86567 100644 --- a/de-DE/guide/basic/element.md +++ b/de-DE/guide/basic/element.md @@ -165,7 +165,7 @@ Koishi 已经内置了一系列消息组件，包括： 你可以在 [这个页面](../../api/message/components.md) 了解每个组件的详细用法和适用范围。 -### 声明消息组件 +### 定义消息组件 一个消息组件本质上是一个函数，它接受三个参数： diff --git a/de-DE/guide/develop/publish.md b/de-DE/guide/develop/publish.md index 27ee42ad365f..670e6f105140 100644 --- a/de-DE/guide/develop/publish.md +++ b/de-DE/guide/develop/publish.md @@ -2,7 +2,7 @@ 为了让别人更方便地使用你编写的插件，你需要将其作为一个 npm 包进行发布。只需满足一定的规范，你的插件就能显示在 [插件市场](../../market/) 中，其他人就可以通过控制台来安装它。 -::: tip +:::tip 本节中介绍的命令行都需要在 [应用目录](./config.md#应用目录) 下运行。 ::: @@ -21,7 +21,7 @@ root └── package.json # 而不是这里 ``` -::: tip +:::tip 请注意 `package.json` 文件不是唯一的，它在应用目录和每个插件目录都会存在。请确保你修改了正确的文件。 ::: @@ -37,7 +37,7 @@ root 其中最重要的属性有两个：`name` 是要发布的包名，`version` 是包的版本号。这里的包名相比实际在插件市场中看到的插件名多了一个 `koishi-plugin-` 的前缀，这样既方便了用户安装和配置，又防止了污染命名空间。 -::: tip +:::tip 请注意：包名和版本号都具有唯一性。包名不能与其他已经发布的包相同，而同一个包的同一个版本号也只能发布一次。如果出现了包名冲突或版本号冲突，则会在之后的发布流程中出现错误提示。你可以自行根据错误提示更换包名或更新插件版本。 ::: @@ -47,7 +47,7 @@ root ### 准入条件 -::: tip +:::tip 使用模板项目创建的插件一定是符合要求的，因此你可以跳过这一节。 ::: @@ -142,7 +142,7 @@ root - **preview:** 配置为 `true` 可以让插件显示为「开发中」状态 - **hidden:** 配置为 `true` 可以让插件市场中不显示该插件 (通常情况下你不需要这么做) -::: tip +:::tip 此外，还有一些字段与 [Koishi Online](../../cookbook/practice/online.md) 的部署流程相关 (如 `browser`, `exports` 等)。由于不影响主线开发，你可以稍后再进行了解。 ::: @@ -150,20 +150,23 @@ root 编辑完上面的清单文件并 [构建源代码](./workspace.md#构建源代码) 后，你就可以公开发布你的插件了。 -::: tabs code +:::tabs code + ```npm npm run pub [...name] ``` + ```yarn yarn pub [...name] ``` + ::: - **name:** 要发布的插件列表，缺省时表示全部 (此处 `name` 不包含 `koishi-plugin-` 前缀，而是你的工作区目录名) 这将发布所有版本号发生变动的插件。 -::: tip +:::tip 从插件成功发布到进插件市场需要一定的时间 (通常在 15 分钟内)，请耐心等待。 ::: @@ -176,39 +179,46 @@ No token found and can't prompt for login when running with --non-interactive. 此时你需要在发布时使用官方镜像，具体操作如下： -::: tabs code +:::tabs code + ```npm npm run pub [...name] -- --registry https://registry.npmjs.org ``` + ```yarn yarn pub [...name] --registry https://registry.yarnpkg.com ``` + ::: 对于 Yarn v2 及以上版本，你还可以分别针对发布和安装设置不同的镜像： -::: tabs code +:::tabs code + ```yarn # 安装时使用国内镜像 yarn config set npmRegistryServer https://registry.npmmirror.com # 发布时使用官方镜像 yarn config set npmPublishRegistry https://registry.yarnpkg.com ``` -::: -: + ::: +:::: ## 更新插件版本 初始创建的插件版本号为 `1.0.0`。当你修改过插件后，你需要更新版本号才能重新发布。在应用目录运行下面的命令以更新版本号： -::: tabs code +:::tabs code + ```npm npm run bump [...name] -- [-1|-2|-3|-p|-v ] [-r] ``` + ```yarn yarn bump [...name] [-1|-2|-3|-p|-v ] [-r] ``` + ::: - **name:** 要更新的插件列表，不能为空 diff --git a/de-DE/guide/develop/script.md b/de-DE/guide/develop/script.md index 3172bf7c0ec9..f50cdf9faf74 100644 --- a/de-DE/guide/develop/script.md +++ b/de-DE/guide/develop/script.md @@ -44,7 +44,7 @@ Koishi 的命令行工具支持自动重启。当运行 Koishi 的进程崩溃 ## 开发模式 -除了 `start` 以外，模板项目还准备了名为 `dev` 的开发模式启动脚本。在应用目录运行下面的命令行可以启动开发模式： +除了 `start` 以外，模板项目还准备了名为 `dev` 的开发模式启动脚本。在应用目录运行下面的命令行可以以开发模式启动应用： ::: tabs code ```npm @@ -55,18 +55,18 @@ yarn dev ``` ::: -如你所见，`dev` 相当于在 `start` 指令的基础上添加了额外的参数和环境变量。这些参数为我们启用了额外的特性，而环境变量则能影响插件的部分配置。 +如你所见，`dev` 相当于在 `start` 指令的基础上添加了额外的参数和环境变量。这些参数为我们启用了额外的特性，而环境变量则能影响插件的部分行为。 ### TypeScript 支持 -Koishi 工作区原生地支持 TypeScript 开发。上述 `-r esbuild-register` 参数允许我们在运行时直接使用工作区插件的 TypeScript 源代码。 +Koishi 模板项目原生地支持 TypeScript 开发。上述 `-r esbuild-register` 参数允许我们在运行时直接使用工作区插件的 TypeScript 源代码。 -你也可以自行扩展更多的后缀名支持。例如，如果你更喜欢 CoffeeScript，你可以这样修改你的启动脚本为： +你也可以自行扩展更多的后缀名支持。例如，如果你更喜欢 CoffeeScript，你可以这样修改你的开发脚本为： ```json title=package.json { "scripts": { - "start": "koishi start -r coffeescript/register" + "dev": "koishi start -r coffeescript/register" }, "devDependencies": { "coffeescript": "^2.7.0" @@ -82,7 +82,7 @@ Koishi 工作区原生地支持 TypeScript 开发。上述 `-r esbuild-register` ### 模块热替换 -如果你开发着一个巨大的 Koishi 项目，可能光是加载一遍全部插件就需要好几秒了。在这种时候，像前端框架一样支持模块热替换就成了一个很棒的主意。幸运的是，Koishi 也做到了这一点！内置插件 @koishijs/plugin-hmr 实现了插件级别的热替换。每当你修改你的本地文件时，Koishi 就会尝试重载你的插件，并在控制台提醒你。 +如果你开发着一个巨大的 Koishi 项目，可能光是加载一遍全部插件就需要好几秒了。在这种时候，像前端框架一样支持模块热替换就成了一个很棒的主意。幸运的是，Koishi 也做到了这一点！内置插件 @koishijs/plugin-hmr 实现了插件级别的热替换。每当你修改你的本地文件时，Koishi 就会尝试重载你的插件，并在命令行中提醒你。 这里的行为也可以在配置文件中进行定制： diff --git a/de-DE/guide/i18n/index.md b/de-DE/guide/i18n/index.md index 74ad7b96284f..1a043e68a724 100644 --- a/de-DE/guide/i18n/index.md +++ b/de-DE/guide/i18n/index.md @@ -51,7 +51,7 @@ channel.locales = ['en-US'] ### 插值语法 -向 `session.text()` 中传入第二个参数，就可以在模板中使用单花括号插值。花括号中的内容将对应传入列表的索引。 +向 `session.text()` 中传入第二个参数，就可以在模板中使用单花括号插值。花括号 `{}` 中的内容将对应传入列表的索引。 ```ts ctx.i18n.define('zh-CN', { hello: '你好，{0}！' }) @@ -95,22 +95,84 @@ ctx.i18n.define('en-US', { hello: 'Hello, {author.name}!' }) 上述三段代码的实际效果完全相同，可以根据自己的需要进行选择。 +### 使用消息元素 + +你也可以在模板中使用 [消息元素](../basic/element.md) 语法。消息元素的属性同样使用 `{}` 进行插值： + +```ts +ctx.i18n.define('zh-CN', { hello: '你好，！' }) +ctx.i18n.define('en-US', { hello: 'Hello, !' }) +``` + +你也可以使用消息组件，例如使用 `` 组件引用其他翻译，或使用 `` 表示本地化的时间： + +```ts +ctx.i18n.define('zh-CN', { remain: '剩余时间：' }) +ctx.i18n.define('en-US', { remain: 'Time Remain: ' }) +``` + +### 条件和循环 实验性 + +我们为模板提供了一些基本的控制流语法，它参考了 [Svelte](https://svelte.dev/) 的设计 (但并未完整实现)。你可以在模板中通过 `{#if}` 和 `{#each}` 来实现条件和循环。例如，下面的代码将会渲染一个列表： + +```html +{#if list.length === 0} + 列表中没有元素。 +{:else} + {#each list as item} + {item} + {/each} +{/if} +``` + +::: tip +如果要使用这种层面的模板能力，那么你的代码已经不适合使用 `ctx.i18n.define()` 定义了。建议参考 [下一节](./translation.md) 中的做法，将不同语言的模板放入不同的文件中，以方便编辑和管理。 +::: + ## 渲染回退 -### 语言优先级 +一次完整的本地化渲染可能涉及多种不同优先级的语言和渲染路径。当首选语言的首选路径对应的翻译文本不存在时，会依次尝试使用其他翻译，这就是渲染回退。 -默认情况下的渲染优先级依次为： +### 基于语言的回退 +首先需要了解的是基于语言的回退。根据 [IETF 语言标签](https://zh.wikipedia.org/wiki/IETF%E8%AA%9E%E8%A8%80%E6%A8%99%E7%B1%A4) 规范，一个语言名称可以包含由 `-` 分隔的多个部分，例如 `de-DE-bavarian`。用户可以为应用设置 [`config.i18n.locales`](../../api/core/app.md#i18n-locales) 来指定可用的语言列表，这些语言将按照 `-` 分隔符形成一棵字典树，而 Koishi 会按照以下规则进行回退： + +1. 找到目标语言的在字典树中出现的最长前缀对应的节点； +2. 按照用户配置的优先级渲染改节点的子树所包含的语言，并将它们移除； +3. 如果此时仍有未被渲染过的语言，那么回到 1 继续遍历，直到所有语言被遍历完全。 + +例如，如果用户配置的语言列表为 `zh-CN`, `en-US`, `zh-TW`, `en-GB`，则对于不同的目标语言会生成对应的回退序列： + +- 目标语言为 `en`，回退序列为 `en`, `en-US`, `en-GB`, ``, `zh`, `zh-CN`, `zh-TW` +- 目标语言为 `zh-TW`，回退序列为 `zh-TW`, `zh`, `zh-CN`, `en`, `en-US`, `en-GB`, `` +- 目标语言为 `de-DE`，回退序列为 ``, `zh`, `zh-CN`, `zh-TW`, `en`, `en-US`, `en-GB` +- 目标语言为 `en`, `zh-TW`，回退序列为 `en`, `en-US`, `en-GB`, `zh-TW`, `zh`, `zh-CN`, `` +- 目标语言为 `zh-TW`, `en`，回退序列为 `zh-TW`, `en`, `en-US`, `en-GB`, `zh`, `zh-CN`, `` + +请注意，空字符串也被视为合法的语言，其所代表的是「没有指定语言」的情况。在实践中，空语言的使用是非常广泛的，例如当用户使用下面的代码定义指令： + +```ts +ctx.command('echo', '回声') +``` + +此时我们无法推测出「回声」的语言，因此它将会被作为路径 `commands.echo.name` 注册到空语言下。用户可以为其定义其他语言的翻译，但在未命中任何翻译时，它将回退到空语言。 + +### 基于会话的回退 + +实际的本地化渲染通常发生在消息会话中。对于一个会话，我们可以从以下几个维度来确定它的目标语言 (每个维度都可以存在多个目标语言)： + +- 会话语言 (`session.locales`) - 频道语言 (`session.channel.locales`) - 群组语言 (`session.guild.locales`) - 用户语言 (`session.user.locales`) -- 默认语言 (`app.config.i18n.locales`) -- 无语言 (`''`) -- 其他任何语言 -如果一种语言不存在对应的翻译，就会尝试使用下一种语言。如果所有语言均没有找到翻译，则会输出本身传入的渲染路径，同时输出一个警告。 +最终的目标语言将会是上述语言按顺序的并集，再根据前面介绍的规则进行回退渲染。 + +会话语言可以在一些交互场景中被直接感知得到。例如，用户如果在聊天平台中已经设置了语言偏好 (并且聊天平台提供了相应的 API)，则相关的设置可以通过适配器插件提供给会话。又比如，当开发者为一个指令设置了多种语言的别名时，可以为这些别名手动指定语言，当用户调用某一个别名时，Koishi 会按照设定好的语言来回答。 -### 路径回退 +用户语言与频道、群组语言的优先关系可以通过 [`config.i18n.output`](../../api/core/app.md#i18n-output) 来指定。默认情况下频道和群组的语言优先级高于用户语言，但是你可以将其设置为 `prefer-user` 来改变这一行为。 + +### 基于路径的回退 你也可以配置多个路径，将会按照顺序查找翻译，直到找到一个翻译为止。 @@ -127,3 +189,9 @@ session.text(['foo', 'bar']) ```ts session.text(['foo', '']) ``` + +### 用户侧覆写 + +用户可以通过 [locales](../../plugins/console/locales.md) 插件提供本地翻译，且这些翻译的优先级高于插件自身提供的翻译。可以认为，从用户提供的翻译到插件提供的翻译，也是一种回退关系。 + +关于用户侧覆写的更多信息，请参见 [入门 > 深入定制机器人](../../manual/usage/customize.md)。 diff --git a/de-DE/manual/usage/market.md b/de-DE/manual/usage/market.md index b5d5d0166b33..dcfd40dae154 100644 --- a/de-DE/manual/usage/market.md +++ b/de-DE/manual/usage/market.md @@ -1,10 +1,12 @@ -- - - -prev: text: 选择安装方式 link: /zh-CN/manual/starter/ -- - - +--- +prev: + text: Andere Installationsmethoden + link: /de-DE/manual/starter/ +--- -# 安装和配置插件 +# Installation und Konfiguration der Plugins -::: tip +:::tip 本节将介绍「插件市场」「插件配置」和「依赖管理」页面的使用方法。 ::: @@ -19,7 +21,7 @@ Koishi 的一个核心特性是强大的控制台。控制台是一个对用户 本节中我们将以 [echo](../../plugins/common/echo.md) 插件为例来演示插件的安装与配置。echo 插件注册了一个名为 `echo` 的指令，调用此指令可以将输入原样输出给用户。 -## Anerkennung der Konsole +## Über die Konsole 在你成功安装了模板项目或启动器后，控制台将自动打开。 @@ -33,7 +35,7 @@ Koishi 的一个核心特性是强大的控制台。控制台是一个对用户 ## 安装插件 -::: warning +:::warning Koishi 不对非官方插件的安全性做任何保证。请不要随意下载来源不明的插件，因为它们可能导致 Koishi 无法运行，甚至更严重的后果。如果你下载插件后遇到了问题，可以前往用户群或论坛进行反馈。此外，部分插件带有「不安全」标识，安装此类插件将不会受到官方群内的支持。 ::: @@ -57,7 +59,7 @@ Koishi 不会自动启用刚刚安装的插件，你需要手动配置并启用 ## 配置插件 -::: warning +:::warning 在配置插件的过程中，请大家记住这个原则：**如无必要，勿动配置**。Koishi 在设计上兼顾了扩展性和实用性，许多基础功能是以预装插件的形式提供的。前面我们已经用到的「插件市场」和「插件配置」页面本身就分别由预装的 market 插件和 config 插件提供。正是因为所有的预装插件均已配置完善，通常情况下你不需要修改预装插件的配置。随意改动插件配置、删除预装插件都可能导致 Koishi 无法正常运行。 ::: @@ -86,7 +88,7 @@ Koishi 在安装时预先配置了一些分组，而新安装的插件会放置 ### 添加更多插件 -::: tip +:::tip 通常情况下，一个插件只能同时运行一份配置。请参考 [维护多份配置](../recipe/multiple.md) 章节。 ::: @@ -98,7 +100,7 @@ Koishi 在安装时预先配置了一些分组，而新安装的插件会放置 ### 删除插件或分组 -::: warning +:::warning 注意：此操作无法被撤销，如果你想要恢复之前的配置，只能再次手动添加。请谨慎操作。 ::: diff --git a/de-DE/plugins/adapter/wechat-official.md b/de-DE/plugins/adapter/wechat-official.md index a81d935d675f..738c7fa072f5 100644 --- a/de-DE/plugins/adapter/wechat-official.md +++ b/de-DE/plugins/adapter/wechat-official.md @@ -5,7 +5,7 @@ 1. 根据 [注册流程指引](https://kf.qq.com/product/weixinmp.html#hid=87) 注册公众平台。 2. 在微信公众平台登录后，页面左侧展开「设置与开发」，进入「公众号设置」，翻至页面底部，复制 `原始 ID` 填入插件的 account 字段。 3. 页面左侧进入「基本配置」，复制 `开发者ID` 填入插件的 appId 字段，在网页上获取开发者密码填入插件的 secret 字段，设置白名单 IP。 -4. 页面下方启用服务器配置，将机器人的 `selfUrl` 值后连接 `/wechatofficial` (如 `https://example.com/wechatofficial`)，在 URL 一栏中填写；在插件配置和公众平台上填入相同的 Token；在公众平台上生成 EncodingAESKey 并填入插件的 aesKey 字段；三种消息加解密方式均可选择。 +4. 页面下方启用服务器配置，将机器人的 `selfUrl` 值后连接 `/wechat-official` (如 `https://example.com/wechat-official`)，在 URL 一栏中填写；在插件配置和公众平台上填入相同的 Token；在公众平台上生成 EncodingAESKey 并填入插件的 aesKey 字段；三种消息加解密方式均可选择。 5. 如果公众号为企业主体，且通过了微信认证，可在插件配置中启用 customerService。客服接口提供了更宽松的消息回复能力。 参考文档：[https://developers.weixin.qq.com/doc/offiaccount/Basic_Information/Access_Overview.html](https://developers.weixin.qq.com/doc/offiaccount/Basic_Information/Access_Overview.html) diff --git a/en-US/about/contact.md b/en-US/about/contact.md index 0f10f5418892..410495ad1275 100644 --- a/en-US/about/contact.md +++ b/en-US/about/contact.md @@ -1,6 +1,6 @@ # Discussion -如果你在 Koishi 使用中遇到了问题，或者有新奇的点子想与其他人讨论，欢迎参与我们的社区。 +If you have problems when using Koishi, or have new ideas to share to other users, welcome to join our community. ## QQ Groups @@ -18,15 +18,15 @@ This group is for the users who had learned Node.js / TypeScript and interested ## Discord -[加入服务器](https://discord.com/invite/xfxYwmd284) +[Join the Server](https://discord.com/invite/xfxYwmd284) Our Discord server has channels with different features such as Version Releases, Development Discuss and Question Feedback. You can also participate in discussions here. ## Telegram -[加入闲聊群](https://t.me/koishichat) / [加入通知频道](https://t.me/koishichannel) +[Join the Chat Group](https://t.me/koishichat) / [Join the Announcement Channel](https://t.me/koishichannel) -欢迎加入我们的 Telegram 群聊，你可以在这里参与讨论，或者在 Telegram 通知群中接收版本更新通知。 +Welcome to join our Telegram chat group, where you can participate in discussions or receive version update notifications in the announcement channel. ## Forum @@ -34,8 +34,8 @@ Our Discord server has channels with different features such as Version Releases Forum is a special way of discussing. Your issues, ideas, feedback will save forever. And you can have different discussions at the same time.Your questions are more likely to be answered in the forum and can be saved for the benefit of others. -## 企业支持 +## Enterprise Support -QQ：[2953529126](https://qm.qq.com/q/P8eMJkP5yI) / 微信：ilharp +QQ：[2953529126](https://qm.qq.com/q/P8eMJkP5yI) / WeChat：ilharp -我们为企业用户提供专属支持。如果您是企业用户，除了通过上面的方式参与讨论以外，还可以添加客服，获得一对一专属支持。 +We provide exclusive support for enterprise users. In addition to participating in discussions through the above methods, enterprise users can also add customer service to get one-on-one exclusive support. diff --git a/en-US/about/license.md b/en-US/about/license.md index ddfe68ee6e46..3281c40171b8 100644 --- a/en-US/about/license.md +++ b/en-US/about/license.md @@ -4,14 +4,14 @@ The Koishi team is committed to maintaining a good open source ecology. ## License used by Koishi -- Koishi 本体及其核心插件全部使用 MIT 许可证开源 ([仓库链接](https://github.com/koishijs/koishi)) -- 与控制台相关的官方插件均使用 AGPL-3.0 许可证开源 ([仓库链接](https://github.com/koishijs/webui)) - - 根据许可证条款，使用了官方控制台插件的软件必须以相同许可证开源 - - 以服务形式扩展控制台功能的插件不受此限制 +- Koishi itself and its core plugins are all open-sourced under the MIT License ([repository link](https://github.com/koishijs/koishi)). +- Official plugins related to the console are open-sourced under the AGPL-3.0 License ([repository link](https://github.com/koishijs/webui)). + - According to the terms of the license, software that uses official console plugins must be open-sourced under the same license. + - Plugins that extend console functionality in the form of a service are not subject to this restriction. ## License for the official website -- 本文档所依赖的主题使用 MIT 许可证开源 ([仓库链接](https://github.com/koishijs/theme)) -- 本文档仓库使用 CC-BY-SA-4.0 和 AGPL-3.0 许可证开源 ([仓库链接](https://github.com/koishijs/docs)) - - 文档内容以 CC-BY-SA-4.0 许可证开源 (`.vitepress` 目录以外的部分) - - 对原主题库进行的扩展使用 AGPL-3.0 许可证开源 (`.vitepress` 目录中的部分) +- The theme on which this document relies is open-sourced under the MIT License ([repository link](https://github.com/koishijs/theme)). +- The document repository is open-sourced under the CC-BY-SA-4.0 and AGPL-3.0 Licenses ([repository link](https://github.com/koishijs/docs)). + - The content of the document is open-sourced under the CC-BY-SA-4.0 License (parts outside the `.vitepress` directory). + - Extensions to the original theme library are open-sourced under the AGPL-3.0 License (parts in the `.vitepress` directory). diff --git a/en-US/about/releases.md b/en-US/about/releases.md index 5d94f3986d25..5815441956ab 100644 --- a/en-US/about/releases.md +++ b/en-US/about/releases.md @@ -1,15 +1,15 @@ -# 更新计划 +# Updates -## 发布周期 +## Release Cycle -Koishi 目前采用 Cordis 架构，绝大多数功能都以插件的形式提供。这些插件的更新会按需进行，且都遵循 [语义化版本](https://semver.org/lang/zh-CN/) 规范： +Koishi currently adopts the Cordis architecture, with the majority of its functionalities provided in the form of plugins. These plugins are updated as needed and all follow the [Semantic Versioning](https://semver.org/lang/zh-CN/) guidelines: -- 补丁版本 (patch) 只用于修复 bug，不会引入新的功能。 -- 次版本 (minor) 会包含新特性，但不会破坏现有功能。 -- 主版本 (major) 会引入破坏性变更。 +- Patch versions are only used for bug fixes and do not introduce new features. +- Minor versions may include new features but will not break existing functionalities. +- Major versions introduce breaking changes. -在语义化版本的界定上，一切对预期行为的定义，以 Koishi 官方文档为准。 +In the context of semantic versioning, all definitions of expected behavior are based on the official Koishi documentation. -Koishi 本体大约每 1-2 周发布一个新版本。这些版本根据 Koishi 自身的依赖确定是补丁版本还是次版本。目前 Koishi 的主版本是 v4，且没有改动主版本的计划。 +Koishi's updates are released approximately every 1-2 weeks. These versions are classified as either patch or minor versions based on Koishi's own dependencies. The current major version of Koishi is v4, and there are no plans to change the major version at this time. -从 v4 的较低版本升级时，可以参考此 [迁移指南](./upgrade.md)。 +For upgrades from lower versions of v4, you can refer to this [Migration Guide](./upgrade.md). diff --git a/en-US/about/team.md b/en-US/about/team.md index 1485a08db0c2..5988a01e99d9 100644 --- a/en-US/about/team.md +++ b/en-US/about/team.md @@ -1,4 +1,4 @@ -# 认识团队 +# Meet the Team ## Core Members diff --git a/en-US/api/core/app.md b/en-US/api/core/app.md index 8ca9e32abef6..5aaa4eceda66 100644 --- a/en-US/api/core/app.md +++ b/en-US/api/core/app.md @@ -91,13 +91,13 @@ interface DelayOptions { ## 国际化设置 -### options.i18n.locales +### options.i18n.locales {#i18n-locales} - 类型：`string[]` 可用的语言列表。按照回退顺序排列。 -### options.i18n.output +### options.i18n.output {#i18n-output} - 类型：`string` @@ -106,15 +106,6 @@ interface DelayOptions { - `prefer-user`: 优先使用用户语言 - `prefer-channel`: 优先使用频道语言 -## 高级设置 - -### options.maxListeners - -- 类型：`number` -- 默认值：`64` - -每种钩子的最大数量。如果超过这个数量，Koishi 会认定为发生了内存泄漏，将产生一个警告。 - ## 请求设置 ### options.request.proxyAgent diff --git a/en-US/api/service/events.md b/en-US/api/service/events.md index 2a27ed980187..5f6037dbda2c 100644 --- a/en-US/api/service/events.md +++ b/en-US/api/service/events.md @@ -1,4 +1,4 @@ -# 事件系统 (Events) +# Events ::: tip 参见：[开发 > 交互基础 > 事件系统](../../guide/basic/events.md)
参见：[开发 > 模块化 > 生命周期](../../guide/plugin/lifecycle.md) diff --git a/en-US/cookbook/design/disposable.md b/en-US/cookbook/design/disposable.md index ad1f30900e3f..861575153549 100644 --- a/en-US/cookbook/design/disposable.md +++ b/en-US/cookbook/design/disposable.md @@ -1,4 +1,4 @@ -# 可逆的插件系统 +# Disposable Plugin System ::: tip 本文将回答以下问题： diff --git a/en-US/cookbook/index.md b/en-US/cookbook/index.md index c7baea3a563d..2656252d80ae 100644 --- a/en-US/cookbook/index.md +++ b/en-US/cookbook/index.md @@ -1,4 +1,4 @@ -# 进阶指南 +# Advanced Guide 欢迎来到 Koishi 开发文档的进阶篇！在 [开发指南](../guide/index.md) 中，我们已经系统地介绍了 Koishi 的基本用法。而进阶指南则会以专题的形式，深入探讨 Koishi 的设计原理和最佳实践。 diff --git a/en-US/cookbook/practice/testing.md b/en-US/cookbook/practice/testing.md index d27a4e9f1f79..8dd160c93aa0 100644 --- a/en-US/cookbook/practice/testing.md +++ b/en-US/cookbook/practice/testing.md @@ -1,4 +1,4 @@ -# 编写测试 +# Writing Tests 如果你是一位成熟的开发者，你一定知道测试的重要性。比起让机器人真正运行起来交给用户去试错，预先编写好的测试具有许多前者所不具有的优点： diff --git a/en-US/guide/basic/element.md b/en-US/guide/basic/element.md index 9f4d3ade36e1..b495fce5c2b0 100644 --- a/en-US/guide/basic/element.md +++ b/en-US/guide/basic/element.md @@ -4,7 +4,7 @@ 消息元素类似于 HTML 元素，它是组成消息的基本单位。一个元素可以表示具有特定语义的内容，如文本、表情、图片、引用、元信息等。Koishi 会将这些元素转换为平台所支持的格式，以便在不同平台之间发送和接收消息。 -## 基本用法 +## Basic Usage 一个典型的元素包含名称、属性和内容。在 Koishi 中，我们通常使用 JSX 或 API 的方式创建元素。下面是一些例子： @@ -27,13 +27,13 @@ session.send(h('image', { url: 'https://koishi.chat/logo.png' })) 这两种写法各有优劣，不同人可能会有不同的偏好。但无论哪一种写法都表达了同样的意思。 -### 使用 JSX +### Use JSX 学习 JSX 的写法需要你有一定的 HTML 基础 (如果有 React 基础将更好，尽管这不是必需的)。如果你不熟悉 HTML，可以参考 [这篇文档](https://developer.mozilla.org/zh-CN/docs/Glossary/Element)。 如果你已经学习过 HTML 的相关知识，你唯一额外需要了解的事情就是我们使用单花括号 `{}` 进行插值。你可以在单花括号中使用任何 JavaScript 表达式，它们会在运算完成后成为元素的一部分。此外，我们还为消息元素编写了完整的 [语法规范](../../api/message/syntax.md)，供你参考。 -### 使用 API +### Use API 对于更喜欢原生 JavaScript 的人，我们也提供了 API 的方式来创建元素。Koishi 提供一个 `h` 函数，它有着灵活的使用方式： @@ -142,30 +142,30 @@ h.image(buffer, 'image/png') ``` -## 消息组件 实验性 +## Message Component experimental **消息组件 (Component)** 是一种对消息元素的扩展和封装。它允许你创建可重用的定制元素，并在渲染时引入自定义逻辑。例如，`` 组件会将其中的内容作为指令执行，并将执行结果替换该元素： ```html -这是执行结果：echo hello +Execution result: echo hello ``` -这是执行结果：hello +Execution result: hello 如你所见，你可以像使用普通的消息元素一样使用消息组件。唯一的区别是消息组件不由适配器实现，而是由 Koishi 直接处理。与之相对的，某些消息组件只有在特定的会话环境下才能使用 (例如在 `ctx.broadcast()` 中传入 `` 是无意义的，也会抛出错误)。 Koishi 已经内置了一系列消息组件，包括： -- ``：执行指令 +- ``: command execution - ``：等待输入 -- ``：国际化 -- ``：随机选择 +- ``: internationalization +- ``: random selection 你可以在 [这个页面](../../api/message/components.md) 了解每个组件的详细用法和适用范围。 -### 声明消息组件 +### 定义消息组件 一个消息组件本质上是一个函数，它接受三个参数： @@ -195,15 +195,15 @@ session.send(h(Custom)) ``` ::: -### 注册全局组件 +### Register Global Component 上面的写法只能在当前文件中使用，并且必须以大写字母开头。如果想要更自然的写法，并将组件提供给其他插件使用，只需使用 `ctx.component()` 将它注册为一个全局组件： ```ts ctx.component('custom', (attrs, children, session) => { - return '自定义内容' + return 'custom content' }) -// 现在你可以在任何地方使用小写的 了 +// Now use can use the lowercased ! session.send() ``` diff --git a/en-US/guide/develop/publish.md b/en-US/guide/develop/publish.md index 29be433603d8..9df224323eb2 100644 --- a/en-US/guide/develop/publish.md +++ b/en-US/guide/develop/publish.md @@ -1,14 +1,15 @@ # Publishing Plugins -Your plugin should be published onto npm before being available to Koishi users. But there are extra requirements for a valid plugin to be listed in the [marketplace](../../market/). +Your plugin should be published onto npm before being available to Koishi users. +But there are extra requirements for a valid plugin to be listed in the [marketplace](../../market/). -::: tip -These commands are should be run in the [workspace root](./config.md#应用目录). +:::tip +本节中介绍的命令行都需要在 [应用目录](./config.md#应用目录) 下运行。 ::: ## Prerequisite -1. Let's start with the `package.json` file in your workspace directory.This file is crucial as it has all the meta information for publishing your plugin. +首先让我们关注工作区目录中的 `package.json` 文件。This file is crucial as it has all the meta information for publishing your plugin. ```diff{6} root @@ -21,8 +22,8 @@ root └── package.json # not this ``` -::: tip -There is a `package.json` file in your workspace root and in each plugin folder, please make sure the file opened is the one in the corresponding plugin folder. +:::tip +请注意 `package.json` 文件不是唯一的，它在应用目录和每个插件目录都会存在。please make sure the file opened is the one in the corresponding plugin folder. ::: 2. The following structure is an example of the above file: @@ -35,34 +36,34 @@ There is a `package.json` file in your workspace root and in each plugin folder, } ``` -When publishing your plugin, the property `name` and `version` are required. We can see a package name prefix `koishi-plugin-`. The prefix is not only omitted in the marketplace to make it easier for users to search and install the plugin, but also prevents conflicts with other package names on npm. +其中最重要的属性有两个：`name` 是要发布的包名，`version` 是包的版本号。这里的包名相比实际在插件市场中看到的插件名多了一个 `koishi-plugin-` 的前缀，这样既方便了用户安装和配置，又防止了污染命名空间。 -::: tip -Each package name and updated version number is unique.If you use a duplicate name or number, will get an error message and have to change them. +:::tip +请注意：包名和版本号都具有唯一性。If you use a duplicate name or number, will get an error message and have to change them. ::: ## More information -The `package.json` is more than just name and version of the plugin. It also includes dependencies, description, contributors, license, keywords, and other information. These are part of the plugin too, so whenever you change them, it is important that you update a version first and then publish again. +除了包名和版本号以外，`package.json` 还包括了插件的依赖、描述、贡献者、许可证、关键词等更多信息。These are part of the plugin too, so whenever you change them, 但请别忘了，这些内容也是插件的一部分，修改完成后别忘了 [更新版本](#更新插件版本) 并 [再次发布](#发布插件)。 ### Requirements -::: tip -You may skip this section, if your plugin created using the boilerplate. +:::tip +使用模板项目创建的插件一定是符合要求的，因此你可以跳过这一节。 ::: -The `package.json` in your plugin should meet the requirements below to appear in the marketplace: +要想显示在插件市场中，插件的 `package.json` 需要满足以下基本要求： -- [`name`](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#name) should match one of these formats: +- [`name`](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#name) 必须符合以下格式之一： - koishi-plugin-\* - @bar/koishi-plugin-\* - @koishijs/plugin-\* (Official) - \* is a string of digits, lowercase letters and dashes -- [`name`](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#name) is unique -- The [`version`](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#version) be in the form `x. x. x` and should follow [semantic versioning guidelines](https://semver.org/lang/zh-CN/) (usually from `1.0.0`) -- [`peerDependencies`](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#peerdependencies) must include `koishi` -- Do not set [`private`](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#private) to `true`, otherwise your plugin cannot be published to npm -- Avoid [deprecating](https://docs.npmjs.com/deprecating-and-undeprecating-packages-or-package-versions) your plugin, unless you have a good reason to do so. For example, if you want to republish the plugin with a different name, you can use it to hide the old plugin on the marketplace. +- [`name`](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#name) 不能与已发布的插件重复或相似 +- [`version`](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#version) 应当符合 [语义化版本](https://semver.org/lang/zh-CN/) (通常从 `1.0.0` 开始) +- [`peerDependencies`](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#peerdependencies) 必须包含 `koishi` +- 不能声明 [`private`](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#private) 为 `true` (否则你的插件无法发布) +- 最新版本不能被 [弃用](https://docs.npmjs.com/deprecating-and-undeprecating-packages-or-package-versions) (一种常见的情况是：你已经发布了某个插件，又希望更换一个名字重新发布，此时你可以通过弃用的方式让旧的名字不显示在插件市场中) Example: @@ -78,38 +79,38 @@ Example: ### The `package.json` file -To make more information available to Koishi users, you could add more comprehensive fields in the `package.json` of your plugin. +除去上面的基本要求外，`package.json` 中还有一些字段能帮助显示插件的相关信息。 ```json title=package.json { "name": "koishi-plugin-example", "version": "1.0.0", - "contributors": [ + "contributors": [ // 贡献者 "Alice ", "Bob " ], - "license": "MIT", - "homepage": "https://example.com", - "repository": { + "license": "MIT", // 许可证 + "homepage": "https://example.com", // 主页 + "repository": { // 源码仓库 "type": "git", "url": "git+https://github.com/alice/koishi-plugin-example.git" }, - "keywords": ["example"], + "keywords": ["example"], // 关键词 "peerDependencies": { "koishi": "^4.3.2" } } ``` -- **contributors:** plugin maintainers, should be an array. The elements usually follow the format `Name `. -- **license:** license under your plugins You can find detailed information about [various licenses here](https://choosealicense.com/licenses/). -- **homepage:** homepage for your plugin, which can be a URL (e.g. your GitHub project address). -- **repository:** source code repository of the plugin, which should be an object. The `type` field specifies the type of repository, and the `url` field specifies the repository address. -- **keywords:** keywords for the plugin, which should be an array of strings. They are used for the search function in the plug-in market. +- **contributors:** 插件维护者，应该是一个数组，其中的元素通常使用 `名字 <邮箱>` 的格式 +- **license:** 插件许可证，你可以在 [这里](https://choosealicense.com/licenses/) 了解各种许可证的详细信息 +- **homepage:** 插件主页，可以是一个网址 (比如你的 GitHub 项目地址) +- **repository:** 插件源码仓库，应该是一个对象，其中 `type` 字段指定仓库类型，`url` 字段指定仓库地址 +- **keywords:** 插件关键词，应该是一个字符串数组，会用于插件市场中的搜索功能 ### Koishi fields -We can also use the `koishi` field to specify Koishi related information +除此以外，我们还提供了一个额外的 `koishi` 字段，用于指定与 Koishi 相关的信息。 ```json title=package.json { @@ -133,42 +134,45 @@ We can also use the `koishi` field to specify Koishi related information } ``` -- **description:** This refers to the description of the plugin, which should be an object. The keys represent the language names, and the values are the descriptions in the corresponding languages. -- **service:** This pertains to the service-related information of the plugin, which includes the following attributes: - - **required:** necessary services, represented as an array of service names. - - **optional:** optional services, also represented as an array of service names. - - **implements:** services that your plugin implements, represented as an array of service names. -- **locales:** This refers to the languages supported by the plugin, represented as an array of language names. -- **preview:** If set to `true`, this allows the plugin to be displayed as “under development”. -- **hidden:** If set to `true`, this prevents the plugin from being displayed in the marketplace (you usually don’t need to do this). - -::: tip -Additionally, there are some fields related to the deployment process of [Koishi Online](../../cookbook/practice/online.md) (such as `browser`, `exports`, etc.). Since they do not affect the mainline development, you can learn about them later. +- **description:** 插件描述，应该是一个对象，其中的键代表语言名，值是对应语言下的描述 +- **service:** 插件的服务相关信息，具体包含下列属性： + - **required:** 必需的服务，应该是一个服务名构成的数组 + - **optional:** 可选的服务，应该是一个服务名构成的数组 + - **implements:** 实现的服务，应该是一个服务名构成的数组 +- **locales:** 插件支持的语言，应该是一个语言名构成的数组 +- **preview:** 配置为 `true` 可以让插件显示为「开发中」状态 +- **hidden:** 配置为 `true` 可以让插件市场中不显示该插件 (通常情况下你不需要这么做) + +:::tip +此外，还有一些字段与 [Koishi Online](../../cookbook/practice/online.md) 的部署流程相关 (如 `browser`, `exports` 等)。Since they do not affect the mainline development, you can learn about them later. ::: -## Publish your plugin +## Publishing Plugins -Congratulations! It's time to publish your plugin, after editing the file above and [build source](./workspace.md#构建源代码). +编辑完上面的清单文件并 [构建源代码](./workspace.md#构建源代码) 后，你就可以公开发布你的插件了。 + +:::tabs code -::: tabs code ```npm npm run pub [...name] ``` + ```yarn yarn pub [...name] ``` + ::: -- **name:** list of plugins to be published, all by default ( `name` is your plugin directory name) +- **name:** 要发布的插件列表，缺省时表示全部 (此处 `name` 不包含 `koishi-plugin-` 前缀，而是你的工作区目录名) This will be released of all plugins that have changed version numbers. -::: tip -It will take some time for the marketplace to include your plugin (usually within 15 minutes), sit back and relax. +:::tip +It takes some time for the plugin to be successfully published to the plugin marketplace (usually within 15 minutes). Please be patient. ::: -::::tip -If you are in China and have configured a mirror, you may encounter the following error hint: +:::: tip +如果你配置了国内镜像，你可能会遇到以下的错误提示： ```text No token found and can't prompt for login when running with --non-interactive. @@ -176,52 +180,59 @@ No token found and can't prompt for login when running with --non-interactive. 此时你需要在发布时使用官方镜像，具体操作如下： -::: tabs code +:::tabs code + ```npm npm run pub [...name] -- --registry https://registry.npmjs.org ``` + ```yarn yarn pub [...name] --registry https://registry.yarnpkg.com ``` + ::: 对于 Yarn v2 及以上版本，你还可以分别针对发布和安装设置不同的镜像： -::: tabs code +:::tabs code + ```yarn # 安装时使用国内镜像 yarn config set npmRegistryServer https://registry.npmmirror.com # 发布时使用官方镜像 yarn config set npmPublishRegistry https://registry.yarnpkg.com ``` -::: -: + ::: +:::: ## Updating version -Version default starts from `1.0.0`. Its number needs to be updated before releasing changes. Run the command in the workspace root to update that: +初始创建的插件版本号为 `1.0.0`。Its number needs to be updated before releasing changes. Run the command in the workspace root to update that: + +:::tabs code -::: tabs code ```npm npm run bump [...name] -- [-1|-2|-3|-p|-v ] [-r] ``` + ```yarn yarn bump [...name] [-1|-2|-3|-p|-v ] [-r] ``` + ::: -- **name: ** Mandatory field. List of plugins. -- **-1, --major:** To the next major version, e.g. `3.1.4` -> `4.0.0`. -- **-2, --minor:** To the next minor version, e.g. `3.1.4` -> `3.2.0`. -- **-3, --patch:** To the next patch version, e.g. `3.1.4` -> `3.1.5` . -- **-p, --prereelease:** to next preview version: - - To `beta.0` if the release is `alpha.x` - - To `rc.0` if the release is `beta.x` - - Remove the prerelease section if the release is `rc.x` - - Otherwise, to the next major version of `alpha.0` -- **-v, --version:** set specific version +- **name:** 要更新的插件列表，不能为空 +- **-1, --major:** 跳到下一个大版本，例如 `3.1.4` -> `4.0.0` +- **-2, --minor:** 跳到下一个中版本，例如 `3.1.4` -> `3.2.0` +- **-3, --patch:** 跳到下一个小版本，例如 `3.1.4` -> `3.1.5` +- **-p, --prerelease:** 跳到下一个预览版本，具体行为如下 + - 如果当前版本是 `alpha.x`，则跳到 `beta.0` + - 如果当前版本是 `beta.x`，则跳到 `rc.0` + - 如果当前版本是 `rc.x`，则移除 prerelease 部分 + - 其他情况下，跳到下一个大版本的 `alpha.0` +- **-v, --version:** 设置具体的版本号 - **-r, --recursive:** 递归更新依赖版本 - Default: incremented by the last of the release version number -When updating the version of a plug-in, the versions of dependencies that rely on this plug-in will also be upgraded to ensure consistency in the workspace.Moreover, if you wish for the versions of plug-ins that depend on this plug-in to be updated in sync, you can append the `-r, --recursive` option. +When updating the version of a plug-in, the versions of dependencies that rely on this plug-in will also be upgraded to ensure consistency in the workspace.进一步，如果你希望更新了依赖版本的插件也同时更新自身的版本，那么可以附加 `-r, --recursive` 选项。 diff --git a/en-US/guide/develop/script.md b/en-US/guide/develop/script.md index 153f98f5335a..328e13119fc3 100644 --- a/en-US/guide/develop/script.md +++ b/en-US/guide/develop/script.md @@ -1,4 +1,4 @@ -# Bootstrap Script +# Launch Script There is also a set of command line tools that provided by Koishi to boot the application quickly by reading the configuration file. @@ -8,7 +8,7 @@ These commands are should be run in the [workspace root](./config.md#应用目 ## General Usage -我们通常使用 **启动脚本** 来启动 Koishi 应用。打开应用目录下的 `package.json` 文件： +We usually use a **bootstrap script** to start a Koishi application. Open the `package.json` file in the workspace root: ```json title=package.json { @@ -19,7 +19,7 @@ These commands are should be run in the [workspace root](./config.md#应用目 } ``` -在应用目录运行下面的命令行以启动 Koishi 应用： +Run the following command line in the workspace root to start the Koishi application: ::: tabs code ```npm @@ -30,21 +30,21 @@ yarn start ``` ::: -在本节的后续部分，我们会介绍上述启动脚本的更多参数。无论你做何改动，你都可以使用上面的命令行来快速启动。这也是启动脚本的意义所在。 +In the subsequent parts of this section, we will introduce more options of the above launch script. No matter what changes you make, you can use the above command line to start. This is also the significance of the boostrap script. -### 启动参数 +### Command Line Options -启动脚本支持 Node.js 的 [命令行参数](https://nodejs.org/api/cli.html)。例如，上面的 `-r` 对应于 `--require`，它将允许你加载 `.ts` 和 `.yml` 后缀的文件。 +The launch script supports Node.js's [command line options](https://nodejs.org/api/cli.html). For example, the `-r` above corresponds to `--require`, which allows you to load files with `.ts` and `.yml` extensions. -除了 Node.js 的命令行参数，Koishi 还提供了一些额外的参数。我们将在下面逐一介绍。 +In addition to Node.js's command line options, Koishi also provides some additional options. We will introduce each of them below. -### 自动重启 +### Auto Restart -Koishi 的命令行工具支持自动重启。当运行 Koishi 的进程崩溃时，如果 Koishi 已经启动成功，则监视进程将自动重新启动一个新的进程。 +Koishi's command line tool supports auto-restart. When the process running Koishi crashes, if Koishi has already started successfully, the surveillance process will automatically restart a new process. -## 开发模式 +## Development Mode -除了 `start` 以外，模板项目还准备了名为 `dev` 的开发模式启动脚本。在应用目录运行下面的命令行可以启动开发模式： +In addition to `start`, the template project also prepares a launch script for development mode named `dev`. Running the following command line in the workspace root can start the application in development mode: ::: tabs code ```npm @@ -55,18 +55,18 @@ yarn dev ``` ::: -如你所见，`dev` 相当于在 `start` 指令的基础上添加了额外的参数和环境变量。这些参数为我们启用了额外的特性，而环境变量则能影响插件的部分配置。 +As you can see, `dev` is equivalent to adding additional options and environment variables on the basis of the `start` command. These options enable us to use additional features, while the environment variables can affect some behaviors of the plugins. -### TypeScript 支持 +### TypeScript Support -Koishi 工作区原生地支持 TypeScript 开发。上述 `-r esbuild-register` 参数允许我们在运行时直接使用工作区插件的 TypeScript 源代码。 +The Koishi template project provides built-in support for TypeScript development. The `-r esbuild-register` option mentioned above allows us to directly use the TypeScript source code of workspace plugins at runtime. -你也可以自行扩展更多的后缀名支持。例如，如果你更喜欢 CoffeeScript，你可以这样修改你的启动脚本为： +You can also add support for more extensions on your own. For example, if you prefer CoffeeScript, you can modify your development script like this: ```json title=package.json { "scripts": { - "start": "koishi start -r coffeescript/register" + "dev": "koishi start -r coffeescript/register" }, "devDependencies": { "coffeescript": "^2.7.0" @@ -74,17 +74,17 @@ Koishi 工作区原生地支持 TypeScript 开发。上述 `-r esbuild-register` } ``` -这样你就可以使用 CoffeeScript 编写你的插件源代码 (当然你还得自行处理构建逻辑)，甚至连配置文件都可以使用 `koishi.coffee` 书写了。 +This way, you can use CoffeeScript to write your plugin source code (of course, you still need to handle the build logic yourself), and you can even write the configuration file in `koishi.coffee`. ::: danger -我们并不推荐使用高级语言来编写配置文件，因为动态的配置无法支持环境变量、配置热重载和插件市场等特性。大部分情况下我们建议仅将 `-r` 用于开发目的。 +We do not recommend using advanced languages to write configuration files, as dynamic configurations do not support features like environment variables, configuration hot reloading, and plugin marketplace. In most cases, we suggest using `-r` only for development purposes. ::: -### 模块热替换 +### Hot Module Replacement -如果你开发着一个巨大的 Koishi 项目，可能光是加载一遍全部插件就需要好几秒了。在这种时候，像前端框架一样支持模块热替换就成了一个很棒的主意。幸运的是，Koishi 也做到了这一点！内置插件 @koishijs/plugin-hmr 实现了插件级别的热替换。每当你修改你的本地文件时，Koishi 就会尝试重载你的插件，并在控制台提醒你。 +If you are developing a large Koishi project, it might take several seconds just to load all plugins. At times like this, supporting hot module replacement like front-end frameworks becomes a great idea. Fortunately, Koishi also supports this! The built-in plugin @koishijs/plugin-hmr implements plugin-level hot replacement. Whenever you modify your local files, Koishi will try to reload your plugin and remind you in the terminal. -这里的行为也可以在配置文件中进行定制： +The behavior here can also be customized in the configuration file: ```yaml title=koishi.yml plugins: @@ -92,19 +92,19 @@ plugins: $if: env.NODE_ENV === 'development' hmr: root: '.' - # 要忽略的文件列表，支持 glob patterns + # List of files to ignore, supports glob patterns ignore: - some-file ``` ::: tip -由于部分 Linux 系统有着 8192 个文件的监听数量限制，你可能会发现运行 `yarn dev` 后出现了如下的报错： +Due to the file watcher limit of 8192 on some Linux systems, you may encounter the following error after running `yarn dev`: ```text NOSPC: System limit for number of file watchers reached ``` -此时你可以使用下面的命令来增加监听数量限制： +In this case, you can use the following command to increase the limit of the number of file watchers: ```sh echo fs.inotify.max_user_watches=524288 | @@ -112,5 +112,5 @@ sudo tee -a /etc/sysctl.conf && sudo sysctl -p ``` -另一种方案是只监听部分子路径，例如将 `root` 改为 `external/foo` (其中 `foo` 是你正在开发的插件目录，参见下一节的工作区指南)，这将忽略其他目录下的变化，并依然对你的插件进行热重载。当你同时开发多个插件时，你也可以将 `root` 改成一个数组来使用。 +Another solution is to only monitor certain subpaths, such as changing `root` to `external/foo` (where `foo` is the directory of the plugin you are developing, see the next section's workspace guide), which will ignore changes in other directories while still hot reloading your plugin. When you are developing multiple plugins at the same time, you can also change `root` to an array for use. ::: diff --git a/en-US/guide/develop/workspace.md b/en-US/guide/develop/workspace.md index 6e1a7d5d938a..8021d0795bb2 100644 --- a/en-US/guide/develop/workspace.md +++ b/en-US/guide/develop/workspace.md @@ -1,14 +1,14 @@ # Workspace Development -Koishi 的核心是插件系统，绝大部分 Koishi 功能都可以通过插件实现。本章节将介绍如何使用模板项目开发和构建自己的 Koishi 插件。 +The core of Koishi is its plugin system, with the vast majority of Koishi's functionalities being implementable through plugins. This chapter will introduce how to develop and build your own Koishi plugins using the template project. ::: tip These commands are should be run in the [workspace root](./config.md#应用目录). ::: -## 创建新插件 +## Create a New Plugin -在应用目录运行下面的命令以创建一个新的插件工作区： +Run the following command in the workspace root to create a new plugin workspace: ::: tabs code ```npm @@ -19,12 +19,12 @@ yarn setup [name] [-c] [-m] [-G] ``` ::: -- **name:** 插件的包名，缺省时将进行提问 -- **-c, --console:** 创建一个带控制台扩展的插件 -- **-m, --monorepo:** 创建 monorepo 的插件 -- **-G, --no-git:** 跳过 git 初始化 +- **name**: The package name of the plugin, will be prompted if omitted. +- **-c, --console:** Create a plugin with console extension. +- **-m, --monorepo:** Create monorepo plugin. +- **-G, --no-git:** Skip git initialization. -我们假设你创建了一个叫 `example` 的插件。那么，你将看到下面的目录结构： +Assuming you created a plugin named `example`, you will see the following directory structure: ```diff{3-6} root @@ -37,7 +37,7 @@ root └── package.json ``` -打开 `index.ts` 文件，并修改其中的代码： +Open the `index.ts` file and modify its code: ```ts{6-11} import { Context } from 'koishi' @@ -45,27 +45,27 @@ import { Context } from 'koishi' export const name = 'example' export function apply(ctx: Context) { - // 如果收到“天王盖地虎”，就回应“宝塔镇河妖” + // When receiving "Hello", respond with "World" ctx.on('message', (session) => { - if (session.content === '天王盖地虎') { - session.send('宝塔镇河妖') + if (session.content === 'Hello') { + session.send('World') } }) } ``` -以 [开发模式](./script.md#开发模式) 重新运行你的项目，点击右上角的「添加插件」按钮，选择你刚才创建的插件名称，你会立即在网页控制台的配置界面中看到 `example` 插件。只需点击启用，你就可以实现与机器人的对话了： +Rerun your project in [Development Mode](./script.md#开发模式), click on the 'Add Plugin' button at the top right, select the name of the plugin you just created, and you will immediately see the `example` plugin in the configuration interface of the web console. Just click to enable it, and you can interact with the bot: -天王盖地虎 -宝塔镇河妖 +Hello +World -### 创建私域插件 +### Create a Scoped Plugin -如果你发现想要创建的插件名称已经被占用了，除了重新想名字或在后面加上数字之外，你还可以改为创建私域插件。私域插件使用你自己的 [npm 用户名](./setup.md#注册-npm) 作为包名前缀，因此不用担心与其他人的插件冲突。 +If you find that the plugin name you want to create is already taken, in addition to thinking of a new name or adding numbers to it, you can opt to create a scoped plugin. Scoped plugins use your own [npm username](./setup.md#注册-npm) as a prefix for the package name, so there's no need to worry about conflicts with other people's plugins. -假设你的 npm 用户名是 `alice`，那么你可以使用下面的命令创建一个私域插件工作区： +Suppose your npm username is `alice`, then you can use the following command to create a scoped plugin workspace: ::: tabs code ```npm @@ -76,7 +76,7 @@ yarn setup @alice/example ``` ::: -此外，你还需要额外修改 `tsconfig.json` 文件。打开这个文件，你将看到下面的内容： +In addition, you will need to modify the `tsconfig.json` file. Open this file, and you will see the following content: ```json {6} { @@ -91,11 +91,11 @@ yarn setup @alice/example } ``` -找到高亮的一行代码，将其复制一份，并将 `@scope` 替换为你的 npm 用户名，然后将复制的这一行代码前面的注释符号去掉。 +Find the highlighted line of code, copy it, replace `@scope` with your npm username, and then remove the comment symbol in front of the copied line. -## 构建源代码 +## Build Source Code -上面的插件暂时还只能在开发模式下运行。如果想要在生产模式下使用或发布到插件市场，你需要构建你的源代码。在应用目录运行下面的命令： +The plugin mentioned above can currently only run in development mode. If you want to use it in production mode or publish it to the plugin marketplace, you need to build your source code. Run the following command in the workspace root: ::: tabs code ```npm @@ -106,16 +106,16 @@ yarn build [...name] ``` ::: -- **name:** 要构建的插件列表，缺省时表示全部插件 +- **name:** list of plugins to build, default to all plugins -还是以上面的插件 `example` 为例： +Taking the `example` plugin as an example: -- 后端代码将输出到 `external/example/lib` 目录 -- 前端代码将输出到 `external/example/dist` 目录 (如果存在) +- Backend code will be output to the `external/example/lib` directory. +- Frontend code will be output to the `external/example/dist` directory (if it exists). -## 添加依赖 +## Add Dependencies -插件创建时，`package.json` 中已经包含了一些必要的依赖。如果你需要添加其他依赖，可以使用下面的命令： +When creating a plugin, `package.json` already includes some necessary dependencies. If you need to add other dependencies, you can use the following command: ::: tabs code ```npm @@ -126,14 +126,14 @@ yarn workspace koishi-plugin-[name] add [...deps] ``` ::: -- **name:** 你的插件名称 -- **deps:** 要添加的依赖列表 +- **name:** your plugin name +- **deps:** list of dependencies to add -如果要添加的是 `devDependencies` 或者 `peerDependencies`，你也需要在命令后面加上 `-D` 或 `-P` 参数。关于服务类插件的依赖声明，请参考 [后续章节](../plugin/service.md#关于-peerdependencies)。 +If you are adding `devDependencies` or `peerDependencies`, you also need to add `-D` or `-P` parameters to the command. For dependencies declaration of service plugins, please refer to [subsequent chapter](../plugin/service.md#关于-peerdependencies). -## 更新依赖版本 +## Upgrade Dependencies -尽管 npm 和 yarn 等包管理器都提供了依赖更新功能，但它们对工作区开发的支持都不是很好。因此，我们也提供了一个简单的命令用于批量更新依赖版本。 +Although package managers like npm and yarn provide dependency upgrade features, their support for workspace development is not very good. Therefore, we also provide a simple command for batch upgrading dependencies. ::: tabs code ```npm @@ -144,23 +144,23 @@ yarn dep ``` ::: -这将按照每个 `package.json` 中声明的依赖版本进行更新。举个例子，如果某个依赖的版本是 `^1.1.4`，而这个依赖之后发布了新版本 `1.2.3` 和 `2.3.3`，那么运行该指令后，依赖的版本将会被更新为 `^1.2.3`。 +This will update according to the dependency versions declared in each `package.json`. For example, if the version of a dependency is `^1.1.4`, and this dependency later releases new versions `1.2.3` and `2.3.3`, then after running this command, the version of the dependency will be updated to `^1.2.3`. -## 二次开发 +## Secondary Development ::: tip -阅读本节前请确保你已经完成 [版本控制](./setup.md#版本控制) 中的全部准备工作。 +Please make sure you have completed all the preparations in [Version Control](./setup.md#版本控制) before reading this section. ::: ::: tip -如果你想要贡献原始仓库，在开始执行下面的操作之前，请确保你对要开发的仓库有写入权限。如果没有，你应当先创建属于自己的 fork，然后将下面的仓库名称替换为你的 fork 仓库名称。举个例子，假如你的 GitHub 用户名是 `alice`，那么下面你使用的仓库名称应当是 `alice/koishi-plugin-forward` 而不是 `koishijs/koishi-plugin-forward`。 +If you want to contribute to the original repository, before starting the following operations, please make sure you have write permission to the repository you are developing. If not, you should first create your own fork and then replace the repository name below with the name of your fork. For example, if your GitHub username is `alice`, then the repository name you use below should be `alice/koishi-plugin-forward` instead of `koishijs/koishi-plugin-forward`. ::: -二次开发是指调试或修改其他仓库中的插件。这种情况下，你需要先将对应的仓库克隆到本地，然后在本地进行调试和修改。 +Secondary development refers to debugging or modifying plugins in other repositories. In this case, you need to first clone the corresponding repository to your local environment and then carry out debugging and modifications. -### 开发插件 +### Develop Plugins -其他人创建的工作区插件可以直接克隆到你的 `external` 目录下。例如，你可以使用下面的命令将 `koishi-plugin-forward` 插件克隆到本地： +Plugins created in other people's workspaces can be directly cloned to your `external` directory. For example, you can use the following command to clone the `koishi-plugin-forward` plugin to your local environment: ::: tabs code ```npm @@ -171,9 +171,9 @@ yarn clone koishijs/koishi-plugin-forward ``` ::: -### 开发 Koishi +### Develop Koishi -工作区不仅可以用于插件的二次开发，还可以用于开发 Koishi 本身。只需使用下面的命令将 Koishi 仓库克隆到本地，并完成构建： +Workspaces can be used not only for secondary development of plugins but also for developing Koishi itself. Simply use the following commands to clone the Koishi repository to your local environment and complete the build: ::: tabs code ```npm @@ -186,6 +186,6 @@ yarn workspace @root/koishi build ``` ::: -通常来说，非插件仓库在克隆下来之后还需经过路径配置才可以正常使用。不过不同担心，模板项目支持已经内置了 Koishi 生态中的几个核心仓库 ([koishi](https://github.com/koishijs/koishi), [satori](https://github.com/satorijs/satori), [minato](https://github.com/shigma/minato)) 的路径配置。 +Generally, non-plugin repositories need to go through path configuration after being cloned in order to be used normally. However, don't worry, the template project support has already built-in path configurations for several core repositories in the Koishi ecosystem ([koishi](https://github.com/koishijs/koishi), [satori](https://github.com/satorijs/satori), [minato](https://github.com/shigma/minato)). -完成上述操作后，现在你的 `yarn dev` 已经能直接使用 Koishi 的 TypeScript 源码了！ +After completing the above operations, your `yarn dev` can now directly use the TypeScript source code of Koishi! diff --git a/en-US/guide/i18n/index.md b/en-US/guide/i18n/index.md index 9ed7c46b30f3..65323e0c5aa7 100644 --- a/en-US/guide/i18n/index.md +++ b/en-US/guide/i18n/index.md @@ -51,7 +51,7 @@ channel.locales = ['en-US'] ### 插值语法 -向 `session.text()` 中传入第二个参数，就可以在模板中使用单花括号插值。花括号中的内容将对应传入列表的索引。 +向 `session.text()` 中传入第二个参数，就可以在模板中使用单花括号插值。花括号 `{}` 中的内容将对应传入列表的索引。 ```ts ctx.i18n.define('zh-CN', { hello: '你好，{0}！' }) @@ -95,22 +95,84 @@ ctx.i18n.define('en-US', { hello: 'Hello, {author.name}!' }) 上述三段代码的实际效果完全相同，可以根据自己的需要进行选择。 +### 使用消息元素 + +你也可以在模板中使用 [消息元素](../basic/element.md) 语法。消息元素的属性同样使用 `{}` 进行插值： + +```ts +ctx.i18n.define('zh-CN', { hello: '你好，！' }) +ctx.i18n.define('en-US', { hello: 'Hello, !' }) +``` + +你也可以使用消息组件，例如使用 `` 组件引用其他翻译，或使用 `` 表示本地化的时间： + +```ts +ctx.i18n.define('zh-CN', { remain: '剩余时间：' }) +ctx.i18n.define('en-US', { remain: 'Time Remain: ' }) +``` + +### 条件和循环 实验性 + +我们为模板提供了一些基本的控制流语法，它参考了 [Svelte](https://svelte.dev/) 的设计 (但并未完整实现)。你可以在模板中通过 `{#if}` 和 `{#each}` 来实现条件和循环。例如，下面的代码将会渲染一个列表： + +```html +{#if list.length === 0} + 列表中没有元素。 +{:else} + {#each list as item} + {item} + {/each} +{/if} +``` + +::: tip +如果要使用这种层面的模板能力，那么你的代码已经不适合使用 `ctx.i18n.define()` 定义了。建议参考 [下一节](./translation.md) 中的做法，将不同语言的模板放入不同的文件中，以方便编辑和管理。 +::: + ## 渲染回退 -### 语言优先级 +一次完整的本地化渲染可能涉及多种不同优先级的语言和渲染路径。当首选语言的首选路径对应的翻译文本不存在时，会依次尝试使用其他翻译，这就是渲染回退。 -默认情况下的渲染优先级依次为： +### 基于语言的回退 +首先需要了解的是基于语言的回退。根据 [IETF 语言标签](https://zh.wikipedia.org/wiki/IETF%E8%AA%9E%E8%A8%80%E6%A8%99%E7%B1%A4) 规范，一个语言名称可以包含由 `-` 分隔的多个部分，例如 `de-DE-bavarian`。用户可以为应用设置 [`config.i18n.locales`](../../api/core/app.md#i18n-locales) 来指定可用的语言列表，这些语言将按照 `-` 分隔符形成一棵字典树，而 Koishi 会按照以下规则进行回退： + +1. 找到目标语言的在字典树中出现的最长前缀对应的节点； +2. 按照用户配置的优先级渲染改节点的子树所包含的语言，并将它们移除； +3. 如果此时仍有未被渲染过的语言，那么回到 1 继续遍历，直到所有语言被遍历完全。 + +例如，如果用户配置的语言列表为 `zh-CN`, `en-US`, `zh-TW`, `en-GB`，则对于不同的目标语言会生成对应的回退序列： + +- 目标语言为 `en`，回退序列为 `en`, `en-US`, `en-GB`, ``, `zh`, `zh-CN`, `zh-TW` +- 目标语言为 `zh-TW`，回退序列为 `zh-TW`, `zh`, `zh-CN`, `en`, `en-US`, `en-GB`, `` +- 目标语言为 `de-DE`，回退序列为 ``, `zh`, `zh-CN`, `zh-TW`, `en`, `en-US`, `en-GB` +- 目标语言为 `en`, `zh-TW`，回退序列为 `en`, `en-US`, `en-GB`, `zh-TW`, `zh`, `zh-CN`, `` +- 目标语言为 `zh-TW`, `en`，回退序列为 `zh-TW`, `en`, `en-US`, `en-GB`, `zh`, `zh-CN`, `` + +请注意，空字符串也被视为合法的语言，其所代表的是「没有指定语言」的情况。在实践中，空语言的使用是非常广泛的，例如当用户使用下面的代码定义指令： + +```ts +ctx.command('echo', '回声') +``` + +此时我们无法推测出「回声」的语言，因此它将会被作为路径 `commands.echo.name` 注册到空语言下。用户可以为其定义其他语言的翻译，但在未命中任何翻译时，它将回退到空语言。 + +### 基于会话的回退 + +实际的本地化渲染通常发生在消息会话中。对于一个会话，我们可以从以下几个维度来确定它的目标语言 (每个维度都可以存在多个目标语言)： + +- 会话语言 (`session.locales`) - 频道语言 (`session.channel.locales`) - 群组语言 (`session.guild.locales`) - 用户语言 (`session.user.locales`) -- 默认语言 (`app.config.i18n.locales`) -- 无语言 (`''`) -- 其他任何语言 -如果一种语言不存在对应的翻译，就会尝试使用下一种语言。如果所有语言均没有找到翻译，则会输出本身传入的渲染路径，同时输出一个警告。 +最终的目标语言将会是上述语言按顺序的并集，再根据前面介绍的规则进行回退渲染。 + +会话语言可以在一些交互场景中被直接感知得到。例如，用户如果在聊天平台中已经设置了语言偏好 (并且聊天平台提供了相应的 API)，则相关的设置可以通过适配器插件提供给会话。又比如，当开发者为一个指令设置了多种语言的别名时，可以为这些别名手动指定语言，当用户调用某一个别名时，Koishi 会按照设定好的语言来回答。 -### 路径回退 +用户语言与频道、群组语言的优先关系可以通过 [`config.i18n.output`](../../api/core/app.md#i18n-output) 来指定。默认情况下频道和群组的语言优先级高于用户语言，但是你可以将其设置为 `prefer-user` 来改变这一行为。 + +### 基于路径的回退 你也可以配置多个路径，将会按照顺序查找翻译，直到找到一个翻译为止。 @@ -127,3 +189,9 @@ session.text(['foo', 'bar']) ```ts session.text(['foo', '']) ``` + +### 用户侧覆写 + +用户可以通过 [locales](../../plugins/console/locales.md) 插件提供本地翻译，且这些翻译的优先级高于插件自身提供的翻译。可以认为，从用户提供的翻译到插件提供的翻译，也是一种回退关系。 + +关于用户侧覆写的更多信息，请参见 [入门 > 深入定制机器人](../../manual/usage/customize.md)。 diff --git a/en-US/guide/i18n/translation.md b/en-US/guide/i18n/translation.md index f29f8f4b1a7c..b443a4ccb39e 100644 --- a/en-US/guide/i18n/translation.md +++ b/en-US/guide/i18n/translation.md @@ -1,4 +1,4 @@ -# 本地化文件 +# Localization File `i18n.define()` 允许开发者为自己的插件提供多套翻译，但直接将每种语言的翻译文本写进源代码并不利于代码的解耦。因此我们建议开发者将翻译文件写在一个单独的目录中，在插件中只需要引用这个目录中的文件即可： diff --git a/en-US/index.md b/en-US/index.md index 29e3ffca9be1..4746f2c1cd6e 100644 --- a/en-US/index.md +++ b/en-US/index.md @@ -126,7 +126,7 @@ footer: text: Telegram link: /en-US/plugins/adapter/telegram.html - - text: 微信公众号 + text: WeChat Official link: /zh-CN/plugins/adapter/wechat-official.html - text: 企业微信 diff --git a/en-US/manual/starter/boilerplate.md b/en-US/manual/starter/boilerplate.md index b3d166b8f996..504944df3b18 100644 --- a/en-US/manual/starter/boilerplate.md +++ b/en-US/manual/starter/boilerplate.md @@ -7,7 +7,7 @@ next: link: /en-US/manual/usage/market.html --- -# Create a boilerplate +# Create from Template ::: tip If you want to learn about other installation method, please visit [Installation](./index.md). @@ -24,7 +24,7 @@ Of course, you could also use the template project in production. While it might ## Install Node.js -Koishi 需要 [Node.js](https://nodejs.org/) (最低 v18，推荐使用 LTS) 运行环境，你需要自己安装它。 +Koishi requires a [Node.js](https://nodejs.org/) runtime environment (at least v18, suggested to use LTS versions), you need to install it yourself. ### Download Installer @@ -84,7 +84,7 @@ yarn config set registry https://registry.npmmirror.com Open a command line, cd to the directory that you want to create a Koishi template project. ::: tip -这个路径不宜过长，且应当避免出现中文或者空格。我们推荐的路径如下： +The working directory path should not be absurdly long, also it is recommended to use a path that contains ASCII characters only. For example: - Windows：`C:\dev` or `D:\dev` (do not create projects directly at the root of the disk, preferably build a folder) - Other operating systems: `~/dev` diff --git a/en-US/manual/starter/direct.md b/en-US/manual/starter/direct.md index ef77f6d27541..e54b30e20168 100644 --- a/en-US/manual/starter/direct.md +++ b/en-US/manual/starter/direct.md @@ -25,7 +25,7 @@ While we recommend the use of the [boilerplate](./boilerplate.md) for most users The Koishi itself is written in TypeScript, so we recommend using TypeScript for Koishi development. In the following documentation, we will consistently use TypeScript as an example. If you are writing vanilla JavaScript or other JavaScript dialects, you could make modifications for your own code based on the example one. ::: -Koishi 需要 [Node.js](https://nodejs.org/) (最低 v18，推荐使用 LTS) 运行环境，你需要自己安装它。We assume that you have already installed it. +Koishi requires a [Node.js](https://nodejs.org/) runtime environment (at least v18, suggested to use LTS versions), you need to install it yourself.We assume that you have already installed it. Firstly initialize your bot directory, then install Koishi and the necessary plugins (in this example, we use the official plugins such as console, sandbox, and echo): diff --git a/en-US/manual/usage/adapter.md b/en-US/manual/usage/adapter.md index 467556dea4fc..b42fc724c750 100644 --- a/en-US/manual/usage/adapter.md +++ b/en-US/manual/usage/adapter.md @@ -1,6 +1,6 @@ # First Dialogue -After installing Koishi and experiencing the marketplace, you may can't wait to try the features of Koishi.Let's start the first conversation with the bots now! +After installing Koishi and experiencing the marketplace, you may can't wait to try the features of Koishi. Let's start the first conversation with the bots now! ## Simulate a conversation in the sandbox @@ -32,8 +32,8 @@ Simulate the conversation in the sandbox is far from enough.We need to get the r - [QQ](../../plugins/adapter/qq.md) - [Slack](../../plugins/adapter/slack.md) - [Telegram](../../plugins/adapter/telegram.md) -- [微信公众号](../../plugins/adapter/wechat-official.md) -- [企业微信](../../plugins/adapter/wecom.md) +- [WeChat Official](../../plugins/adapter/wechat-official.md) +- [WeCom](../../plugins/adapter/wecom.md) - [WhatsApp](../../plugins/adapter/whatsapp.md) The commonly used adapter plugins have been pre-installed in Koishi, you can find them in the category "Adapter" in the Plugin Configuration page.If you don't see the platform you want, you can also search for and install more adapter plugins in the marketplace. diff --git a/en-US/manual/usage/market.md b/en-US/manual/usage/market.md index 8788674f2eb2..9d6160fba92e 100644 --- a/en-US/manual/usage/market.md +++ b/en-US/manual/usage/market.md @@ -1,27 +1,29 @@ -- - - -prev: text: 选择安装方式 link: /en-US/manual/starter/ -- - - +--- +prev: + text: Installation + link: /en-US/manual/starter/ +--- # Install and Configure Plugins -::: tip +:::tip This section covers the usage of pages such as "Marketplace", "Plugin Configuration" and "Dependency Management". ::: -As the key feature, 控制台是一个对用户友好的图形界面，封装了 Koishi 的绝大多数功能： +As the key feature, Console is a graphical interface which is very friendly for users. And there are majority functions in the console. - Plugin installation, updating and uninstallation -- 启用、停用和配置插件 +- Plugin enabling, disabling and configuration - Management of commands, database and locale text -- 在模拟和真实环境下聊天 +- Chat in simulated and real environment - Running status monitoring and statistics - Log management -本节中我们将以 [echo](../../plugins/common/echo.md) 插件为例来演示插件的安装与配置。The echo plugin registered a command named `echo`. Use this command can output the input to the user originally. +We will show installing and configuring of plugins with the [echo](../../plugins/common/echo.md) plugin. The echo plugin registered a command named `echo`. Use this command can output the input to the user originally. ## About Koishi Console -在你成功安装了模板项目或启动器后，控制台将自动打开。 +The console will be opened automatically when you have a launcher or a template project installed successfully. In the left section of the Console UI, you can see a sidebar that is used to toggle the interfaces on the right section. The dashboard page would be shown by default. There is also a status bar which is used to show the running status of bots at the bottom when you are using a PC or a tablet. @@ -29,15 +31,19 @@ In the left section of the Console UI, you can see a sidebar that is used to tog ![home](/manual/console/home.dark.webp) {.dark-only} -在之后的几节里，我们会逐一介绍各界面的功能和使用。 +You can learn more about the features and usage of each interface in the following sections. ## Install Plugins -::: warning -We Koishi team doesn't warrant the availability of third party plugins. Plugins from unknown sources may break Koishi to crash, or have very serious consequences. If you have problems after downloading plugins, you can go to the user group or forum to provide feedback. In addition, some plugins are marked as "unsafe" and install such plugins will not be supported by the official group. +:::warning +We Koishi team doesn't warrant the availability of third party plugins.Plugins from unknown sources may break Koishi to crash, or have very serious consequences. +If you have problems after downloading plugins, you can go to the user group or forum to provide feedback. +In addition, some plugins are marked as "unsafe" and install such plugins will not be supported by the official group. ::: -Go to the "Marketplace" page, where you will see all downloadable plugins here. Enter `echo` in the search box to find the plugin we want, click the "Add" button, and then click "Installation" in the popup dialog.Wait for a moment, and the plugin will be installed successfully. +Go to the "Marketplace" page, where you will see all downloadable plugins here. +Enter `echo` in the search box to find the plugin we want, click the "Add" button, and then click "Installation" in the popup dialog. +Wait for a moment, and the plugin will be installed successfully. ![select-version](/manual/console/select-version.light.webp) {.light-only} @@ -45,7 +51,8 @@ Go to the "Marketplace" page, where you will see all downloadable plugins here. ## Enable and Disable Plugins -Koishi will not enable the plugin you just installed. You need to manually configure and enable it.Go to the "Plugin Configuration" page, where various configured plugins are listed in the left column. Among these, blackwhite fonts show plugins that are running, while gray fonts show plugins that are not running yet. +Koishi will not enable the plugin you just installed. You need to manually configure and enable it.Go to the "Plugin Configuration" page, where various configured plugins are listed in the left column. +Among these, blackwhite fonts show plugins that are running, while gray fonts show plugins that are not running yet. ![plugins](/manual/console/plugins.light.webp) {.light-only} @@ -53,15 +60,17 @@ Koishi will not enable the plugin you just installed. You need to manually confi We can see that the name of the echo plugin is grey, indicating that it is not running.The echo plugin does not have any configurable items, so the details page on the right side is empty.We can directly click on the "Enable Plugin" button in the upper right corner and see the "Enable success" reminder that the echo plugin is already running. -It is also easy to disable the "echo" plugin. Click the "Disable Plugin" button in the upper right corner, then the plugin will stop running.Disabling a plugin will neither delete the plugin code nor delete the plugin configuration, so you can re-enable it at any time. +It is also easy to disable the "echo" plugin. +Click the "Disable Plugin" button in the upper right corner, then the plugin will stop running.Disabling a plugin will neither delete the plugin code nor delete the plugin configuration, so you can re-enable it at any time. ## Plugins configurations -::: warning -When configuring plugins, please remember this principle: **Don't change any configuration unless necessary**.Koishi 在设计上兼顾了扩展性和实用性，许多基础功能是以预装插件的形式提供的。The "Marketplace" and "Plugin Configuration" pages that we are already using are also provided by the "market" plugin and the "config" plugin preloaded.It is because all preloaded plugins are well configured, so you do not usually need to modify the preloaded plugins' configuration.Changing the preloaded plugins' configuration or delete the preloaded plugins may cause Koishi to run improperly. +:::warning +When configuring plugins, please remember this principle: Don't change any configuration unless necessary. Koishi is designed to take into account both extension and utility, and many of the basic features are provided in the form of built-in plugins. The "Marketplace" and "Plugin Configuration" pages that we are already using are also provided by the "market" plugin and the "config" plugin preloaded.It is because all preloaded plugins are well configured, so you do not usually need to modify the preloaded plugins' configuration.Changing the preloaded plugins' configuration or delete the preloaded plugins may cause Koishi to run improperly. ::: -While the "echo" plugin does not require configuration, more complex plugins often provide configurations that allow users to control the behavior of plugins. The picture below shows the configuration page of the "novelai" plugin. +While the "echo" plugin does not require configuration, more complex plugins often provide configurations that allow users to control the behavior of plugins. +The picture below shows the configuration page of the "novelai" plugin. ![settings](/manual/console/settings.light.webp) {.light-only} @@ -69,8 +78,8 @@ While the "echo" plugin does not require configuration, more complex plugins oft In this page, we can see many configurations, where you need to take note of: -- 必选但尚未填入的配置项会在左侧呈现 红色 的提示条，只有正确填写配置才能启动插件。 -- 已修改但未保存的配置项会在左侧呈现 紫色 的提示条，点击「启用插件」或「保存配置」按钮后会保存配置；如果你想撤销这些改动，可以在配置名称旁的小三角处呼出菜单，选择「撤销更改」使该配置恢复到上次保存时的状态。 +- Required but unfilled configurations will display a red tooltip on the left, and they must be filled in correctly to enable the plugin. +- Modified but unsaved configurations will display a purple tooltip on the left, and they will be saved after you click "Enable Plugin" or "Save Configuration" button. If you want to discard these changes, you can call the menu at the small triangle next to the configuration name, select "Undo Changes" to restore the configuration to the status last saved. ## Manage Plugins @@ -82,15 +91,17 @@ Koishi pre-configured some groups during the installation, while newly installed Creating a new group is also simple.In "Global Configuration" or in any group page, click the "Create Group" button in the top right corner to create a new group.The name of the new group is randomly generated, but you can change it by clicking on the name to the name you like.The groups can unfold and fold by clicking on the small triangle in the left bar. -此外，[过滤器](../usage/customize.md#过滤器) 机制也可用于分组，便于控制一系列插件的行为。 +In addition, the [filter](../usage/customize.md#过滤器) mechanism can also be used on groups to control the behavior of a range of plugins. -### Add More Plugins +### Adding More Plugins -::: tip -Normally, a plugin can only run one configuration at once. Please refer to the [Maintaining Multiple Configurations](../recipe/multiple.md) section. +:::tip +通常情况下，一个插件只能同时运行一份配置。请参考 [维护多份配置](../recipe/multiple.md) 章节。 ::: -If an installed plugin is not shown in the plugin list, you can also add it manually. In "Global Configuration" or in any group page, click the "Add Plugin" button in the top right corner will eject a dialog box. Click on the plugin to be added in the dialog box to create a plugin configuration which is not enabled. +If an installed plugin is not shown in the plugin list, you can also add it manually. +In "Global Configuration" or in any group page, click the "Add Plugin" button in the top right corner will eject a dialog box. +Click on the plugin to be added in the dialog box to create a plugin configuration which is not enabled. ![select-plugin](/manual/console/select-plugin.light.webp) {.light-only} @@ -98,17 +109,18 @@ If an installed plugin is not shown in the plugin list, you can also add it manu ### Remove Plugin or Group -::: warning -Warning: this action cannot be undone. If you want to restore the previous configuration, you can only manually add it again. Please be careful. +:::warning +注意：此操作无法被撤销，如果你想要恢复之前的配置，只能再次手动添加。Please be careful. ::: -Click Remove Plugin button in the top right corner in the configuration page of any plugin to remove the plugin configuration. Similarly, you can remove a plugin group by clicking "Remove Group" in the top right corner of its configuration page. When removing groups, all plugins in the group will also be deleted. +Click Remove Plugin button in the top right corner in the configuration page of any plugin to remove the plugin configuration. Similarly, you can remove a plugin group by clicking "Remove Group" in the top right corner of its configuration page. +When removing groups, all plugins in the group will also be deleted. ## Update and Uninstall Plugins Go to the "Dependency Management" page. You can see the dependency list here.Dependencies may include Koishi properties, various plugins, and packages that support plugins to run, etc. -当依赖的状态显示为「可更新」时，点击其右侧的「修改」按钮，在弹出的窗口左上角选择你需要的版本，点击右下角的「更新」按钮即可完成更新。 +When the status shows "Has Update", you can click the "Modify" button on the right, select the version you need in the top left corner of the popup dialog, and click "Updated" in the bottom right corner to complete your Updated. You can also update multiple plugins. Select the version you need by relying on the dropdown menu on the right side of the dependency name. Then press the "Apply changes" button in the upper right corner.In addition, the "Update All" button in the top right corner can update all dependencies versions once(you still need to click "Apply" button). diff --git a/en-US/manual/usage/platform.md b/en-US/manual/usage/platform.md index ef1086ccf69b..2ea3d2e75305 100644 --- a/en-US/manual/usage/platform.md +++ b/en-US/manual/usage/platform.md @@ -8,7 +8,7 @@ Koishi describes itself as a "cross-platform" framework, but what does this "cro 现在就让我们来说说，如何在 Koishi 中使用跨平台的账号系统。 -## 获取账号信息 +## Get Account Information 有些平台的账号信息是不可见的，所以我们需要借助一些工具来获取它们。 @@ -26,7 +26,7 @@ Koishi describes itself as a "cross-platform" framework, but what does this "cro -如果你要进行登录或者绑定，这里的「平台名」和「用户 ID」会很有用。 +If you want to login or bind your account, the platform name and user ID here will be useful. ## Console Login diff --git a/en-US/plugins/adapter/wechat-official.md b/en-US/plugins/adapter/wechat-official.md index a81d935d675f..738c7fa072f5 100644 --- a/en-US/plugins/adapter/wechat-official.md +++ b/en-US/plugins/adapter/wechat-official.md @@ -5,7 +5,7 @@ 1. 根据 [注册流程指引](https://kf.qq.com/product/weixinmp.html#hid=87) 注册公众平台。 2. 在微信公众平台登录后，页面左侧展开「设置与开发」，进入「公众号设置」，翻至页面底部，复制 `原始 ID` 填入插件的 account 字段。 3. 页面左侧进入「基本配置」，复制 `开发者ID` 填入插件的 appId 字段，在网页上获取开发者密码填入插件的 secret 字段，设置白名单 IP。 -4. 页面下方启用服务器配置，将机器人的 `selfUrl` 值后连接 `/wechatofficial` (如 `https://example.com/wechatofficial`)，在 URL 一栏中填写；在插件配置和公众平台上填入相同的 Token；在公众平台上生成 EncodingAESKey 并填入插件的 aesKey 字段；三种消息加解密方式均可选择。 +4. 页面下方启用服务器配置，将机器人的 `selfUrl` 值后连接 `/wechat-official` (如 `https://example.com/wechat-official`)，在 URL 一栏中填写；在插件配置和公众平台上填入相同的 Token；在公众平台上生成 EncodingAESKey 并填入插件的 aesKey 字段；三种消息加解密方式均可选择。 5. 如果公众号为企业主体，且通过了微信认证，可在插件配置中启用 customerService。客服接口提供了更宽松的消息回复能力。 参考文档：[https://developers.weixin.qq.com/doc/offiaccount/Basic_Information/Access_Overview.html](https://developers.weixin.qq.com/doc/offiaccount/Basic_Information/Access_Overview.html) diff --git a/en-US/plugins/console/market.md b/en-US/plugins/console/market.md index 7f5b9d931f10..41d980dc4885 100644 --- a/en-US/plugins/console/market.md +++ b/en-US/plugins/console/market.md @@ -1,4 +1,4 @@ -# 插件市场 (Market) +# Plugin Manager (Market) ## 配置项 diff --git a/en-US/releases/v4.14.md b/en-US/releases/v4.14.md index 4dc8395f3b1a..fd77b8115047 100644 --- a/en-US/releases/v4.14.md +++ b/en-US/releases/v4.14.md @@ -37,7 +37,7 @@ v4.14 版本中，我们引入了新的权限系统。相比过去用数字来 这个版本中我们增加了大量官方适配器，可用于以下平台： - DingTalk -- 微信公众号 +- WeChat Official - 企业微信 - Slack - WhatsApp diff --git a/fr-FR/about/events.md b/fr-FR/about/events.md index 9f6abb0ffd89..6f9aef267af3 100644 --- a/fr-FR/about/events.md +++ b/fr-FR/about/events.md @@ -1,4 +1,4 @@ -# 大事件 +# Le Grand Événement ## 开源之夏 2023 diff --git a/fr-FR/about/releases.md b/fr-FR/about/releases.md index 5d94f3986d25..fa8641959069 100644 --- a/fr-FR/about/releases.md +++ b/fr-FR/about/releases.md @@ -1,4 +1,4 @@ -# 更新计划 +# Mettre à jour l'horaire ## 发布周期 diff --git a/fr-FR/about/team.md b/fr-FR/about/team.md index f9f81b3ad76d..e7aa3458a32a 100644 --- a/fr-FR/about/team.md +++ b/fr-FR/about/team.md @@ -1,4 +1,4 @@ -# 认识团队 +# À propos de l'équipe ## 核心成员 diff --git a/fr-FR/about/upgrade.md b/fr-FR/about/upgrade.md index b7ff2cba0b36..d44973a9d324 100644 --- a/fr-FR/about/upgrade.md +++ b/fr-FR/about/upgrade.md @@ -1,4 +1,4 @@ -# 从低版本迁移 +# Migration depuis une version ancienne ## JSX 支持 v4.10.3 diff --git a/fr-FR/api/core/app.md b/fr-FR/api/core/app.md index c01b54ca7836..9ecda1457034 100644 --- a/fr-FR/api/core/app.md +++ b/fr-FR/api/core/app.md @@ -91,13 +91,13 @@ interface DelayOptions { ## 国际化设置 -### options.i18n.locales +### options.i18n.locales {#i18n-locales} - 类型：`string[]` 可用的语言列表。按照回退顺序排列。 -### options.i18n.output +### options.i18n.output {#i18n-output} - 类型：`string` @@ -106,15 +106,6 @@ interface DelayOptions { - `prefer-user`: 优先使用用户语言 - `prefer-channel`: 优先使用频道语言 -## 高级设置 - -### options.maxListeners - -- 类型：`number` -- 默认值：`64` - -每种钩子的最大数量。如果超过这个数量，Koishi 会认定为发生了内存泄漏，将产生一个警告。 - ## 请求设置 ### options.request.proxyAgent diff --git a/fr-FR/cookbook/design/disposable.md b/fr-FR/cookbook/design/disposable.md index d46e2c410fae..b5fedfc509f2 100644 --- a/fr-FR/cookbook/design/disposable.md +++ b/fr-FR/cookbook/design/disposable.md @@ -1,4 +1,4 @@ -# 可逆的插件系统 +# Système réversible de plugin ::: tip 本文将回答以下问题： diff --git a/fr-FR/cookbook/design/framework.md b/fr-FR/cookbook/design/framework.md index 1d73bccf7454..0f4ae8c9627e 100644 --- a/fr-FR/cookbook/design/framework.md +++ b/fr-FR/cookbook/design/framework.md @@ -1,4 +1,4 @@ -# 从元框架到框架 +# Du méta-framework au framework :::danger 本文档尚未完成。 diff --git a/fr-FR/cookbook/design/storage.md b/fr-FR/cookbook/design/storage.md index bd48a9786af6..ac1f98753313 100644 --- a/fr-FR/cookbook/design/storage.md +++ b/fr-FR/cookbook/design/storage.md @@ -1,4 +1,4 @@ -# 零占用的存储 +# Stockage avec zéro volume ::: tip 本文将回答以下问题： diff --git a/fr-FR/cookbook/practice/testing.md b/fr-FR/cookbook/practice/testing.md index ff1e09c2fce8..3108bad2ce46 100644 --- a/fr-FR/cookbook/practice/testing.md +++ b/fr-FR/cookbook/practice/testing.md @@ -1,4 +1,4 @@ -# 编写测试 +# Écrit des tests 如果你是一位成熟的开发者，你一定知道测试的重要性。比起让机器人真正运行起来交给用户去试错，预先编写好的测试具有许多前者所不具有的优点： diff --git a/fr-FR/guide/basic/element.md b/fr-FR/guide/basic/element.md index e526981f01bd..a1fcc6a86567 100644 --- a/fr-FR/guide/basic/element.md +++ b/fr-FR/guide/basic/element.md @@ -165,7 +165,7 @@ Koishi 已经内置了一系列消息组件，包括： 你可以在 [这个页面](../../api/message/components.md) 了解每个组件的详细用法和适用范围。 -### 声明消息组件 +### 定义消息组件 一个消息组件本质上是一个函数，它接受三个参数： diff --git a/fr-FR/guide/develop/publish.md b/fr-FR/guide/develop/publish.md index 27ee42ad365f..a54a5b05e483 100644 --- a/fr-FR/guide/develop/publish.md +++ b/fr-FR/guide/develop/publish.md @@ -1,8 +1,8 @@ -# 发布插件 +# Publication du plugin 为了让别人更方便地使用你编写的插件，你需要将其作为一个 npm 包进行发布。只需满足一定的规范，你的插件就能显示在 [插件市场](../../market/) 中，其他人就可以通过控制台来安装它。 -::: tip +:::tip 本节中介绍的命令行都需要在 [应用目录](./config.md#应用目录) 下运行。 ::: @@ -21,7 +21,7 @@ root └── package.json # 而不是这里 ``` -::: tip +:::tip 请注意 `package.json` 文件不是唯一的，它在应用目录和每个插件目录都会存在。请确保你修改了正确的文件。 ::: @@ -37,7 +37,7 @@ root 其中最重要的属性有两个：`name` 是要发布的包名，`version` 是包的版本号。这里的包名相比实际在插件市场中看到的插件名多了一个 `koishi-plugin-` 的前缀，这样既方便了用户安装和配置，又防止了污染命名空间。 -::: tip +:::tip 请注意：包名和版本号都具有唯一性。包名不能与其他已经发布的包相同，而同一个包的同一个版本号也只能发布一次。如果出现了包名冲突或版本号冲突，则会在之后的发布流程中出现错误提示。你可以自行根据错误提示更换包名或更新插件版本。 ::: @@ -47,7 +47,7 @@ root ### 准入条件 -::: tip +:::tip 使用模板项目创建的插件一定是符合要求的，因此你可以跳过这一节。 ::: @@ -142,28 +142,31 @@ root - **preview:** 配置为 `true` 可以让插件显示为「开发中」状态 - **hidden:** 配置为 `true` 可以让插件市场中不显示该插件 (通常情况下你不需要这么做) -::: tip +:::tip 此外，还有一些字段与 [Koishi Online](../../cookbook/practice/online.md) 的部署流程相关 (如 `browser`, `exports` 等)。由于不影响主线开发，你可以稍后再进行了解。 ::: -## 发布插件 +## Publication du plugin 编辑完上面的清单文件并 [构建源代码](./workspace.md#构建源代码) 后，你就可以公开发布你的插件了。 -::: tabs code +:::tabs code + ```npm npm run pub [...name] ``` + ```yarn yarn pub [...name] ``` + ::: - **name:** 要发布的插件列表，缺省时表示全部 (此处 `name` 不包含 `koishi-plugin-` 前缀，而是你的工作区目录名) 这将发布所有版本号发生变动的插件。 -::: tip +:::tip 从插件成功发布到进插件市场需要一定的时间 (通常在 15 分钟内)，请耐心等待。 ::: @@ -176,39 +179,46 @@ No token found and can't prompt for login when running with --non-interactive. 此时你需要在发布时使用官方镜像，具体操作如下： -::: tabs code +:::tabs code + ```npm npm run pub [...name] -- --registry https://registry.npmjs.org ``` + ```yarn yarn pub [...name] --registry https://registry.yarnpkg.com ``` + ::: 对于 Yarn v2 及以上版本，你还可以分别针对发布和安装设置不同的镜像： -::: tabs code +:::tabs code + ```yarn # 安装时使用国内镜像 yarn config set npmRegistryServer https://registry.npmmirror.com # 发布时使用官方镜像 yarn config set npmPublishRegistry https://registry.yarnpkg.com ``` -::: -: + ::: +:::: ## 更新插件版本 初始创建的插件版本号为 `1.0.0`。当你修改过插件后，你需要更新版本号才能重新发布。在应用目录运行下面的命令以更新版本号： -::: tabs code +:::tabs code + ```npm npm run bump [...name] -- [-1|-2|-3|-p|-v ] [-r] ``` + ```yarn yarn bump [...name] [-1|-2|-3|-p|-v ] [-r] ``` + ::: - **name:** 要更新的插件列表，不能为空 diff --git a/fr-FR/guide/develop/script.md b/fr-FR/guide/develop/script.md index 3172bf7c0ec9..f50cdf9faf74 100644 --- a/fr-FR/guide/develop/script.md +++ b/fr-FR/guide/develop/script.md @@ -44,7 +44,7 @@ Koishi 的命令行工具支持自动重启。当运行 Koishi 的进程崩溃 ## 开发模式 -除了 `start` 以外，模板项目还准备了名为 `dev` 的开发模式启动脚本。在应用目录运行下面的命令行可以启动开发模式： +除了 `start` 以外，模板项目还准备了名为 `dev` 的开发模式启动脚本。在应用目录运行下面的命令行可以以开发模式启动应用： ::: tabs code ```npm @@ -55,18 +55,18 @@ yarn dev ``` ::: -如你所见，`dev` 相当于在 `start` 指令的基础上添加了额外的参数和环境变量。这些参数为我们启用了额外的特性，而环境变量则能影响插件的部分配置。 +如你所见，`dev` 相当于在 `start` 指令的基础上添加了额外的参数和环境变量。这些参数为我们启用了额外的特性，而环境变量则能影响插件的部分行为。 ### TypeScript 支持 -Koishi 工作区原生地支持 TypeScript 开发。上述 `-r esbuild-register` 参数允许我们在运行时直接使用工作区插件的 TypeScript 源代码。 +Koishi 模板项目原生地支持 TypeScript 开发。上述 `-r esbuild-register` 参数允许我们在运行时直接使用工作区插件的 TypeScript 源代码。 -你也可以自行扩展更多的后缀名支持。例如，如果你更喜欢 CoffeeScript，你可以这样修改你的启动脚本为： +你也可以自行扩展更多的后缀名支持。例如，如果你更喜欢 CoffeeScript，你可以这样修改你的开发脚本为： ```json title=package.json { "scripts": { - "start": "koishi start -r coffeescript/register" + "dev": "koishi start -r coffeescript/register" }, "devDependencies": { "coffeescript": "^2.7.0" @@ -82,7 +82,7 @@ Koishi 工作区原生地支持 TypeScript 开发。上述 `-r esbuild-register` ### 模块热替换 -如果你开发着一个巨大的 Koishi 项目，可能光是加载一遍全部插件就需要好几秒了。在这种时候，像前端框架一样支持模块热替换就成了一个很棒的主意。幸运的是，Koishi 也做到了这一点！内置插件 @koishijs/plugin-hmr 实现了插件级别的热替换。每当你修改你的本地文件时，Koishi 就会尝试重载你的插件，并在控制台提醒你。 +如果你开发着一个巨大的 Koishi 项目，可能光是加载一遍全部插件就需要好几秒了。在这种时候，像前端框架一样支持模块热替换就成了一个很棒的主意。幸运的是，Koishi 也做到了这一点！内置插件 @koishijs/plugin-hmr 实现了插件级别的热替换。每当你修改你的本地文件时，Koishi 就会尝试重载你的插件，并在命令行中提醒你。 这里的行为也可以在配置文件中进行定制： diff --git a/fr-FR/guide/i18n/index.md b/fr-FR/guide/i18n/index.md index 74ad7b96284f..1a043e68a724 100644 --- a/fr-FR/guide/i18n/index.md +++ b/fr-FR/guide/i18n/index.md @@ -51,7 +51,7 @@ channel.locales = ['en-US'] ### 插值语法 -向 `session.text()` 中传入第二个参数，就可以在模板中使用单花括号插值。花括号中的内容将对应传入列表的索引。 +向 `session.text()` 中传入第二个参数，就可以在模板中使用单花括号插值。花括号 `{}` 中的内容将对应传入列表的索引。 ```ts ctx.i18n.define('zh-CN', { hello: '你好，{0}！' }) @@ -95,22 +95,84 @@ ctx.i18n.define('en-US', { hello: 'Hello, {author.name}!' }) 上述三段代码的实际效果完全相同，可以根据自己的需要进行选择。 +### 使用消息元素 + +你也可以在模板中使用 [消息元素](../basic/element.md) 语法。消息元素的属性同样使用 `{}` 进行插值： + +```ts +ctx.i18n.define('zh-CN', { hello: '你好，！' }) +ctx.i18n.define('en-US', { hello: 'Hello, !' }) +``` + +你也可以使用消息组件，例如使用 `` 组件引用其他翻译，或使用 `` 表示本地化的时间： + +```ts +ctx.i18n.define('zh-CN', { remain: '剩余时间：' }) +ctx.i18n.define('en-US', { remain: 'Time Remain: ' }) +``` + +### 条件和循环 实验性 + +我们为模板提供了一些基本的控制流语法，它参考了 [Svelte](https://svelte.dev/) 的设计 (但并未完整实现)。你可以在模板中通过 `{#if}` 和 `{#each}` 来实现条件和循环。例如，下面的代码将会渲染一个列表： + +```html +{#if list.length === 0} + 列表中没有元素。 +{:else} + {#each list as item} + {item} + {/each} +{/if} +``` + +::: tip +如果要使用这种层面的模板能力，那么你的代码已经不适合使用 `ctx.i18n.define()` 定义了。建议参考 [下一节](./translation.md) 中的做法，将不同语言的模板放入不同的文件中，以方便编辑和管理。 +::: + ## 渲染回退 -### 语言优先级 +一次完整的本地化渲染可能涉及多种不同优先级的语言和渲染路径。当首选语言的首选路径对应的翻译文本不存在时，会依次尝试使用其他翻译，这就是渲染回退。 -默认情况下的渲染优先级依次为： +### 基于语言的回退 +首先需要了解的是基于语言的回退。根据 [IETF 语言标签](https://zh.wikipedia.org/wiki/IETF%E8%AA%9E%E8%A8%80%E6%A8%99%E7%B1%A4) 规范，一个语言名称可以包含由 `-` 分隔的多个部分，例如 `de-DE-bavarian`。用户可以为应用设置 [`config.i18n.locales`](../../api/core/app.md#i18n-locales) 来指定可用的语言列表，这些语言将按照 `-` 分隔符形成一棵字典树，而 Koishi 会按照以下规则进行回退： + +1. 找到目标语言的在字典树中出现的最长前缀对应的节点； +2. 按照用户配置的优先级渲染改节点的子树所包含的语言，并将它们移除； +3. 如果此时仍有未被渲染过的语言，那么回到 1 继续遍历，直到所有语言被遍历完全。 + +例如，如果用户配置的语言列表为 `zh-CN`, `en-US`, `zh-TW`, `en-GB`，则对于不同的目标语言会生成对应的回退序列： + +- 目标语言为 `en`，回退序列为 `en`, `en-US`, `en-GB`, ``, `zh`, `zh-CN`, `zh-TW` +- 目标语言为 `zh-TW`，回退序列为 `zh-TW`, `zh`, `zh-CN`, `en`, `en-US`, `en-GB`, `` +- 目标语言为 `de-DE`，回退序列为 ``, `zh`, `zh-CN`, `zh-TW`, `en`, `en-US`, `en-GB` +- 目标语言为 `en`, `zh-TW`，回退序列为 `en`, `en-US`, `en-GB`, `zh-TW`, `zh`, `zh-CN`, `` +- 目标语言为 `zh-TW`, `en`，回退序列为 `zh-TW`, `en`, `en-US`, `en-GB`, `zh`, `zh-CN`, `` + +请注意，空字符串也被视为合法的语言，其所代表的是「没有指定语言」的情况。在实践中，空语言的使用是非常广泛的，例如当用户使用下面的代码定义指令： + +```ts +ctx.command('echo', '回声') +``` + +此时我们无法推测出「回声」的语言，因此它将会被作为路径 `commands.echo.name` 注册到空语言下。用户可以为其定义其他语言的翻译，但在未命中任何翻译时，它将回退到空语言。 + +### 基于会话的回退 + +实际的本地化渲染通常发生在消息会话中。对于一个会话，我们可以从以下几个维度来确定它的目标语言 (每个维度都可以存在多个目标语言)： + +- 会话语言 (`session.locales`) - 频道语言 (`session.channel.locales`) - 群组语言 (`session.guild.locales`) - 用户语言 (`session.user.locales`) -- 默认语言 (`app.config.i18n.locales`) -- 无语言 (`''`) -- 其他任何语言 -如果一种语言不存在对应的翻译，就会尝试使用下一种语言。如果所有语言均没有找到翻译，则会输出本身传入的渲染路径，同时输出一个警告。 +最终的目标语言将会是上述语言按顺序的并集，再根据前面介绍的规则进行回退渲染。 + +会话语言可以在一些交互场景中被直接感知得到。例如，用户如果在聊天平台中已经设置了语言偏好 (并且聊天平台提供了相应的 API)，则相关的设置可以通过适配器插件提供给会话。又比如，当开发者为一个指令设置了多种语言的别名时，可以为这些别名手动指定语言，当用户调用某一个别名时，Koishi 会按照设定好的语言来回答。 -### 路径回退 +用户语言与频道、群组语言的优先关系可以通过 [`config.i18n.output`](../../api/core/app.md#i18n-output) 来指定。默认情况下频道和群组的语言优先级高于用户语言，但是你可以将其设置为 `prefer-user` 来改变这一行为。 + +### 基于路径的回退 你也可以配置多个路径，将会按照顺序查找翻译，直到找到一个翻译为止。 @@ -127,3 +189,9 @@ session.text(['foo', 'bar']) ```ts session.text(['foo', '']) ``` + +### 用户侧覆写 + +用户可以通过 [locales](../../plugins/console/locales.md) 插件提供本地翻译，且这些翻译的优先级高于插件自身提供的翻译。可以认为，从用户提供的翻译到插件提供的翻译，也是一种回退关系。 + +关于用户侧覆写的更多信息，请参见 [入门 > 深入定制机器人](../../manual/usage/customize.md)。 diff --git a/fr-FR/guide/i18n/translation.md b/fr-FR/guide/i18n/translation.md index f29f8f4b1a7c..03970e652cf8 100644 --- a/fr-FR/guide/i18n/translation.md +++ b/fr-FR/guide/i18n/translation.md @@ -1,4 +1,4 @@ -# 本地化文件 +# Fichier de localisation `i18n.define()` 允许开发者为自己的插件提供多套翻译，但直接将每种语言的翻译文本写进源代码并不利于代码的解耦。因此我们建议开发者将翻译文件写在一个单独的目录中，在插件中只需要引用这个目录中的文件即可： diff --git a/fr-FR/manual/starter/android.md b/fr-FR/manual/starter/android.md index 87e1486f986d..e23c700efec5 100644 --- a/fr-FR/manual/starter/android.md +++ b/fr-FR/manual/starter/android.md @@ -3,7 +3,7 @@ prev: text: Choisir une méthode d'installation link: /fr-FR/manual/starter/ next: - text: Installation et configuration de plugins + text: Installation et configuration des plugins link: /fr-FR/manual/usage/market.html --- diff --git a/fr-FR/manual/starter/boilerplate.md b/fr-FR/manual/starter/boilerplate.md index 8443f1b5bd1c..bb8d455a7835 100644 --- a/fr-FR/manual/starter/boilerplate.md +++ b/fr-FR/manual/starter/boilerplate.md @@ -3,7 +3,7 @@ prev: text: Choisir une méthode d'installation link: /fr-FR/manual/starter/ next: - text: Installation et configuration de plugins + text: Installation et configuration des plugins link: /fr-FR/manual/usage/market.html --- diff --git a/fr-FR/manual/starter/docker.md b/fr-FR/manual/starter/docker.md index 446da2efc0ce..6ca9a39a9163 100644 --- a/fr-FR/manual/starter/docker.md +++ b/fr-FR/manual/starter/docker.md @@ -3,7 +3,7 @@ prev: text: Choisir une méthode d'installation link: /fr-FR/manual/starter/ next: - text: Installation et configuration de plugins + text: Installation et configuration des plugins link: /fr-FR/manual/usage/market.html --- diff --git a/fr-FR/manual/starter/linux.md b/fr-FR/manual/starter/linux.md index 01faa9693a20..bb5875edbca6 100644 --- a/fr-FR/manual/starter/linux.md +++ b/fr-FR/manual/starter/linux.md @@ -3,7 +3,7 @@ prev: text: Choisir une méthode d'installation link: /fr-FR/manual/starter/ next: - text: Installation et configuration de plugins + text: Installation et configuration des plugins link: /fr-FR/manual/usage/market.html --- diff --git a/fr-FR/manual/starter/macos.md b/fr-FR/manual/starter/macos.md index a054ed86fe80..694caeed148c 100644 --- a/fr-FR/manual/starter/macos.md +++ b/fr-FR/manual/starter/macos.md @@ -3,7 +3,7 @@ prev: text: Choisir une méthode d'installation link: /fr-FR/manual/starter/ next: - text: Installation et configuration de plugins + text: Installation et configuration des plugins link: /fr-FR/manual/usage/market.html --- diff --git a/fr-FR/manual/starter/windows.md b/fr-FR/manual/starter/windows.md index b0d89d325769..0fce80a49c8b 100644 --- a/fr-FR/manual/starter/windows.md +++ b/fr-FR/manual/starter/windows.md @@ -3,7 +3,7 @@ prev: text: Autre méthode d'installation link: /fr-FR/manual/starter/ next: - text: Installation et configuration de plugins + text: Installation et configuration des plugins link: /fr-FR/manual/usage/market.html --- diff --git a/fr-FR/manual/usage/market.md b/fr-FR/manual/usage/market.md index 4b477759a49a..5d5758586f16 100644 --- a/fr-FR/manual/usage/market.md +++ b/fr-FR/manual/usage/market.md @@ -1,11 +1,13 @@ -- - - -prev: text: Choisir une méthode d'installation link: /fr-FR/manual/starter/ -- - - +--- +prev: + text: Choisir une méthode d'installation + link: /fr-FR/manual/starter/ +--- -# Installation et configuration de plugins +# Installation et configuration des plugins -::: tip -Cette section explique comment utiliser les pages "Marketplace des plugins", "Configuration des plugins" et "Gestion des dépendances". +:::tip +本节将介绍「插件市场」「插件配置」和「依赖管理」页面的使用方法。 ::: L'une des fonctionnalités clés de Koishi est sa puissante console.La console est une interface utilisateur conviviale qui encapsule la plupart des fonctionnalités de Koishi : @@ -17,7 +19,7 @@ L'une des fonctionnalités clés de Koishi est sa puissante console.La console e - Surveillance de l'état, statistiques des données - Voir le journal -Dans cette section, nous utiliserons l'exemple du plugin [echo](../../plugins/common/echo.md) pour vous montrer comment installer et configurer des plugins.Le plugin echo enregistre une commande nommée `echo`, qui renvoie le texte d'entrée tel quel à l'utilisateur. +本节中我们将以 [echo](../../plugins/common/echo.md) 插件为例来演示插件的安装与配置。echo 插件注册了一个名为 `echo` 的指令，调用此指令可以将输入原样输出给用户。 ## Découverte de la console @@ -31,13 +33,13 @@ L'interface de la console est principalement divisée en deux parties : à gauch Au cours des prochaines sections, nous expliquerons en détail les fonctionnalités et l'utilisation de chaque page. -## Installation de plugins +## Installer les plugins -::: warning -Koishi ne garantit pas la sécurité des plugins non officiels. N'installez pas de plugins provenant de sources inconnues, car ils peuvent rendre Koishi instable, voire entraîner des conséquences plus graves. Si vous rencontrez des problèmes après avoir installé un plugin, veuillez signaler le problème dans le groupe d'utilisateurs ou le forum. De plus, certains plugins portent l'étiquette "Non sécurisé" et ne bénéficient pas du support de la communauté officielle. +:::warning +Koishi 不对非官方插件的安全性做任何保证。N'installez pas de plugins provenant de sources inconnues, car ils peuvent rendre Koishi instable, voire entraîner des conséquences plus graves. Si vous rencontrez des problèmes après avoir installé un plugin, veuillez signaler le problème dans le groupe d'utilisateurs ou le forum. De plus, certains plugins portent l'étiquette "Non sécurisé" et ne bénéficient pas du support de la communauté officielle. ::: -Accédez à la page "Marketplace des plugins". Vous y trouverez tous les plugins disponibles. Dans la barre de recherche, saisissez `echo`, trouvez le plugin que vous souhaitez, cliquez sur le bouton "Ajouter", puis cliquez sur "Installer" dans la fenêtre contextuelle. Attendez un moment, le plugin est maintenant installé avec succès. +Accédez à la page "Marketplace des plugins". Vous y trouverez tous les plugins disponibles. 在搜索框中输入 `echo`，找到我们想要的插件，点击「添加」按钮，然后在弹出的对话框中点击「安装」。Attendez un moment, le plugin est maintenant installé avec succès. ![select-version](/manual/console/select-version.light.webp) {.light-only} @@ -57,8 +59,8 @@ La désactivation d'un plugin est tout aussi simple.La désactivation d'un plugi ## Configuration des plugins -::: warning -Lors de la configuration des plugins, gardez à l'esprit ce principe : **ne modifiez pas la configuration à moins que cela ne soit nécessaire**. Koishi a été conçu pour allier extensibilité et praticité, et de nombreuses fonctionnalités de base sont fournies sous la forme de plugins pré-installés. Les pages "Marketplace des plugins" et "Configuration des plugins" sont elles-mêmes fournies par les plugins market et config pré-installés. Étant donné que tous les plugins pré-installés sont préconfigurés, vous n'avez généralement pas besoin de modifier leur configuration. La modification arbitraire de la configuration des plugins ou la suppression de plugins pré-installés peut entraîner des dysfonctionnements de Koishi. +:::warning +在配置插件的过程中，请大家记住这个原则：**如无必要，勿动配置**。Koishi a été conçu pour allier extensibilité et praticité, et de nombreuses fonctionnalités de base sont fournies sous la forme de plugins pré-installés. Les pages "Marketplace des plugins" et "Configuration des plugins" sont elles-mêmes fournies par les plugins market et config pré-installés. Étant donné que tous les plugins pré-installés sont préconfigurés, vous n'avez généralement pas besoin de modifier leur configuration. La modification arbitraire de la configuration des plugins ou la suppression de plugins pré-installés peut entraîner des dysfonctionnements de Koishi. ::: Bien que le plugin echo n'ait pas besoin de configuration, les plugins plus complexes offrent souvent de nombreuses options de configuration pour permettre aux utilisateurs de contrôler leur comportement. L'image suivante montre la page de configuration du plugin novelai. @@ -69,8 +71,8 @@ Bien que le plugin echo n'ait pas besoin de configuration, les plugins plus comp Sur cette page, vous verrez de nombreuses options de configuration. Notez ce qui suit : -- 必选但尚未填入的配置项会在左侧呈现 红色 的提示条，只有正确填写配置才能启动插件。 -- 已修改但未保存的配置项会在左侧呈现 紫色 的提示条，点击「启用插件」或「保存配置」按钮后会保存配置；如果你想撤销这些改动，可以在配置名称旁的小三角处呼出菜单，选择「撤销更改」使该配置恢复到上次保存时的状态。 +- Les options de configuration obligatoires mais non encore renseignées sont indiquées par une barre d'information rouge. Vous devez remplir correctement ces options pour activer le plugin. +- Les options de configuration modifiées mais non enregistrées sont indiquées par une barre d'information violette. Une fois que vous avez modifié une configuration, cliquez sur le bouton "Activer le plugin" ou "Enregistrer la configuration" pour enregistrer les modifications. Si vous souhaitez annuler les modifications, vous pouvez cliquer sur le menu déroulant à côté du nom de la configuration, puis choisir "Annuler les modifications" pour ramener la configuration à son état précédemment enregistré. ## Gestion des plugins @@ -82,12 +84,12 @@ Lors de l'installation de Koishi, certains groupes sont préconfigurés, et les La création d'un nouveau groupe est également simple. Cliquez sur "Configuration globale" ou sur le nom d'un groupe, puis cliquez sur le bouton "Créer un groupe" en haut à droite. Le nom du nouveau groupe est généré de manière aléatoire, mais vous pouvez cliquer sur le nom pour le modifier comme vous le souhaitez. Les groupes peuvent être développés ou réduits en cliquant sur la petite flèche à côté du nom du groupe. -De plus, le mécanisme [de filtre](../usage/customize.md#filtres) peut également être utilisé avec les groupes pour contrôler le comportement de plusieurs plugins à la fois. +此外，[过滤器](../usage/customize.md#过滤器) 机制也可用于分组，便于控制一系列插件的行为。 -### Ajout de plus de plugins +### Ajout de plugins supplémentaires -::: tip -En général, un seul plugin peut être exécuté à la fois avec une configuration donnée. Consultez la section [Gérer plusieurs configurations](../recipe/multiple.md) pour plus d'informations. +:::tip +通常情况下，一个插件只能同时运行一份配置。请参考 [维护多份配置](../recipe/multiple.md) 章节。 ::: Si un plugin déjà installé n'apparaît pas dans la liste des plugins, vous pouvez l'ajouter manuellement. Sur la page "Configuration globale" ou de n'importe quel groupe, cliquez sur le bouton "Ajouter un plugin", puis une fenêtre contextuelle apparaîtra. Dans cette fenêtre contextuelle, cliquez sur le plugin que vous souhaitez ajouter pour créer une nouvelle configuration de plugin non activée. @@ -98,8 +100,8 @@ Si un plugin déjà installé n'apparaît pas dans la liste des plugins, vous po ### Suppression de plugins ou de groupes -::: warning -Attention : cette opération ne peut pas être annulée. Si vous souhaitez restaurer la configuration précédente, vous devrez ajouter manuellement les plugins. Faites preuve de prudence. +:::warning +注意：此操作无法被撤销，如果你想要恢复之前的配置，只能再次手动添加。Faites preuve de prudence. ::: Sur n'importe quelle page de configuration de plugin, cliquez sur le bouton "Supprimer le plugin" en haut à droite pour supprimer la configuration du plugin. De même, dans la page de configuration du groupe, cliquez sur le bouton "Supprimer le groupe" en haut à droite pour supprimer ce groupe. Lorsque vous supprimez un groupe, tous les plugins qui s'y trouvent sont également supprimés. diff --git a/fr-FR/plugins/adapter/wechat-official.md b/fr-FR/plugins/adapter/wechat-official.md index a81d935d675f..738c7fa072f5 100644 --- a/fr-FR/plugins/adapter/wechat-official.md +++ b/fr-FR/plugins/adapter/wechat-official.md @@ -5,7 +5,7 @@ 1. 根据 [注册流程指引](https://kf.qq.com/product/weixinmp.html#hid=87) 注册公众平台。 2. 在微信公众平台登录后，页面左侧展开「设置与开发」，进入「公众号设置」，翻至页面底部，复制 `原始 ID` 填入插件的 account 字段。 3. 页面左侧进入「基本配置」，复制 `开发者ID` 填入插件的 appId 字段，在网页上获取开发者密码填入插件的 secret 字段，设置白名单 IP。 -4. 页面下方启用服务器配置，将机器人的 `selfUrl` 值后连接 `/wechatofficial` (如 `https://example.com/wechatofficial`)，在 URL 一栏中填写；在插件配置和公众平台上填入相同的 Token；在公众平台上生成 EncodingAESKey 并填入插件的 aesKey 字段；三种消息加解密方式均可选择。 +4. 页面下方启用服务器配置，将机器人的 `selfUrl` 值后连接 `/wechat-official` (如 `https://example.com/wechat-official`)，在 URL 一栏中填写；在插件配置和公众平台上填入相同的 Token；在公众平台上生成 EncodingAESKey 并填入插件的 aesKey 字段；三种消息加解密方式均可选择。 5. 如果公众号为企业主体，且通过了微信认证，可在插件配置中启用 customerService。客服接口提供了更宽松的消息回复能力。 参考文档：[https://developers.weixin.qq.com/doc/offiaccount/Basic_Information/Access_Overview.html](https://developers.weixin.qq.com/doc/offiaccount/Basic_Information/Access_Overview.html) diff --git a/ja-JP/api/core/app.md b/ja-JP/api/core/app.md index c01b54ca7836..9ecda1457034 100644 --- a/ja-JP/api/core/app.md +++ b/ja-JP/api/core/app.md @@ -91,13 +91,13 @@ interface DelayOptions { ## 国际化设置 -### options.i18n.locales +### options.i18n.locales {#i18n-locales} - 类型：`string[]` 可用的语言列表。按照回退顺序排列。 -### options.i18n.output +### options.i18n.output {#i18n-output} - 类型：`string` @@ -106,15 +106,6 @@ interface DelayOptions { - `prefer-user`: 优先使用用户语言 - `prefer-channel`: 优先使用频道语言 -## 高级设置 - -### options.maxListeners - -- 类型：`number` -- 默认值：`64` - -每种钩子的最大数量。如果超过这个数量，Koishi 会认定为发生了内存泄漏，将产生一个警告。 - ## 请求设置 ### options.request.proxyAgent diff --git a/ja-JP/guide/basic/element.md b/ja-JP/guide/basic/element.md index e526981f01bd..a1fcc6a86567 100644 --- a/ja-JP/guide/basic/element.md +++ b/ja-JP/guide/basic/element.md @@ -165,7 +165,7 @@ Koishi 已经内置了一系列消息组件，包括： 你可以在 [这个页面](../../api/message/components.md) 了解每个组件的详细用法和适用范围。 -### 声明消息组件 +### 定义消息组件 一个消息组件本质上是一个函数，它接受三个参数： diff --git a/ja-JP/guide/develop/publish.md b/ja-JP/guide/develop/publish.md index 27ee42ad365f..f70d0db6b538 100644 --- a/ja-JP/guide/develop/publish.md +++ b/ja-JP/guide/develop/publish.md @@ -1,8 +1,8 @@ -# 发布插件 +# プラグインを公開する 为了让别人更方便地使用你编写的插件，你需要将其作为一个 npm 包进行发布。只需满足一定的规范，你的插件就能显示在 [插件市场](../../market/) 中，其他人就可以通过控制台来安装它。 -::: tip +:::tip 本节中介绍的命令行都需要在 [应用目录](./config.md#应用目录) 下运行。 ::: @@ -21,7 +21,7 @@ root └── package.json # 而不是这里 ``` -::: tip +:::tip 请注意 `package.json` 文件不是唯一的，它在应用目录和每个插件目录都会存在。请确保你修改了正确的文件。 ::: @@ -37,7 +37,7 @@ root 其中最重要的属性有两个：`name` 是要发布的包名，`version` 是包的版本号。这里的包名相比实际在插件市场中看到的插件名多了一个 `koishi-plugin-` 的前缀，这样既方便了用户安装和配置，又防止了污染命名空间。 -::: tip +:::tip 请注意：包名和版本号都具有唯一性。包名不能与其他已经发布的包相同，而同一个包的同一个版本号也只能发布一次。如果出现了包名冲突或版本号冲突，则会在之后的发布流程中出现错误提示。你可以自行根据错误提示更换包名或更新插件版本。 ::: @@ -47,7 +47,7 @@ root ### 准入条件 -::: tip +:::tip 使用模板项目创建的插件一定是符合要求的，因此你可以跳过这一节。 ::: @@ -142,28 +142,31 @@ root - **preview:** 配置为 `true` 可以让插件显示为「开发中」状态 - **hidden:** 配置为 `true` 可以让插件市场中不显示该插件 (通常情况下你不需要这么做) -::: tip +:::tip 此外，还有一些字段与 [Koishi Online](../../cookbook/practice/online.md) 的部署流程相关 (如 `browser`, `exports` 等)。由于不影响主线开发，你可以稍后再进行了解。 ::: -## 发布插件 +## プラグインを公開する 编辑完上面的清单文件并 [构建源代码](./workspace.md#构建源代码) 后，你就可以公开发布你的插件了。 -::: tabs code +:::tabs code + ```npm npm run pub [...name] ``` + ```yarn yarn pub [...name] ``` + ::: - **name:** 要发布的插件列表，缺省时表示全部 (此处 `name` 不包含 `koishi-plugin-` 前缀，而是你的工作区目录名) 这将发布所有版本号发生变动的插件。 -::: tip +:::tip 从插件成功发布到进插件市场需要一定的时间 (通常在 15 分钟内)，请耐心等待。 ::: @@ -176,39 +179,46 @@ No token found and can't prompt for login when running with --non-interactive. 此时你需要在发布时使用官方镜像，具体操作如下： -::: tabs code +:::tabs code + ```npm npm run pub [...name] -- --registry https://registry.npmjs.org ``` + ```yarn yarn pub [...name] --registry https://registry.yarnpkg.com ``` + ::: 对于 Yarn v2 及以上版本，你还可以分别针对发布和安装设置不同的镜像： -::: tabs code +:::tabs code + ```yarn # 安装时使用国内镜像 yarn config set npmRegistryServer https://registry.npmmirror.com # 发布时使用官方镜像 yarn config set npmPublishRegistry https://registry.yarnpkg.com ``` -::: -: + ::: +:::: ## 更新插件版本 初始创建的插件版本号为 `1.0.0`。当你修改过插件后，你需要更新版本号才能重新发布。在应用目录运行下面的命令以更新版本号： -::: tabs code +:::tabs code + ```npm npm run bump [...name] -- [-1|-2|-3|-p|-v ] [-r] ``` + ```yarn yarn bump [...name] [-1|-2|-3|-p|-v ] [-r] ``` + ::: - **name:** 要更新的插件列表，不能为空 diff --git a/ja-JP/guide/develop/script.md b/ja-JP/guide/develop/script.md index 3172bf7c0ec9..f50cdf9faf74 100644 --- a/ja-JP/guide/develop/script.md +++ b/ja-JP/guide/develop/script.md @@ -44,7 +44,7 @@ Koishi 的命令行工具支持自动重启。当运行 Koishi 的进程崩溃 ## 开发模式 -除了 `start` 以外，模板项目还准备了名为 `dev` 的开发模式启动脚本。在应用目录运行下面的命令行可以启动开发模式： +除了 `start` 以外，模板项目还准备了名为 `dev` 的开发模式启动脚本。在应用目录运行下面的命令行可以以开发模式启动应用： ::: tabs code ```npm @@ -55,18 +55,18 @@ yarn dev ``` ::: -如你所见，`dev` 相当于在 `start` 指令的基础上添加了额外的参数和环境变量。这些参数为我们启用了额外的特性，而环境变量则能影响插件的部分配置。 +如你所见，`dev` 相当于在 `start` 指令的基础上添加了额外的参数和环境变量。这些参数为我们启用了额外的特性，而环境变量则能影响插件的部分行为。 ### TypeScript 支持 -Koishi 工作区原生地支持 TypeScript 开发。上述 `-r esbuild-register` 参数允许我们在运行时直接使用工作区插件的 TypeScript 源代码。 +Koishi 模板项目原生地支持 TypeScript 开发。上述 `-r esbuild-register` 参数允许我们在运行时直接使用工作区插件的 TypeScript 源代码。 -你也可以自行扩展更多的后缀名支持。例如，如果你更喜欢 CoffeeScript，你可以这样修改你的启动脚本为： +你也可以自行扩展更多的后缀名支持。例如，如果你更喜欢 CoffeeScript，你可以这样修改你的开发脚本为： ```json title=package.json { "scripts": { - "start": "koishi start -r coffeescript/register" + "dev": "koishi start -r coffeescript/register" }, "devDependencies": { "coffeescript": "^2.7.0" @@ -82,7 +82,7 @@ Koishi 工作区原生地支持 TypeScript 开发。上述 `-r esbuild-register` ### 模块热替换 -如果你开发着一个巨大的 Koishi 项目，可能光是加载一遍全部插件就需要好几秒了。在这种时候，像前端框架一样支持模块热替换就成了一个很棒的主意。幸运的是，Koishi 也做到了这一点！内置插件 @koishijs/plugin-hmr 实现了插件级别的热替换。每当你修改你的本地文件时，Koishi 就会尝试重载你的插件，并在控制台提醒你。 +如果你开发着一个巨大的 Koishi 项目，可能光是加载一遍全部插件就需要好几秒了。在这种时候，像前端框架一样支持模块热替换就成了一个很棒的主意。幸运的是，Koishi 也做到了这一点！内置插件 @koishijs/plugin-hmr 实现了插件级别的热替换。每当你修改你的本地文件时，Koishi 就会尝试重载你的插件，并在命令行中提醒你。 这里的行为也可以在配置文件中进行定制： diff --git a/ja-JP/guide/i18n/index.md b/ja-JP/guide/i18n/index.md index 74ad7b96284f..1a043e68a724 100644 --- a/ja-JP/guide/i18n/index.md +++ b/ja-JP/guide/i18n/index.md @@ -51,7 +51,7 @@ channel.locales = ['en-US'] ### 插值语法 -向 `session.text()` 中传入第二个参数，就可以在模板中使用单花括号插值。花括号中的内容将对应传入列表的索引。 +向 `session.text()` 中传入第二个参数，就可以在模板中使用单花括号插值。花括号 `{}` 中的内容将对应传入列表的索引。 ```ts ctx.i18n.define('zh-CN', { hello: '你好，{0}！' }) @@ -95,22 +95,84 @@ ctx.i18n.define('en-US', { hello: 'Hello, {author.name}!' }) 上述三段代码的实际效果完全相同，可以根据自己的需要进行选择。 +### 使用消息元素 + +你也可以在模板中使用 [消息元素](../basic/element.md) 语法。消息元素的属性同样使用 `{}` 进行插值： + +```ts +ctx.i18n.define('zh-CN', { hello: '你好，！' }) +ctx.i18n.define('en-US', { hello: 'Hello, !' }) +``` + +你也可以使用消息组件，例如使用 `` 组件引用其他翻译，或使用 `` 表示本地化的时间： + +```ts +ctx.i18n.define('zh-CN', { remain: '剩余时间：' }) +ctx.i18n.define('en-US', { remain: 'Time Remain: ' }) +``` + +### 条件和循环 实验性 + +我们为模板提供了一些基本的控制流语法，它参考了 [Svelte](https://svelte.dev/) 的设计 (但并未完整实现)。你可以在模板中通过 `{#if}` 和 `{#each}` 来实现条件和循环。例如，下面的代码将会渲染一个列表： + +```html +{#if list.length === 0} + 列表中没有元素。 +{:else} + {#each list as item} + {item} + {/each} +{/if} +``` + +::: tip +如果要使用这种层面的模板能力，那么你的代码已经不适合使用 `ctx.i18n.define()` 定义了。建议参考 [下一节](./translation.md) 中的做法，将不同语言的模板放入不同的文件中，以方便编辑和管理。 +::: + ## 渲染回退 -### 语言优先级 +一次完整的本地化渲染可能涉及多种不同优先级的语言和渲染路径。当首选语言的首选路径对应的翻译文本不存在时，会依次尝试使用其他翻译，这就是渲染回退。 -默认情况下的渲染优先级依次为： +### 基于语言的回退 +首先需要了解的是基于语言的回退。根据 [IETF 语言标签](https://zh.wikipedia.org/wiki/IETF%E8%AA%9E%E8%A8%80%E6%A8%99%E7%B1%A4) 规范，一个语言名称可以包含由 `-` 分隔的多个部分，例如 `de-DE-bavarian`。用户可以为应用设置 [`config.i18n.locales`](../../api/core/app.md#i18n-locales) 来指定可用的语言列表，这些语言将按照 `-` 分隔符形成一棵字典树，而 Koishi 会按照以下规则进行回退： + +1. 找到目标语言的在字典树中出现的最长前缀对应的节点； +2. 按照用户配置的优先级渲染改节点的子树所包含的语言，并将它们移除； +3. 如果此时仍有未被渲染过的语言，那么回到 1 继续遍历，直到所有语言被遍历完全。 + +例如，如果用户配置的语言列表为 `zh-CN`, `en-US`, `zh-TW`, `en-GB`，则对于不同的目标语言会生成对应的回退序列： + +- 目标语言为 `en`，回退序列为 `en`, `en-US`, `en-GB`, ``, `zh`, `zh-CN`, `zh-TW` +- 目标语言为 `zh-TW`，回退序列为 `zh-TW`, `zh`, `zh-CN`, `en`, `en-US`, `en-GB`, `` +- 目标语言为 `de-DE`，回退序列为 ``, `zh`, `zh-CN`, `zh-TW`, `en`, `en-US`, `en-GB` +- 目标语言为 `en`, `zh-TW`，回退序列为 `en`, `en-US`, `en-GB`, `zh-TW`, `zh`, `zh-CN`, `` +- 目标语言为 `zh-TW`, `en`，回退序列为 `zh-TW`, `en`, `en-US`, `en-GB`, `zh`, `zh-CN`, `` + +请注意，空字符串也被视为合法的语言，其所代表的是「没有指定语言」的情况。在实践中，空语言的使用是非常广泛的，例如当用户使用下面的代码定义指令： + +```ts +ctx.command('echo', '回声') +``` + +此时我们无法推测出「回声」的语言，因此它将会被作为路径 `commands.echo.name` 注册到空语言下。用户可以为其定义其他语言的翻译，但在未命中任何翻译时，它将回退到空语言。 + +### 基于会话的回退 + +实际的本地化渲染通常发生在消息会话中。对于一个会话，我们可以从以下几个维度来确定它的目标语言 (每个维度都可以存在多个目标语言)： + +- 会话语言 (`session.locales`) - 频道语言 (`session.channel.locales`) - 群组语言 (`session.guild.locales`) - 用户语言 (`session.user.locales`) -- 默认语言 (`app.config.i18n.locales`) -- 无语言 (`''`) -- 其他任何语言 -如果一种语言不存在对应的翻译，就会尝试使用下一种语言。如果所有语言均没有找到翻译，则会输出本身传入的渲染路径，同时输出一个警告。 +最终的目标语言将会是上述语言按顺序的并集，再根据前面介绍的规则进行回退渲染。 + +会话语言可以在一些交互场景中被直接感知得到。例如，用户如果在聊天平台中已经设置了语言偏好 (并且聊天平台提供了相应的 API)，则相关的设置可以通过适配器插件提供给会话。又比如，当开发者为一个指令设置了多种语言的别名时，可以为这些别名手动指定语言，当用户调用某一个别名时，Koishi 会按照设定好的语言来回答。 -### 路径回退 +用户语言与频道、群组语言的优先关系可以通过 [`config.i18n.output`](../../api/core/app.md#i18n-output) 来指定。默认情况下频道和群组的语言优先级高于用户语言，但是你可以将其设置为 `prefer-user` 来改变这一行为。 + +### 基于路径的回退 你也可以配置多个路径，将会按照顺序查找翻译，直到找到一个翻译为止。 @@ -127,3 +189,9 @@ session.text(['foo', 'bar']) ```ts session.text(['foo', '']) ``` + +### 用户侧覆写 + +用户可以通过 [locales](../../plugins/console/locales.md) 插件提供本地翻译，且这些翻译的优先级高于插件自身提供的翻译。可以认为，从用户提供的翻译到插件提供的翻译，也是一种回退关系。 + +关于用户侧覆写的更多信息，请参见 [入门 > 深入定制机器人](../../manual/usage/customize.md)。 diff --git a/ja-JP/manual/usage/market.md b/ja-JP/manual/usage/market.md index 6a0ecd918bdc..817d2501bb15 100644 --- a/ja-JP/manual/usage/market.md +++ b/ja-JP/manual/usage/market.md @@ -1,10 +1,12 @@ -- - - -prev: text: 选择安装方式 link: /zh-CN/manual/starter/ -- - - +--- +prev: + text: インストール方法 + link: /ja-JP/manual/starter/ +--- -# 安装和配置插件 +# プラグインのインストールと設定 -::: tip +:::tip 本节将介绍「插件市场」「插件配置」和「依赖管理」页面的使用方法。 ::: @@ -33,7 +35,7 @@ Koishi 的一个核心特性是强大的控制台。控制台是一个对用户 ## 安装插件 -::: warning +:::warning Koishi 不对非官方插件的安全性做任何保证。请不要随意下载来源不明的插件，因为它们可能导致 Koishi 无法运行，甚至更严重的后果。如果你下载插件后遇到了问题，可以前往用户群或论坛进行反馈。此外，部分插件带有「不安全」标识，安装此类插件将不会受到官方群内的支持。 ::: @@ -57,7 +59,7 @@ Koishi 不会自动启用刚刚安装的插件，你需要手动配置并启用 ## 配置插件 -::: warning +:::warning 在配置插件的过程中，请大家记住这个原则：**如无必要，勿动配置**。Koishi 在设计上兼顾了扩展性和实用性，许多基础功能是以预装插件的形式提供的。前面我们已经用到的「插件市场」和「插件配置」页面本身就分别由预装的 market 插件和 config 插件提供。正是因为所有的预装插件均已配置完善，通常情况下你不需要修改预装插件的配置。随意改动插件配置、删除预装插件都可能导致 Koishi 无法正常运行。 ::: @@ -86,7 +88,7 @@ Koishi 在安装时预先配置了一些分组，而新安装的插件会放置 ### 添加更多插件 -::: tip +:::tip 通常情况下，一个插件只能同时运行一份配置。请参考 [维护多份配置](../recipe/multiple.md) 章节。 ::: @@ -98,7 +100,7 @@ Koishi 在安装时预先配置了一些分组，而新安装的插件会放置 ### 删除插件或分组 -::: warning +:::warning 注意：此操作无法被撤销，如果你想要恢复之前的配置，只能再次手动添加。请谨慎操作。 ::: diff --git a/ja-JP/plugins/adapter/wechat-official.md b/ja-JP/plugins/adapter/wechat-official.md index a81d935d675f..738c7fa072f5 100644 --- a/ja-JP/plugins/adapter/wechat-official.md +++ b/ja-JP/plugins/adapter/wechat-official.md @@ -5,7 +5,7 @@ 1. 根据 [注册流程指引](https://kf.qq.com/product/weixinmp.html#hid=87) 注册公众平台。 2. 在微信公众平台登录后，页面左侧展开「设置与开发」，进入「公众号设置」，翻至页面底部，复制 `原始 ID` 填入插件的 account 字段。 3. 页面左侧进入「基本配置」，复制 `开发者ID` 填入插件的 appId 字段，在网页上获取开发者密码填入插件的 secret 字段，设置白名单 IP。 -4. 页面下方启用服务器配置，将机器人的 `selfUrl` 值后连接 `/wechatofficial` (如 `https://example.com/wechatofficial`)，在 URL 一栏中填写；在插件配置和公众平台上填入相同的 Token；在公众平台上生成 EncodingAESKey 并填入插件的 aesKey 字段；三种消息加解密方式均可选择。 +4. 页面下方启用服务器配置，将机器人的 `selfUrl` 值后连接 `/wechat-official` (如 `https://example.com/wechat-official`)，在 URL 一栏中填写；在插件配置和公众平台上填入相同的 Token；在公众平台上生成 EncodingAESKey 并填入插件的 aesKey 字段；三种消息加解密方式均可选择。 5. 如果公众号为企业主体，且通过了微信认证，可在插件配置中启用 customerService。客服接口提供了更宽松的消息回复能力。 参考文档：[https://developers.weixin.qq.com/doc/offiaccount/Basic_Information/Access_Overview.html](https://developers.weixin.qq.com/doc/offiaccount/Basic_Information/Access_Overview.html) diff --git a/ru-RU/api/core/app.md b/ru-RU/api/core/app.md index c01b54ca7836..9ecda1457034 100644 --- a/ru-RU/api/core/app.md +++ b/ru-RU/api/core/app.md @@ -91,13 +91,13 @@ interface DelayOptions { ## 国际化设置 -### options.i18n.locales +### options.i18n.locales {#i18n-locales} - 类型：`string[]` 可用的语言列表。按照回退顺序排列。 -### options.i18n.output +### options.i18n.output {#i18n-output} - 类型：`string` @@ -106,15 +106,6 @@ interface DelayOptions { - `prefer-user`: 优先使用用户语言 - `prefer-channel`: 优先使用频道语言 -## 高级设置 - -### options.maxListeners - -- 类型：`number` -- 默认值：`64` - -每种钩子的最大数量。如果超过这个数量，Koishi 会认定为发生了内存泄漏，将产生一个警告。 - ## 请求设置 ### options.request.proxyAgent diff --git a/ru-RU/guide/basic/element.md b/ru-RU/guide/basic/element.md index e526981f01bd..a1fcc6a86567 100644 --- a/ru-RU/guide/basic/element.md +++ b/ru-RU/guide/basic/element.md @@ -165,7 +165,7 @@ Koishi 已经内置了一系列消息组件，包括： 你可以在 [这个页面](../../api/message/components.md) 了解每个组件的详细用法和适用范围。 -### 声明消息组件 +### 定义消息组件 一个消息组件本质上是一个函数，它接受三个参数： diff --git a/ru-RU/guide/develop/publish.md b/ru-RU/guide/develop/publish.md index 27ee42ad365f..670e6f105140 100644 --- a/ru-RU/guide/develop/publish.md +++ b/ru-RU/guide/develop/publish.md @@ -2,7 +2,7 @@ 为了让别人更方便地使用你编写的插件，你需要将其作为一个 npm 包进行发布。只需满足一定的规范，你的插件就能显示在 [插件市场](../../market/) 中，其他人就可以通过控制台来安装它。 -::: tip +:::tip 本节中介绍的命令行都需要在 [应用目录](./config.md#应用目录) 下运行。 ::: @@ -21,7 +21,7 @@ root └── package.json # 而不是这里 ``` -::: tip +:::tip 请注意 `package.json` 文件不是唯一的，它在应用目录和每个插件目录都会存在。请确保你修改了正确的文件。 ::: @@ -37,7 +37,7 @@ root 其中最重要的属性有两个：`name` 是要发布的包名，`version` 是包的版本号。这里的包名相比实际在插件市场中看到的插件名多了一个 `koishi-plugin-` 的前缀，这样既方便了用户安装和配置，又防止了污染命名空间。 -::: tip +:::tip 请注意：包名和版本号都具有唯一性。包名不能与其他已经发布的包相同，而同一个包的同一个版本号也只能发布一次。如果出现了包名冲突或版本号冲突，则会在之后的发布流程中出现错误提示。你可以自行根据错误提示更换包名或更新插件版本。 ::: @@ -47,7 +47,7 @@ root ### 准入条件 -::: tip +:::tip 使用模板项目创建的插件一定是符合要求的，因此你可以跳过这一节。 ::: @@ -142,7 +142,7 @@ root - **preview:** 配置为 `true` 可以让插件显示为「开发中」状态 - **hidden:** 配置为 `true` 可以让插件市场中不显示该插件 (通常情况下你不需要这么做) -::: tip +:::tip 此外，还有一些字段与 [Koishi Online](../../cookbook/practice/online.md) 的部署流程相关 (如 `browser`, `exports` 等)。由于不影响主线开发，你可以稍后再进行了解。 ::: @@ -150,20 +150,23 @@ root 编辑完上面的清单文件并 [构建源代码](./workspace.md#构建源代码) 后，你就可以公开发布你的插件了。 -::: tabs code +:::tabs code + ```npm npm run pub [...name] ``` + ```yarn yarn pub [...name] ``` + ::: - **name:** 要发布的插件列表，缺省时表示全部 (此处 `name` 不包含 `koishi-plugin-` 前缀，而是你的工作区目录名) 这将发布所有版本号发生变动的插件。 -::: tip +:::tip 从插件成功发布到进插件市场需要一定的时间 (通常在 15 分钟内)，请耐心等待。 ::: @@ -176,39 +179,46 @@ No token found and can't prompt for login when running with --non-interactive. 此时你需要在发布时使用官方镜像，具体操作如下： -::: tabs code +:::tabs code + ```npm npm run pub [...name] -- --registry https://registry.npmjs.org ``` + ```yarn yarn pub [...name] --registry https://registry.yarnpkg.com ``` + ::: 对于 Yarn v2 及以上版本，你还可以分别针对发布和安装设置不同的镜像： -::: tabs code +:::tabs code + ```yarn # 安装时使用国内镜像 yarn config set npmRegistryServer https://registry.npmmirror.com # 发布时使用官方镜像 yarn config set npmPublishRegistry https://registry.yarnpkg.com ``` -::: -: + ::: +:::: ## 更新插件版本 初始创建的插件版本号为 `1.0.0`。当你修改过插件后，你需要更新版本号才能重新发布。在应用目录运行下面的命令以更新版本号： -::: tabs code +:::tabs code + ```npm npm run bump [...name] -- [-1|-2|-3|-p|-v ] [-r] ``` + ```yarn yarn bump [...name] [-1|-2|-3|-p|-v ] [-r] ``` + ::: - **name:** 要更新的插件列表，不能为空 diff --git a/ru-RU/guide/develop/script.md b/ru-RU/guide/develop/script.md index 3172bf7c0ec9..f50cdf9faf74 100644 --- a/ru-RU/guide/develop/script.md +++ b/ru-RU/guide/develop/script.md @@ -44,7 +44,7 @@ Koishi 的命令行工具支持自动重启。当运行 Koishi 的进程崩溃 ## 开发模式 -除了 `start` 以外，模板项目还准备了名为 `dev` 的开发模式启动脚本。在应用目录运行下面的命令行可以启动开发模式： +除了 `start` 以外，模板项目还准备了名为 `dev` 的开发模式启动脚本。在应用目录运行下面的命令行可以以开发模式启动应用： ::: tabs code ```npm @@ -55,18 +55,18 @@ yarn dev ``` ::: -如你所见，`dev` 相当于在 `start` 指令的基础上添加了额外的参数和环境变量。这些参数为我们启用了额外的特性，而环境变量则能影响插件的部分配置。 +如你所见，`dev` 相当于在 `start` 指令的基础上添加了额外的参数和环境变量。这些参数为我们启用了额外的特性，而环境变量则能影响插件的部分行为。 ### TypeScript 支持 -Koishi 工作区原生地支持 TypeScript 开发。上述 `-r esbuild-register` 参数允许我们在运行时直接使用工作区插件的 TypeScript 源代码。 +Koishi 模板项目原生地支持 TypeScript 开发。上述 `-r esbuild-register` 参数允许我们在运行时直接使用工作区插件的 TypeScript 源代码。 -你也可以自行扩展更多的后缀名支持。例如，如果你更喜欢 CoffeeScript，你可以这样修改你的启动脚本为： +你也可以自行扩展更多的后缀名支持。例如，如果你更喜欢 CoffeeScript，你可以这样修改你的开发脚本为： ```json title=package.json { "scripts": { - "start": "koishi start -r coffeescript/register" + "dev": "koishi start -r coffeescript/register" }, "devDependencies": { "coffeescript": "^2.7.0" @@ -82,7 +82,7 @@ Koishi 工作区原生地支持 TypeScript 开发。上述 `-r esbuild-register` ### 模块热替换 -如果你开发着一个巨大的 Koishi 项目，可能光是加载一遍全部插件就需要好几秒了。在这种时候，像前端框架一样支持模块热替换就成了一个很棒的主意。幸运的是，Koishi 也做到了这一点！内置插件 @koishijs/plugin-hmr 实现了插件级别的热替换。每当你修改你的本地文件时，Koishi 就会尝试重载你的插件，并在控制台提醒你。 +如果你开发着一个巨大的 Koishi 项目，可能光是加载一遍全部插件就需要好几秒了。在这种时候，像前端框架一样支持模块热替换就成了一个很棒的主意。幸运的是，Koishi 也做到了这一点！内置插件 @koishijs/plugin-hmr 实现了插件级别的热替换。每当你修改你的本地文件时，Koishi 就会尝试重载你的插件，并在命令行中提醒你。 这里的行为也可以在配置文件中进行定制： diff --git a/ru-RU/guide/i18n/index.md b/ru-RU/guide/i18n/index.md index 74ad7b96284f..1a043e68a724 100644 --- a/ru-RU/guide/i18n/index.md +++ b/ru-RU/guide/i18n/index.md @@ -51,7 +51,7 @@ channel.locales = ['en-US'] ### 插值语法 -向 `session.text()` 中传入第二个参数，就可以在模板中使用单花括号插值。花括号中的内容将对应传入列表的索引。 +向 `session.text()` 中传入第二个参数，就可以在模板中使用单花括号插值。花括号 `{}` 中的内容将对应传入列表的索引。 ```ts ctx.i18n.define('zh-CN', { hello: '你好，{0}！' }) @@ -95,22 +95,84 @@ ctx.i18n.define('en-US', { hello: 'Hello, {author.name}!' }) 上述三段代码的实际效果完全相同，可以根据自己的需要进行选择。 +### 使用消息元素 + +你也可以在模板中使用 [消息元素](../basic/element.md) 语法。消息元素的属性同样使用 `{}` 进行插值： + +```ts +ctx.i18n.define('zh-CN', { hello: '你好，！' }) +ctx.i18n.define('en-US', { hello: 'Hello, !' }) +``` + +你也可以使用消息组件，例如使用 `` 组件引用其他翻译，或使用 `` 表示本地化的时间： + +```ts +ctx.i18n.define('zh-CN', { remain: '剩余时间：' }) +ctx.i18n.define('en-US', { remain: 'Time Remain: ' }) +``` + +### 条件和循环 实验性 + +我们为模板提供了一些基本的控制流语法，它参考了 [Svelte](https://svelte.dev/) 的设计 (但并未完整实现)。你可以在模板中通过 `{#if}` 和 `{#each}` 来实现条件和循环。例如，下面的代码将会渲染一个列表： + +```html +{#if list.length === 0} + 列表中没有元素。 +{:else} + {#each list as item} + {item} + {/each} +{/if} +``` + +::: tip +如果要使用这种层面的模板能力，那么你的代码已经不适合使用 `ctx.i18n.define()` 定义了。建议参考 [下一节](./translation.md) 中的做法，将不同语言的模板放入不同的文件中，以方便编辑和管理。 +::: + ## 渲染回退 -### 语言优先级 +一次完整的本地化渲染可能涉及多种不同优先级的语言和渲染路径。当首选语言的首选路径对应的翻译文本不存在时，会依次尝试使用其他翻译，这就是渲染回退。 -默认情况下的渲染优先级依次为： +### 基于语言的回退 +首先需要了解的是基于语言的回退。根据 [IETF 语言标签](https://zh.wikipedia.org/wiki/IETF%E8%AA%9E%E8%A8%80%E6%A8%99%E7%B1%A4) 规范，一个语言名称可以包含由 `-` 分隔的多个部分，例如 `de-DE-bavarian`。用户可以为应用设置 [`config.i18n.locales`](../../api/core/app.md#i18n-locales) 来指定可用的语言列表，这些语言将按照 `-` 分隔符形成一棵字典树，而 Koishi 会按照以下规则进行回退： + +1. 找到目标语言的在字典树中出现的最长前缀对应的节点； +2. 按照用户配置的优先级渲染改节点的子树所包含的语言，并将它们移除； +3. 如果此时仍有未被渲染过的语言，那么回到 1 继续遍历，直到所有语言被遍历完全。 + +例如，如果用户配置的语言列表为 `zh-CN`, `en-US`, `zh-TW`, `en-GB`，则对于不同的目标语言会生成对应的回退序列： + +- 目标语言为 `en`，回退序列为 `en`, `en-US`, `en-GB`, ``, `zh`, `zh-CN`, `zh-TW` +- 目标语言为 `zh-TW`，回退序列为 `zh-TW`, `zh`, `zh-CN`, `en`, `en-US`, `en-GB`, `` +- 目标语言为 `de-DE`，回退序列为 ``, `zh`, `zh-CN`, `zh-TW`, `en`, `en-US`, `en-GB` +- 目标语言为 `en`, `zh-TW`，回退序列为 `en`, `en-US`, `en-GB`, `zh-TW`, `zh`, `zh-CN`, `` +- 目标语言为 `zh-TW`, `en`，回退序列为 `zh-TW`, `en`, `en-US`, `en-GB`, `zh`, `zh-CN`, `` + +请注意，空字符串也被视为合法的语言，其所代表的是「没有指定语言」的情况。在实践中，空语言的使用是非常广泛的，例如当用户使用下面的代码定义指令： + +```ts +ctx.command('echo', '回声') +``` + +此时我们无法推测出「回声」的语言，因此它将会被作为路径 `commands.echo.name` 注册到空语言下。用户可以为其定义其他语言的翻译，但在未命中任何翻译时，它将回退到空语言。 + +### 基于会话的回退 + +实际的本地化渲染通常发生在消息会话中。对于一个会话，我们可以从以下几个维度来确定它的目标语言 (每个维度都可以存在多个目标语言)： + +- 会话语言 (`session.locales`) - 频道语言 (`session.channel.locales`) - 群组语言 (`session.guild.locales`) - 用户语言 (`session.user.locales`) -- 默认语言 (`app.config.i18n.locales`) -- 无语言 (`''`) -- 其他任何语言 -如果一种语言不存在对应的翻译，就会尝试使用下一种语言。如果所有语言均没有找到翻译，则会输出本身传入的渲染路径，同时输出一个警告。 +最终的目标语言将会是上述语言按顺序的并集，再根据前面介绍的规则进行回退渲染。 + +会话语言可以在一些交互场景中被直接感知得到。例如，用户如果在聊天平台中已经设置了语言偏好 (并且聊天平台提供了相应的 API)，则相关的设置可以通过适配器插件提供给会话。又比如，当开发者为一个指令设置了多种语言的别名时，可以为这些别名手动指定语言，当用户调用某一个别名时，Koishi 会按照设定好的语言来回答。 -### 路径回退 +用户语言与频道、群组语言的优先关系可以通过 [`config.i18n.output`](../../api/core/app.md#i18n-output) 来指定。默认情况下频道和群组的语言优先级高于用户语言，但是你可以将其设置为 `prefer-user` 来改变这一行为。 + +### 基于路径的回退 你也可以配置多个路径，将会按照顺序查找翻译，直到找到一个翻译为止。 @@ -127,3 +189,9 @@ session.text(['foo', 'bar']) ```ts session.text(['foo', '']) ``` + +### 用户侧覆写 + +用户可以通过 [locales](../../plugins/console/locales.md) 插件提供本地翻译，且这些翻译的优先级高于插件自身提供的翻译。可以认为，从用户提供的翻译到插件提供的翻译，也是一种回退关系。 + +关于用户侧覆写的更多信息，请参见 [入门 > 深入定制机器人](../../manual/usage/customize.md)。 diff --git a/ru-RU/manual/usage/market.md b/ru-RU/manual/usage/market.md index 9465b4406581..ac80c47f5031 100644 --- a/ru-RU/manual/usage/market.md +++ b/ru-RU/manual/usage/market.md @@ -1,10 +1,12 @@ -- - - -prev: text: 选择安装方式 link: /zh-CN/manual/starter/ -- - - +--- +prev: + text: 选择安装方式 + link: /ru-RU/manual/starter/ +--- # 安装和配置插件 -::: tip +:::tip 本节将介绍「插件市场」「插件配置」和「依赖管理」页面的使用方法。 ::: @@ -33,7 +35,7 @@ Koishi 的一个核心特性是强大的控制台。控制台是一个对用户 ## 安装插件 -::: warning +:::warning Koishi 不对非官方插件的安全性做任何保证。请不要随意下载来源不明的插件，因为它们可能导致 Koishi 无法运行，甚至更严重的后果。如果你下载插件后遇到了问题，可以前往用户群或论坛进行反馈。此外，部分插件带有「不安全」标识，安装此类插件将不会受到官方群内的支持。 ::: @@ -57,7 +59,7 @@ Koishi 不会自动启用刚刚安装的插件，你需要手动配置并启用 ## 配置插件 -::: warning +:::warning 在配置插件的过程中，请大家记住这个原则：**如无必要，勿动配置**。Koishi 在设计上兼顾了扩展性和实用性，许多基础功能是以预装插件的形式提供的。前面我们已经用到的「插件市场」和「插件配置」页面本身就分别由预装的 market 插件和 config 插件提供。正是因为所有的预装插件均已配置完善，通常情况下你不需要修改预装插件的配置。随意改动插件配置、删除预装插件都可能导致 Koishi 无法正常运行。 ::: @@ -86,7 +88,7 @@ Koishi 在安装时预先配置了一些分组，而新安装的插件会放置 ### 添加更多插件 -::: tip +:::tip 通常情况下，一个插件只能同时运行一份配置。请参考 [维护多份配置](../recipe/multiple.md) 章节。 ::: @@ -98,7 +100,7 @@ Koishi 在安装时预先配置了一些分组，而新安装的插件会放置 ### 删除插件或分组 -::: warning +:::warning 注意：此操作无法被撤销，如果你想要恢复之前的配置，只能再次手动添加。请谨慎操作。 ::: diff --git a/ru-RU/plugins/adapter/wechat-official.md b/ru-RU/plugins/adapter/wechat-official.md index a81d935d675f..738c7fa072f5 100644 --- a/ru-RU/plugins/adapter/wechat-official.md +++ b/ru-RU/plugins/adapter/wechat-official.md @@ -5,7 +5,7 @@ 1. 根据 [注册流程指引](https://kf.qq.com/product/weixinmp.html#hid=87) 注册公众平台。 2. 在微信公众平台登录后，页面左侧展开「设置与开发」，进入「公众号设置」，翻至页面底部，复制 `原始 ID` 填入插件的 account 字段。 3. 页面左侧进入「基本配置」，复制 `开发者ID` 填入插件的 appId 字段，在网页上获取开发者密码填入插件的 secret 字段，设置白名单 IP。 -4. 页面下方启用服务器配置，将机器人的 `selfUrl` 值后连接 `/wechatofficial` (如 `https://example.com/wechatofficial`)，在 URL 一栏中填写；在插件配置和公众平台上填入相同的 Token；在公众平台上生成 EncodingAESKey 并填入插件的 aesKey 字段；三种消息加解密方式均可选择。 +4. 页面下方启用服务器配置，将机器人的 `selfUrl` 值后连接 `/wechat-official` (如 `https://example.com/wechat-official`)，在 URL 一栏中填写；在插件配置和公众平台上填入相同的 Token；在公众平台上生成 EncodingAESKey 并填入插件的 aesKey 字段；三种消息加解密方式均可选择。 5. 如果公众号为企业主体，且通过了微信认证，可在插件配置中启用 customerService。客服接口提供了更宽松的消息回复能力。 参考文档：[https://developers.weixin.qq.com/doc/offiaccount/Basic_Information/Access_Overview.html](https://developers.weixin.qq.com/doc/offiaccount/Basic_Information/Access_Overview.html) diff --git a/zh-TW/api/core/app.md b/zh-TW/api/core/app.md index 8ac6ce62e26e..9ecda1457034 100644 --- a/zh-TW/api/core/app.md +++ b/zh-TW/api/core/app.md @@ -91,13 +91,13 @@ interface DelayOptions { ## 国际化设置 -### options.i18n.locales +### options.i18n.locales {#i18n-locales} - 类型：`string[]` 可用的语言列表。按照回退顺序排列。 -### options.i18n.output +### options.i18n.output {#i18n-output} - 类型：`string` @@ -106,15 +106,6 @@ interface DelayOptions { - `prefer-user`: 优先使用用户语言 - `prefer-channel`: 优先使用频道语言 -## 高級設定 - -### options.maxListeners - -- 类型：`number` -- 默认值：`64` - -每种钩子的最大数量。如果超过这个数量，Koishi 会认定为发生了内存泄漏，将产生一个警告。 - ## 请求设置 ### options.request.proxyAgent diff --git a/zh-TW/guide/basic/element.md b/zh-TW/guide/basic/element.md index defc820bc253..a7d7d60e05da 100644 --- a/zh-TW/guide/basic/element.md +++ b/zh-TW/guide/basic/element.md @@ -165,7 +165,7 @@ Koishi 已经内置了一系列消息组件，包括： 你可以在 [这个页面](../../api/message/components.md) 了解每个组件的详细用法和适用范围。 -### 声明消息组件 +### 定义消息组件 一个消息组件本质上是一个函数，它接受三个参数： diff --git a/zh-TW/guide/develop/publish.md b/zh-TW/guide/develop/publish.md index 27ee42ad365f..274372424ba9 100644 --- a/zh-TW/guide/develop/publish.md +++ b/zh-TW/guide/develop/publish.md @@ -1,8 +1,8 @@ -# 发布插件 +# 釋出外掛 为了让别人更方便地使用你编写的插件，你需要将其作为一个 npm 包进行发布。只需满足一定的规范，你的插件就能显示在 [插件市场](../../market/) 中，其他人就可以通过控制台来安装它。 -::: tip +:::tip 本节中介绍的命令行都需要在 [应用目录](./config.md#应用目录) 下运行。 ::: @@ -21,7 +21,7 @@ root └── package.json # 而不是这里 ``` -::: tip +:::tip 请注意 `package.json` 文件不是唯一的，它在应用目录和每个插件目录都会存在。请确保你修改了正确的文件。 ::: @@ -37,7 +37,7 @@ root 其中最重要的属性有两个：`name` 是要发布的包名，`version` 是包的版本号。这里的包名相比实际在插件市场中看到的插件名多了一个 `koishi-plugin-` 的前缀，这样既方便了用户安装和配置，又防止了污染命名空间。 -::: tip +:::tip 请注意：包名和版本号都具有唯一性。包名不能与其他已经发布的包相同，而同一个包的同一个版本号也只能发布一次。如果出现了包名冲突或版本号冲突，则会在之后的发布流程中出现错误提示。你可以自行根据错误提示更换包名或更新插件版本。 ::: @@ -47,7 +47,7 @@ root ### 准入条件 -::: tip +:::tip 使用模板项目创建的插件一定是符合要求的，因此你可以跳过这一节。 ::: @@ -142,28 +142,31 @@ root - **preview:** 配置为 `true` 可以让插件显示为「开发中」状态 - **hidden:** 配置为 `true` 可以让插件市场中不显示该插件 (通常情况下你不需要这么做) -::: tip +:::tip 此外，还有一些字段与 [Koishi Online](../../cookbook/practice/online.md) 的部署流程相关 (如 `browser`, `exports` 等)。由于不影响主线开发，你可以稍后再进行了解。 ::: -## 发布插件 +## 釋出外掛 编辑完上面的清单文件并 [构建源代码](./workspace.md#构建源代码) 后，你就可以公开发布你的插件了。 -::: tabs code +:::tabs code + ```npm npm run pub [...name] ``` + ```yarn yarn pub [...name] ``` + ::: - **name:** 要发布的插件列表，缺省时表示全部 (此处 `name` 不包含 `koishi-plugin-` 前缀，而是你的工作区目录名) 这将发布所有版本号发生变动的插件。 -::: tip +:::tip 从插件成功发布到进插件市场需要一定的时间 (通常在 15 分钟内)，请耐心等待。 ::: @@ -176,39 +179,46 @@ No token found and can't prompt for login when running with --non-interactive. 此时你需要在发布时使用官方镜像，具体操作如下： -::: tabs code +:::tabs code + ```npm npm run pub [...name] -- --registry https://registry.npmjs.org ``` + ```yarn yarn pub [...name] --registry https://registry.yarnpkg.com ``` + ::: 对于 Yarn v2 及以上版本，你还可以分别针对发布和安装设置不同的镜像： -::: tabs code +:::tabs code + ```yarn # 安装时使用国内镜像 yarn config set npmRegistryServer https://registry.npmmirror.com # 发布时使用官方镜像 yarn config set npmPublishRegistry https://registry.yarnpkg.com ``` -::: -: + ::: +:::: ## 更新插件版本 初始创建的插件版本号为 `1.0.0`。当你修改过插件后，你需要更新版本号才能重新发布。在应用目录运行下面的命令以更新版本号： -::: tabs code +:::tabs code + ```npm npm run bump [...name] -- [-1|-2|-3|-p|-v ] [-r] ``` + ```yarn yarn bump [...name] [-1|-2|-3|-p|-v ] [-r] ``` + ::: - **name:** 要更新的插件列表，不能为空 diff --git a/zh-TW/guide/develop/script.md b/zh-TW/guide/develop/script.md index 3172bf7c0ec9..f50cdf9faf74 100644 --- a/zh-TW/guide/develop/script.md +++ b/zh-TW/guide/develop/script.md @@ -44,7 +44,7 @@ Koishi 的命令行工具支持自动重启。当运行 Koishi 的进程崩溃 ## 开发模式 -除了 `start` 以外，模板项目还准备了名为 `dev` 的开发模式启动脚本。在应用目录运行下面的命令行可以启动开发模式： +除了 `start` 以外，模板项目还准备了名为 `dev` 的开发模式启动脚本。在应用目录运行下面的命令行可以以开发模式启动应用： ::: tabs code ```npm @@ -55,18 +55,18 @@ yarn dev ``` ::: -如你所见，`dev` 相当于在 `start` 指令的基础上添加了额外的参数和环境变量。这些参数为我们启用了额外的特性，而环境变量则能影响插件的部分配置。 +如你所见，`dev` 相当于在 `start` 指令的基础上添加了额外的参数和环境变量。这些参数为我们启用了额外的特性，而环境变量则能影响插件的部分行为。 ### TypeScript 支持 -Koishi 工作区原生地支持 TypeScript 开发。上述 `-r esbuild-register` 参数允许我们在运行时直接使用工作区插件的 TypeScript 源代码。 +Koishi 模板项目原生地支持 TypeScript 开发。上述 `-r esbuild-register` 参数允许我们在运行时直接使用工作区插件的 TypeScript 源代码。 -你也可以自行扩展更多的后缀名支持。例如，如果你更喜欢 CoffeeScript，你可以这样修改你的启动脚本为： +你也可以自行扩展更多的后缀名支持。例如，如果你更喜欢 CoffeeScript，你可以这样修改你的开发脚本为： ```json title=package.json { "scripts": { - "start": "koishi start -r coffeescript/register" + "dev": "koishi start -r coffeescript/register" }, "devDependencies": { "coffeescript": "^2.7.0" @@ -82,7 +82,7 @@ Koishi 工作区原生地支持 TypeScript 开发。上述 `-r esbuild-register` ### 模块热替换 -如果你开发着一个巨大的 Koishi 项目，可能光是加载一遍全部插件就需要好几秒了。在这种时候，像前端框架一样支持模块热替换就成了一个很棒的主意。幸运的是，Koishi 也做到了这一点！内置插件 @koishijs/plugin-hmr 实现了插件级别的热替换。每当你修改你的本地文件时，Koishi 就会尝试重载你的插件，并在控制台提醒你。 +如果你开发着一个巨大的 Koishi 项目，可能光是加载一遍全部插件就需要好几秒了。在这种时候，像前端框架一样支持模块热替换就成了一个很棒的主意。幸运的是，Koishi 也做到了这一点！内置插件 @koishijs/plugin-hmr 实现了插件级别的热替换。每当你修改你的本地文件时，Koishi 就会尝试重载你的插件，并在命令行中提醒你。 这里的行为也可以在配置文件中进行定制： diff --git a/zh-TW/guide/i18n/index.md b/zh-TW/guide/i18n/index.md index 74ad7b96284f..1a043e68a724 100644 --- a/zh-TW/guide/i18n/index.md +++ b/zh-TW/guide/i18n/index.md @@ -51,7 +51,7 @@ channel.locales = ['en-US'] ### 插值语法 -向 `session.text()` 中传入第二个参数，就可以在模板中使用单花括号插值。花括号中的内容将对应传入列表的索引。 +向 `session.text()` 中传入第二个参数，就可以在模板中使用单花括号插值。花括号 `{}` 中的内容将对应传入列表的索引。 ```ts ctx.i18n.define('zh-CN', { hello: '你好，{0}！' }) @@ -95,22 +95,84 @@ ctx.i18n.define('en-US', { hello: 'Hello, {author.name}!' }) 上述三段代码的实际效果完全相同，可以根据自己的需要进行选择。 +### 使用消息元素 + +你也可以在模板中使用 [消息元素](../basic/element.md) 语法。消息元素的属性同样使用 `{}` 进行插值： + +```ts +ctx.i18n.define('zh-CN', { hello: '你好，！' }) +ctx.i18n.define('en-US', { hello: 'Hello, !' }) +``` + +你也可以使用消息组件，例如使用 `` 组件引用其他翻译，或使用 `` 表示本地化的时间： + +```ts +ctx.i18n.define('zh-CN', { remain: '剩余时间：' }) +ctx.i18n.define('en-US', { remain: 'Time Remain: ' }) +``` + +### 条件和循环 实验性 + +我们为模板提供了一些基本的控制流语法，它参考了 [Svelte](https://svelte.dev/) 的设计 (但并未完整实现)。你可以在模板中通过 `{#if}` 和 `{#each}` 来实现条件和循环。例如，下面的代码将会渲染一个列表： + +```html +{#if list.length === 0} + 列表中没有元素。 +{:else} + {#each list as item} + {item} + {/each} +{/if} +``` + +::: tip +如果要使用这种层面的模板能力，那么你的代码已经不适合使用 `ctx.i18n.define()` 定义了。建议参考 [下一节](./translation.md) 中的做法，将不同语言的模板放入不同的文件中，以方便编辑和管理。 +::: + ## 渲染回退 -### 语言优先级 +一次完整的本地化渲染可能涉及多种不同优先级的语言和渲染路径。当首选语言的首选路径对应的翻译文本不存在时，会依次尝试使用其他翻译，这就是渲染回退。 -默认情况下的渲染优先级依次为： +### 基于语言的回退 +首先需要了解的是基于语言的回退。根据 [IETF 语言标签](https://zh.wikipedia.org/wiki/IETF%E8%AA%9E%E8%A8%80%E6%A8%99%E7%B1%A4) 规范，一个语言名称可以包含由 `-` 分隔的多个部分，例如 `de-DE-bavarian`。用户可以为应用设置 [`config.i18n.locales`](../../api/core/app.md#i18n-locales) 来指定可用的语言列表，这些语言将按照 `-` 分隔符形成一棵字典树，而 Koishi 会按照以下规则进行回退： + +1. 找到目标语言的在字典树中出现的最长前缀对应的节点； +2. 按照用户配置的优先级渲染改节点的子树所包含的语言，并将它们移除； +3. 如果此时仍有未被渲染过的语言，那么回到 1 继续遍历，直到所有语言被遍历完全。 + +例如，如果用户配置的语言列表为 `zh-CN`, `en-US`, `zh-TW`, `en-GB`，则对于不同的目标语言会生成对应的回退序列： + +- 目标语言为 `en`，回退序列为 `en`, `en-US`, `en-GB`, ``, `zh`, `zh-CN`, `zh-TW` +- 目标语言为 `zh-TW`，回退序列为 `zh-TW`, `zh`, `zh-CN`, `en`, `en-US`, `en-GB`, `` +- 目标语言为 `de-DE`，回退序列为 ``, `zh`, `zh-CN`, `zh-TW`, `en`, `en-US`, `en-GB` +- 目标语言为 `en`, `zh-TW`，回退序列为 `en`, `en-US`, `en-GB`, `zh-TW`, `zh`, `zh-CN`, `` +- 目标语言为 `zh-TW`, `en`，回退序列为 `zh-TW`, `en`, `en-US`, `en-GB`, `zh`, `zh-CN`, `` + +请注意，空字符串也被视为合法的语言，其所代表的是「没有指定语言」的情况。在实践中，空语言的使用是非常广泛的，例如当用户使用下面的代码定义指令： + +```ts +ctx.command('echo', '回声') +``` + +此时我们无法推测出「回声」的语言，因此它将会被作为路径 `commands.echo.name` 注册到空语言下。用户可以为其定义其他语言的翻译，但在未命中任何翻译时，它将回退到空语言。 + +### 基于会话的回退 + +实际的本地化渲染通常发生在消息会话中。对于一个会话，我们可以从以下几个维度来确定它的目标语言 (每个维度都可以存在多个目标语言)： + +- 会话语言 (`session.locales`) - 频道语言 (`session.channel.locales`) - 群组语言 (`session.guild.locales`) - 用户语言 (`session.user.locales`) -- 默认语言 (`app.config.i18n.locales`) -- 无语言 (`''`) -- 其他任何语言 -如果一种语言不存在对应的翻译，就会尝试使用下一种语言。如果所有语言均没有找到翻译，则会输出本身传入的渲染路径，同时输出一个警告。 +最终的目标语言将会是上述语言按顺序的并集，再根据前面介绍的规则进行回退渲染。 + +会话语言可以在一些交互场景中被直接感知得到。例如，用户如果在聊天平台中已经设置了语言偏好 (并且聊天平台提供了相应的 API)，则相关的设置可以通过适配器插件提供给会话。又比如，当开发者为一个指令设置了多种语言的别名时，可以为这些别名手动指定语言，当用户调用某一个别名时，Koishi 会按照设定好的语言来回答。 -### 路径回退 +用户语言与频道、群组语言的优先关系可以通过 [`config.i18n.output`](../../api/core/app.md#i18n-output) 来指定。默认情况下频道和群组的语言优先级高于用户语言，但是你可以将其设置为 `prefer-user` 来改变这一行为。 + +### 基于路径的回退 你也可以配置多个路径，将会按照顺序查找翻译，直到找到一个翻译为止。 @@ -127,3 +189,9 @@ session.text(['foo', 'bar']) ```ts session.text(['foo', '']) ``` + +### 用户侧覆写 + +用户可以通过 [locales](../../plugins/console/locales.md) 插件提供本地翻译，且这些翻译的优先级高于插件自身提供的翻译。可以认为，从用户提供的翻译到插件提供的翻译，也是一种回退关系。 + +关于用户侧覆写的更多信息，请参见 [入门 > 深入定制机器人](../../manual/usage/customize.md)。 diff --git a/zh-TW/manual/usage/market.md b/zh-TW/manual/usage/market.md index f9e460896ff6..7a7f60988b10 100644 --- a/zh-TW/manual/usage/market.md +++ b/zh-TW/manual/usage/market.md @@ -1,11 +1,13 @@ -- - - -prev: text: 选择安装方式 link: /zh-CN/manual/starter/ -- - - +--- +prev: + text: 選擇安裝方式 + link: /zh-TW/manual/starter/ +--- # 安裝和配置外掛 -::: tip -本節將介紹「外掛市場」「外掛配置」和「依賴管理」頁面的使用方法。 +:::tip +本节将介绍「插件市场」「插件配置」和「依赖管理」页面的使用方法。 ::: Koishi 的一個核心特性是強大的控制檯。控制台是一个对用户友好的图形界面，封装了 Koishi 的绝大多数功能： @@ -17,7 +19,7 @@ Koishi 的一個核心特性是強大的控制檯。控制台是一个对用户 - 狀態監控、資料統計 - 檢視日誌 -本节中我们将以 [echo](../../plugins/common/echo.md) 插件为例来演示插件的安装与配置。echo 外掛註冊了一個名為 `echo` 的指令，呼叫此指令可以將輸入原樣輸出給使用者。 +本节中我们将以 [echo](../../plugins/common/echo.md) 插件为例来演示插件的安装与配置。echo 插件注册了一个名为 `echo` 的指令，调用此指令可以将输入原样输出给用户。 ## 認識控制檯 @@ -33,11 +35,11 @@ Koishi 的一個核心特性是強大的控制檯。控制台是一个对用户 ## 安裝外掛 -::: warning -Koishi 不對非官方外掛的安全性做任何保證。請不要隨意下載來源不明的外掛，因為它們可能導致 Koishi 無法執行，甚至更嚴重的後果。如果你下載外掛後遇到了問題，可以前往使用者群或論壇進行反饋。此外，部分外掛帶有「不安全」標識，安裝此類外掛將不會受到官方群內的支援。 +:::warning +Koishi 不对非官方插件的安全性做任何保证。請不要隨意下載來源不明的外掛，因為它們可能導致 Koishi 無法執行，甚至更嚴重的後果。如果你下載外掛後遇到了問題，可以前往使用者群或論壇進行反饋。此外，部分外掛帶有「不安全」標識，安裝此類外掛將不會受到官方群內的支援。 ::: -前往「外掛市場」頁面，你將在這裡看到所有可下載的外掛。在搜尋框中輸入 `echo`，找到我們想要的外掛，點選「新增」按鈕，然後在彈出的對話方塊中點選「安裝」。等待片刻，外掛就已經安裝成功了。 +前往「外掛市場」頁面，你將在這裡看到所有可下載的外掛。在搜索框中输入 `echo`，找到我们想要的插件，点击「添加」按钮，然后在弹出的对话框中点击「安装」。等待片刻，外掛就已經安裝成功了。 ![select-version](/manual/console/select-version.light.webp) {.light-only} @@ -57,8 +59,8 @@ Koishi 不會自動啟用剛剛安裝的外掛，你需要手動配置並啟用 ## 配置外掛 -::: warning -在配置外掛的過程中，請大家記住這個原則：**如無必要，勿動配置**。Koishi 在設計上兼顧了擴充套件性和實用性，許多基礎功能是以預裝外掛的形式提供的。前面我們已經用到的「外掛市場」和「外掛配置」頁面本身就分別由預裝的 market 外掛和 config 外掛提供。正是因為所有的預裝外掛均已配置完善，通常情況下你不需要修改預裝外掛的配置。隨意改動外掛配置、刪除預裝外掛都可能導致 Koishi 無法正常執行。 +:::warning +在配置插件的过程中，请大家记住这个原则：**如无必要，勿动配置**。Koishi 在設計上兼顧了擴充套件性和實用性，許多基礎功能是以預裝外掛的形式提供的。前面我們已經用到的「外掛市場」和「外掛配置」頁面本身就分別由預裝的 market 外掛和 config 外掛提供。正是因為所有的預裝外掛均已配置完善，通常情況下你不需要修改預裝外掛的配置。隨意改動外掛配置、刪除預裝外掛都可能導致 Koishi 無法正常執行。 ::: 雖然 echo 外掛沒有需要配置的地方，但更復雜的外掛則通常會提供各種配置項，允許使用者控制外掛的行為。下圖展示了 novelai 外掛的配置介面。 @@ -69,8 +71,8 @@ Koishi 不會自動啟用剛剛安裝的外掛，你需要手動配置並啟用 在這個介面中，我們可以看到許多配置項。其中你需要注意： -- 必选但尚未填入的配置项会在左侧呈现 红色 的提示条，只有正确填写配置才能启动插件。 -- 已修改但未保存的配置项会在左侧呈现 紫色 的提示条，点击「启用插件」或「保存配置」按钮后会保存配置；如果你想撤销这些改动，可以在配置名称旁的小三角处呼出菜单，选择「撤销更改」使该配置恢复到上次保存时的状态。 +- 必選但尚未填入的配置項會在左側呈現 紅色 的提示條，只有正確填寫配置才能啟動外掛。 +- 已修改但未儲存的配置項會在左側呈現 紫色 的提示條，點選「啟用外掛」或「儲存配置」按鈕後會儲存配置；如果你想撤銷這些改動，可以在配置名稱旁的小三角處撥出選單，選擇「撤銷更改」使該配置恢復到上次儲存時的狀態。 ## 管理外掛 @@ -86,8 +88,8 @@ Koishi 在安裝時預先配置了一些分組，而新安裝的外掛會放置 ### 新增更多外掛 -::: tip -通常情況下，一個外掛只能同時執行一份配置。請參考 [維護多份配置](../recipe/multiple.md) 章節。 +:::tip +通常情况下，一个插件只能同时运行一份配置。请参考 [维护多份配置](../recipe/multiple.md) 章节。 ::: 如果某個已安裝的外掛並未顯示在外掛列表中，你也可以手動新增它。在「全域性配置」或任意分組介面中，點選右上角的「新增外掛」將會彈出對話方塊。在對話方塊中點選要新增的外掛，即可建立一份未啟用的外掛配置。 @@ -98,8 +100,8 @@ Koishi 在安裝時預先配置了一些分組，而新安裝的外掛會放置 ### 刪除外掛或分組 -::: warning -注意：此操作無法被撤銷，如果你想要恢復之前的配置，只能再次手動新增。請謹慎操作。 +:::warning +注意：此操作无法被撤销，如果你想要恢复之前的配置，只能再次手动添加。請謹慎操作。 ::: 在任何外掛的配置介面點選右上角的「刪除外掛」可刪除這份配置。與之類似，在分組的配置介面點選右上角的「刪除分組」可刪除這個分組。刪除分組時，分組內的所有外掛也會一併刪除。 diff --git a/zh-TW/plugins/adapter/wechat-official.md b/zh-TW/plugins/adapter/wechat-official.md index a81d935d675f..738c7fa072f5 100644 --- a/zh-TW/plugins/adapter/wechat-official.md +++ b/zh-TW/plugins/adapter/wechat-official.md @@ -5,7 +5,7 @@ 1. 根据 [注册流程指引](https://kf.qq.com/product/weixinmp.html#hid=87) 注册公众平台。 2. 在微信公众平台登录后，页面左侧展开「设置与开发」，进入「公众号设置」，翻至页面底部，复制 `原始 ID` 填入插件的 account 字段。 3. 页面左侧进入「基本配置」，复制 `开发者ID` 填入插件的 appId 字段，在网页上获取开发者密码填入插件的 secret 字段，设置白名单 IP。 -4. 页面下方启用服务器配置，将机器人的 `selfUrl` 值后连接 `/wechatofficial` (如 `https://example.com/wechatofficial`)，在 URL 一栏中填写；在插件配置和公众平台上填入相同的 Token；在公众平台上生成 EncodingAESKey 并填入插件的 aesKey 字段；三种消息加解密方式均可选择。 +4. 页面下方启用服务器配置，将机器人的 `selfUrl` 值后连接 `/wechat-official` (如 `https://example.com/wechat-official`)，在 URL 一栏中填写；在插件配置和公众平台上填入相同的 Token；在公众平台上生成 EncodingAESKey 并填入插件的 aesKey 字段；三种消息加解密方式均可选择。 5. 如果公众号为企业主体，且通过了微信认证，可在插件配置中启用 customerService。客服接口提供了更宽松的消息回复能力。 参考文档：[https://developers.weixin.qq.com/doc/offiaccount/Basic_Information/Access_Overview.html](https://developers.weixin.qq.com/doc/offiaccount/Basic_Information/Access_Overview.html)