i18n: update translations (#92)

de-DE/api/message/elements.md

@@ -282,5 +282,5 @@ hello<message/>world
 |    `nickname`    |        ⭘        |  ~   |        ✓        |    ~    |    ~     |
 |     `avatar`     |        ⭘        |  ~   |        ~        |    ~    |    ~     |
 
-- [1]: 基于 Webhook 功能，目前暂未支持
+- [1]: 基于 webhook 功能，目前暂未支持
 - [2]: 仅限 forward 和 quote 消息

de-DE/guide/adapter/bot.md

@@ -1,9 +1,5 @@
 # 实现机器人
 
-::: danger 注意
-此页文档正在施工，其中的内容可能不是最新。
-:::
-
 `Bot` 对应着由 Koishi 操纵的聊天平台机器人账号。其上封装了一系列方法，用于发送消息、获取频道信息等操作。要实现一个聊天平台的 `Bot` 类，只需要实现这些方法即可。
 
 ## 通用接口
@@ -55,10 +51,13 @@ class ReplBot extends Bot {
 (bot as DiscordBot).internal.getGuild(guildId)
 ```
 
-另一种方法是在有 `Session` 对象的环境中，直接通过 `session[platform]` 就可以访问到对应适配器的内部接口。这种方式的好处是无需类型断言：
+另一种方法是在有 `Session` 对象的环境中，直接通过 `session[platform]` 就可以访问到对应适配器的内部接口。这种方式不仅无需类型断言，并且能够直接访问到会话的原始数据：
 
 ```ts
 session.discord.getGuild(guildId)
+
+session.discord.t // 原始事件名称
+session.discord.d // 原始事件数据
 ```
 
 你甚至还可以用这种方式对多种适配器提供定制化的支持：
@@ -87,8 +86,6 @@ const decodeGuild = (data: Discord.Guild): Universal.Guild => ({
 })
 
 class DiscordBot extends Bot {
-  internal: Internal
-
   constructor(ctx: Context, config: Config) {
     super(ctx, config)
     this.internal = new Internal()
@@ -110,4 +107,117 @@ class DiscordBot extends Bot {
 
 在上面这段代码中，Discord 平台与 Koishi 都定义了一个 `Guild` 接口。前者包含了更多信息，但由于它们的关键字段不完全相同，因此并不能直接把请求的结果作为通用方法的返回值。
 
-为此，我们实现了一个 `decodeGuild` 函数，将 Discord 的数据结构转换为 Koishi 的通用数据结构。与此同时，我们把网络请求的部分放在 `internal` 中实现，并在 `Bot` 类中直接调用内部方法。可以看到，这样编写出来的代码结构相比直接把请求放在 `Bot` 类中要清晰得多。
+为此，我们实现了一个 `decodeGuild` 函数，将 Discord 的数据结构转换为 Koishi 的通用数据结构。与此同时，我们把网络请求的部分放在 `Internal` 类中实现，并在 `Bot` 类中直接调用内部方法。可以看到，这样编写出来的代码结构相比直接把请求放在 `Bot` 类中要清晰得多。
+
+## 实现内部接口
+
+不同的平台由于其 API 的差异性，`Internal` 类的实现方式也会有所不同。对于简单的平台，你完全可以手动实现每一个内部接口 (甚至可以不实现 `Internal` 类，就像 REPL 适配器那样)；但如果平台本身就有上百个 API，手写每一个内部接口显然既费时又啰嗦。因此，Koishi 提供了一些技巧以简化你的适配工作。我们这里仍然以 Discord 为例。
+
+### 使用 HTTP 服务
+
+让我们进一步完成上面的代码。Discord 的 API 是 Restful 的，并且需要 `Authorization` 请求头。我们通过在 `Internal` 类中传入一个 `http` 对象简化网络请求的写法：
+
+```ts{5,9,17-20}
+class Internal {
+  constructor(private http: Quester) {}
+
+  getGuild(guildId: string) {
+    return this.http.get(`/guilds/${guildId}`)
+  }
+
+  getCurrentUserGuilds() {
+    return this.http.get('/users/@me/guilds')
+  }
+}
+
+class DiscordBot extends Bot {
+  constructor(ctx: Context, config: Config) {
+    super(ctx, config)
+    const http = ctx.http.extend({
+      endpoint: 'https://discord.com/api/v10',
+      headers: {
+        Authorization: `Bot ${config.token}`,
+      },
+    })
+    this.internal = new Internal(http)
+  }
+}
+```
+
+[`ctx.http`](../../api/service/http.md) 是 Koishi 的内置服务，其上封装了一套基于 [axios](https://github.com/axios/axios) 的网络请求 API。这里，我们使用 `ctx.http.extend()` 方法创建了一个新的 `Quester` 实例，其上的请求会继承传入的配置。这样我们就无需每次请求都写一遍请求头了。
+
+### 反射网络请求
+
+在 `Quester` 的帮助下，我们甚至可以直接对网络请求进行反射，从而自动生成内部接口。
+
+```ts
+class Internal {
+  constructor(private http: Quester) {}
+
+  static define(path: string, methods: Partial<Record<Quester.Method, string | string[]>>) {
+    for (const key in methods) {
+      const method = key as Quester.Method
+      for (const name of makeArray(methods[method])) {
+        this.prototype[name] = async function (this: Internal, ...args: any[]) {
+          // 将参数填入路径中
+          const url = path.replace(/\{([^}]+)\}/g, () => {
+            if (!args.length) throw new TypeError('missing arguments')
+            return args.shift()
+          })
+          return this.http(method, url)
+        }
+      }
+    }
+  }
+}
+```
+
+有了这个 `Internal.define()` 方法，我们就可以批量定义内部接口了：
+
+```ts
+Internal.define('/guilds/{guild.id}', {
+  GET: 'getGuild',
+  PATCH: 'modifyGuild',
+  DELETE: 'deleteGuild',
+})
+
+Internal.define('/users/@me/guilds', {
+  GET: 'getCurrentUserGuilds',
+})
+```
+
+最后别忘了通过类型合并的方式，将这些方法添加到 `Internal` 类型上：
+
+```ts
+interface Internal {
+  getGuild(guildId: string): Promise<Discord.Guild>
+  modifyGuild(guildId: string, data: Discord.PartialGuild): Promise<Discord.Guild>
+  deleteGuild(guildId: string): Promise<void>
+  getCurrentUserGuilds(): Promise<Discord.Guild[]>
+}
+```
+
+上面的代码还没有考虑请求体和异常处理等问题，如果想要深入了解，可以阅读 Discord 适配器的 [源码](https://github.com/satorijs/satori/blob/master/adapters/discord/src/types/internal.ts)。事实上，Discord 的接口已经是比较复杂的了。相信有了这些技巧的加持，其他平台的适配器你一定也能手到擒来。
+
+### 注入会话属性
+
+在本节的最后，我们还有一点伏笔没有回收。我们还需要在 `Session` 对象中注入 `discord` 属性，以便插件能够访问到内部接口：
+
+```ts
+declare module 'koishi' {
+  interface Session {
+    discord?: Internal & Payload
+  }
+}
+```
+
+这里的 `Internal` 对应着内部接口，而 `Payload` 则对应着原始事件数据。当构造会话对象时 (将在下一节具体介绍)，我们需要将这些数据注入到 `Session` 对象中：
+
+```ts
+// 平台注入的属性不建议设置为 enumerable
+Object.defineProperty(session, 'discord', {
+  // 将 Internal 作为原型，将 Payload 作为实例属性
+  value: Object.assign(Object.create(internal), payload),
+  writable: true,
+})
+```

de-DE/guide/adapter/index.md

@@ -1,9 +1,5 @@
 # 基本示例
 
-::: tip
-本章将介绍如何开发适配器。如果你没有适配聊天平台的需求，可以直接跳过本章。
-:::
-
 ::: tip
 在学习本章之前，建议先完整阅读 [入门 > 跨平台](../../manual/usage/platform.md)。
 :::

de-DE/guide/basic/command.md

@@ -1,7 +1,7 @@
 # 指令开发
 
 ::: tip
-在学习本节之前，建议先阅读 [入门 > 指令系统](../../manual/usage/command.md)。
+在学习本节之前，建议先完整阅读 [入门 > 指令系统](../../manual/usage/command.md)。
 :::
 
 正如我们在入门篇中介绍的那样，一个 Koishi 机器人的绝大部分功能都是通过指令提供给用户的。Koishi 的指令系统能够高效地处理大量消息的并发调用，同时还提供了快捷方式、调用前缀、权限管理、速率限制、本地化等大量功能。因此，只需掌握指令开发并编写少量代码就可以轻松应对各类用户需求。

de-DE/guide/console/index.md

@@ -1,9 +1,5 @@
 # 扩展控制台
 
-::: tip
-本章将介绍如何开发控制台插件。如果你没有扩展控制台的需求，可以直接跳过本章。
-:::
-
 ::: tip
 在学习本章之前，建议先完整阅读 [入门 > 认识控制台](../../manual/console/index.md)。
 :::

de-DE/guide/develop/workspace.md

@@ -153,14 +153,16 @@ yarn clone koishijs/koishi-plugin-forward
 
 ### 开发 Koishi
 
-工作区不仅可以用于插件的二次开发，还可以用于开发 Koishi 本身。只需使用下面的命令将 Koishi 仓库克隆到本地：
+工作区不仅可以用于插件的二次开发，还可以用于开发 Koishi 本身。只需使用下面的命令将 Koishi 仓库克隆到本地，并完成构建：
 
 ::: tabs code
 ```npm
 npm run clone koishijs/koishi
+npm run build -w @root/koishi
 ```
 ```yarn
 yarn clone koishijs/koishi
+yarn workspace @root/koishi build
 ```
 :::
 

de-DE/guide/i18n/index.md

@@ -5,7 +5,7 @@
 :::
 
 ::: tip
-在学习本章之前，建议先阅读 [入门 > 国际化](../../manual/usage/i18n.md)。
+在学习本章之前，建议先完整阅读 [入门 > 国际化](../../manual/usage/i18n.md)。
 :::
 
 如果你在运营一个大型社区，那么你可能会遇到这种场景：群组内设立了许多不同语言的频道，每个频道分别供不同地区的用户进行交流。在这种情况下，最合适的做法是让你的机器人在不同的频道下使用不同的语言进行回复。本质上，这不会改变机器人的运行逻辑，因此最好的做法是将涉及的每一段文本都抽离出来，通过统一的方式进行管理，并在发送前进行本地化渲染。

de-DE/guide/plugin/filter.md

@@ -1,7 +1,7 @@
 # 过滤器
 
 ::: tip
-在学习本节之前，建议先阅读 [入门 > 过滤器](../../manual/usage/filter.md)。
+在学习本节之前，建议先完整阅读 [入门 > 过滤器](../../manual/usage/filter.md)。
 :::
 
 默认情况下，一个会话事件、中间件或者指令都对所有的会话生效。但如果我们希望这些功能只对部分群聊或者用户生效，我们就需要用到 **过滤器**。

de-DE/guide/plugin/index.md

@@ -1,7 +1,7 @@
 # 认识插件
 
 ::: tip
-在学习本章之前，建议先阅读 [入门 > 安装和配置插件](../../manual/console/market.md)。
+在学习本章之前，建议先完整阅读 [入门 > 安装和配置插件](../../manual/console/market.md)。
 :::
 
 模块化是 Koishi 的核心特性。借助插件系统，Koishi 得以将各种功能解耦出来，并以模块的形式分发。在「开发上手」中我们已经体验了基础的插件开发范例。本章将介绍更多的模块化编写方式，并介绍一些场景下的最佳实践。

de-DE/manual/recipe/server.md

@@ -7,7 +7,7 @@
 Koishi 应用默认情况下只能在本机访问。而对于某些需求，你可能希望在公网上访问到 Koishi 的控制台或其他网络服务：
 
 - 让更多人访问到你的 Koishi 控制台
-- 使用作为 Webhook 服务端的插件 (例如 [github](https://github.koishi.chat))
+- 使用作为 webhook 服务端的插件 (例如 [github](https://github.koishi.chat))
 
 本节教程将指导你完成 Koishi 应用的公网部署。
 

en-US/api/message/elements.md

@@ -282,5 +282,5 @@ hello<message/>world
 |    `nickname`    |        ⭘        |  ~   |        ✓        |    ~    |    ~     |
 |     `avatar`     |        ⭘        |  ~   |        ~        |    ~    |    ~     |
 
-- [1]: 基于 Webhook 功能，目前暂未支持
+- [1]: 基于 webhook 功能，目前暂未支持
 - [2]: 仅限 forward 和 quote 消息