[docs] add zh docs (#3507)

* [docs] add zh docs

* [docs] add lang dropdown

* [docs] update mkdocs zh config

* [docs] migrate assets

* [docs] update overrides dir in mkdocs zh config

* [docs] exclude locales director in main mkdocs config

* [docs] rename assets to public to avoid conflicting with template

* [docs] extra_css change followup

* [docs] add theme.palette.toggle.icon back into mkdocs zh config

* [docs] fix zh readme reference + migrate language-specific repo markdown to docs

* [docs] translate remaining repo docs + update reference

* [docs] update zh index.md reference

* [docs/zh] wording alignment

docs/locales/zh/api/authentication.md

@@ -0,0 +1,149 @@
+# 使用 API 进行身份验证
+
+使用客户端 API 需要进行身份验证。本页记录了如何获取身份验证令牌的通用流程，并提供了使用 `curl` 在命令行界面进行操作的示例。
+
+## 创建新应用
+
+我们需要注册一个新应用，以便请求 OAuth 令牌。这可以通过向 `/api/v1/apps` 端点发送 `POST` 请求来完成。注意将下面命令中的 `your_app_name` 替换为你想使用的应用名称：
+
+```bash
+curl \
+  -X POST \
+  -H 'Content-Type:application/json' \
+  -d '{
+        "client_name": "your_app_name",
+        "redirect_uris": "urn:ietf:wg:oauth:2.0:oob",
+        "scopes": "read"
+      }' \
+  'https://example.org/api/v1/apps'
+```
+
+字符串 `urn:ietf:wg:oauth:2.0:oob` 表示一种称为带外身份验证的技术，这是一种用于多因素身份验证的技术，旨在减少恶意行为者干扰身份验证过程的途径。在此情况下，它允许我们查看并手动复制生成的令牌以便继续使用。
+
+注意，`scopes` 可以是以下任意空格分隔的组合：
+
+- `read`
+- `write`
+- `admin`
+
+!!! warning
+    GoToSocial 目前不支持范围授权令牌，因此在此过程中获得的任何令牌都可以代表你执行所有操作，包括如果你的账户具有管理员权限时的管理员操作。然而，始终以最低权限授予你的应用是一个好习惯。例如，如果你的应用不会发布贴文，请使用 scope=read。
+
+    本着这种精神，上述示例使用了`read`，这意味着当未来支持范围令牌时，应用将仅限于执行`read`操作。
+
+    你可以在[此处](https://github.com/superseriousbusiness/gotosocial/issues/2232)阅读更多关于计划中 OAuth 安全功能的信息。
+
+成功调用会返回一个带有 `client_id` 和 `client_secret` 的响应，我们将在后续流程中需要使用这些信息。它看起来像这样：
+
+```json
+{
+  "id": "01J1CYJ4QRNFZD6WHQMZV7248G",
+  "name": "your_app_name",
+  "redirect_uri": "urn:ietf:wg:oauth:2.0:oob",
+  "client_id": "YOUR_CLIENT_ID",
+  "client_secret": "YOUR_CLIENT_SECRET"
+}
+```
+
+!!! tip
+    确保将 `client_id` 和 `client_secret` 的值保存到某个位置，以便在需要时参考。
+
+## 授权你的应用代表你操作
+
+我们已经在 GoToSocial 注册了一个新应用，但它尚未与你的账户连接。现在，我们需要告知 GoToSocial 这个新应用将代表你操作。为此，我们需要通过浏览器进行实例认证，以启动登录和权限授予过程。
+
+创建一个带查询字符串的 URL，如下所示，将 `YOUR_CLIENT_ID` 替换为你在上一步收到的 `client_id`，然后将 URL 粘贴到浏览器中：
+
+```text
+https://example.org/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=urn:ietf:wg:oauth:2.0:oob&response_type=code&scope=read
+```
+
+!!! tip
+    如果你在注册应用时使用了不同的范围，在上面的 URL 中将 `scope=read` 替换为你注册时使用的加号分隔的范围列表。例如，如果你注册你的应用时使用了 `scopes` 值 `read write`，那么你应该将上面的 `scope=read` 改为 `scope=read+write`。
+
+将 URL 粘贴到浏览器后，你会被引导到实例的登录表单，提示你输入邮箱地址和密码以将应用连接到你的账户。
+
+提交凭据后，你会到达一个页面，上面写着类似这样的内容：
+
+```
+嗨嗨，`your_username`!
+
+应用 `your_app_name` 申请以你的名义执行操作，申请的权限范围是 *`read`*.
+如果选择允许，应用将跳转到： urn:ietf:wg:oauth:2.0:oob 继续操作
+```
+
+点击 `允许`，你将到达这样一个页面：
+
+```text
+Here's your out-of-band token with scope "read", use it wisely:
+YOUR_AUTHORIZATION_TOKEN
+```
+
+复制带外授权令牌到某个地方，因为你将在下一步中需要它。
+
+## 获取访问令牌
+
+下一步是用刚刚收到的带外授权令牌交换一个可重用的访问令牌，该令牌可以在以后所有的 API 请求中发送。
+
+你可以通过另一个 `POST` 请求来完成这项操作，如下所示：
+
+```bash
+curl \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{
+        "redirect_uri": "urn:ietf:wg:oauth:2.0:oob",
+        "client_id": "YOUR_CLIENT_ID",
+        "client_secret": "YOUR_CLIENT_SECRET",
+        "grant_type": "authorization_code",
+        "code": "YOUR_AUTHORIZATION_TOKEN"
+      }' \
+  'https://example.org/oauth/token'
+```
+
+确保替换：
+
+- `YOUR_CLIENT_ID` 为第一步中收到的客户端 ID。
+- `YOUR_CLIENT_SECRET` 为第一步中收到的客户端密钥。
+- `YOUR_AUTHORIZATION_TOKEN` 为在第二步中收到的带外授权令牌。
+
+你会收到一个包含访问令牌的响应，看起来像这样：
+
+```json
+{
+  "access_token": "YOUR_ACCESS_TOKEN",
+  "created_at": 1719577950,
+  "scope": "read",
+  "token_type": "Bearer"
+}
+```
+
+将你的访问令牌复制并安全保存。
+
+## 验证
+
+为了确保一切正常，尝试查询 `/api/v1/verify_credentials` 端点，在请求头中添加你的访问令牌作为 `Authorization: Bearer YOUR_ACCESS_TOKEN`。
+
+请参考以下示例：
+
+```bash
+curl \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
+  'https://example.org/api/v1/accounts/verify_credentials'
+```
+
+如果一切顺利，你应该会得到用户资料的 JSON 响应。
+
+## 最后说明
+
+现在你拥有了访问令牌，可以在每次 API 请求中重复使用该令牌进行授权。你不需要每次都执行整个令牌交换过程！
+
+例如，你可以使用相同的访问令牌向 API 发送另一个 `GET` 请求以获取通知，如下所示：
+
+```bash
+curl \
+  -H 'Content-Type: application/json' \ 
+  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
+  'https://example.org/api/v1/notifications'
+```

docs/locales/zh/api/ratelimiting.md

@@ -0,0 +1,41 @@
+# 请求速率限制
+
+为减轻对你的实例的滥用和抓取，系统使用了基于 IP 的 HTTP 速率限制。
+
+不同的端点组有单独的速率限制规则。换句话说，一个部分的 API 被速率限制了，并不意味着其他部分也会被限制。以下列表中的每个项目都有单独的速率限制规则：
+
+- `/users/*` 和 `/emoji/*` - ActivityPub (s2s) 端点。
+- `/auth/*` 和 `/oauth/*` - 登录和 OAUTH 令牌请求。
+- `/fileserver/*` - 媒体附件、表情符号等。
+- `/nodeinfo/*` - NodeInfo 端点。
+- `/.well-known/*` - webfinger 和 nodeinfo 请求。
+
+默认情况下，每个速率限制规则允许在 5 分钟内最多进行 300 次请求：每个客户端 IP 地址每秒 1 次请求。
+
+每个响应将包含速率限制的当前状态，具体表现为以下头信息：
+
+- `X-Ratelimit-Limit`: 每个时间段允许的最大请求数。
+- `X-Ratelimit-Remaining`: 在剩余时间内仍然可以进行的请求数量。
+- `X-Ratelimit-Reset`: 表示速率限制何时重置的 ISO8601 时间戳。
+
+如果超过速率限制，将返回 [HTTP 429 Too Many Requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) 错误给请求者。
+
+## 速率限制常见问题
+
+### 我总是超出速率限制！为什么？
+
+如果你发现自己的速率限制在正常使用时经常被超出（对于你自己和其他请求者也是如此），这可能是因为 GoToSocial 无法通过 IP 地址区分客户端。你可以通过查看实例的日志来调查这个问题。如果（几乎）所有记录的 IP 地址似乎都是相同的 IP 地址（类似于 `172.x.x.x`），那么速率限制将导致问题。
+
+这种情况通常发生在你的服务器运行在 NAT（端口转发）中，或者在没有正确配置的 HTTP 代理之后，导致你的实例将所有传入 IP 地址视为相同的地址：即你的反向代理或网关的 IP 地址。这意味着所有传入请求*共享同一个速率限制*，而不是按 IP 正确分开。
+
+如果你正在使用 HTTP 代理，那么很可能你的 `trusted-proxies` 未正确配置。如果是这种情况，尝试将反向代理的 IP 地址添加到 `trusted-proxies` 列表中，并重启你的实例。
+
+如果没有使用 HTTP 代理，那么很可能是由 NAT 引起的。在这种情况下，你应该完全禁用速率限制。
+
+### 我可以配置速率限制吗？可以关闭吗？
+
+可以！在配置中设置 `advanced-rate-limit-requests: 0`。
+
+### 我可以将一个或多个 IP 地址排除在速率限制之外，而保持其他的限制吗？
+
+可以！在配置中设置 `advanced-rate-limit-exceptions`。

docs/locales/zh/api/swagger.md

@@ -0,0 +1,21 @@
+# 路由和方法
+
+GoToSocial 使用 [go-swagger](https://github.com/go-swagger/go-swagger) 从代码注释生成一个 V2 [OpenAPI 规范](https://swagger.io/specification/v2/)文档。
+
+生成的 API 文档如下所示。请注意，本文档仅供参考。你将无法使用以下小部件内置的授权功能实际连接到实例或进行 API 调用。相反，你应该使用像 curl、Postman 等工具。
+
+大多数 GoToSocial API 端点需要用户级别的 OAuth 令牌。有关如何使用 OAuth 令牌进行 API 认证的指南，请参阅[认证文档](./authentication.md)。
+
+!!! tip
+    如果你想更多地使用该规范，还可以直接查看 [swagger.yaml](./swagger.yaml)，然后将其粘贴到 [Swagger Editor](https://editor.swagger.io/) 等工具中。这样你可以尝试自动生成不同语言的 GoToSocial API 客户端（不支持，但可以尝试），或者将文档转换为 JSON 或 OpenAPI v3 规范等。更多信息请参见[这里](https://swagger.io/tools/open-source/getting-started/)。
+
+!!! info "注意事项：上传文件"
+    当使用涉及提交表单上传文件的 API 端点时（例如，媒体附件端点或表情符号上传端点等），请注意，在表单字段中 `filename` 是必需的，这是由于 GoToSocial 用于解析表单的依赖关系以及 Go 的某些特性导致的。
+    
+    有关更多背景信息，请参见以下问题：
+    
+    - [#1958](https://github.com/superseriousbusiness/gotosocial/issues/1958)
+    - [#1944](https://github.com/superseriousbusiness/gotosocial/issues/1944)
+    - [#2641](https://github.com/superseriousbusiness/gotosocial/issues/2641)
+
+<swagger-ui src="swagger.yaml"/>

docs/locales/zh/api/throttling.md

@@ -0,0 +1,35 @@
+# 请求限流
+
+GoToSocial 使用请求限流来限制与你的实例 API 的开放连接数。这是为了防止在一个账户含有成千上万粉丝的情况下，贴文被转发或回复时，避免你的实例意外被 DDOS 攻击（即所谓的[死亡之拥](https://en.wikipedia.org/wiki/Slashdot_effect)）。
+
+限流意味着只有有限数量的 HTTP 请求可同时处理，以便为每个请求提供快速响应，迅速完成。其原理是，快速处理较少的请求比同时尝试处理所有传入请求并每个用时多秒要好。
+
+限流应用于不同的路由组，类似于[速率限制](./ratelimiting.md)的组织方式，因此，如果 API 的某个部分正处于限流状态，并不意味着所有部分都如此。
+
+限流限制基于 GoToSocial 可用的 CPU 数量和配置值 `advanced-throttling-multiplier` 来计算。其计算方式如下：
+
+- 处理中的队列限制 = CPU 数量 * CPU 乘数。
+- 待处理队列限制 = 处理中的队列限制 * CPU 乘数。
+
+对于默认乘数（8），得出以下值：
+
+```text
+1 个 CPU = 08 处理中，064 待处理
+2 个 CPU = 16 处理中，128 待处理
+4 个 CPU = 32 处理中，256 待处理
+8 个 CPU = 64 处理中，512 待处理
+```
+
+新请求如果超过处理中的限制将被放入待处理队列，并在有空位时进行处理（即当前处理中的请求完成时）。无法处理且无法放入待处理队列的请求将收到 HTTP 代码 [503 - 服务不可用](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/503)，并设置 `Retry-After` 头为 `30`（秒），以表示调用者稍后重试。
+
+请求不会无限期地保留在待处理队列中：如果待处理中的请求无法在 30 秒内处理，它们也将收到 503 代码和 30 秒的重试等待。
+
+## 限流常见问题
+
+### 我可以调节请求限流吗？
+
+可以。只需根据你的 CPU 性能更改 `advanced-throttling-multiplier` 的值，CPU 性能强可调高，性能相对较弱可调低。
+
+### 我可以禁用请求限流吗？
+
+可以。只需将 `advanced-throttling-multiplier` 设置为 `0` 或更小。这样将完全禁用 HTTP 请求限流，并尝试同时处理所有传入请求。如果你想使用外部服务或反向代理进行请求限流，并且不希望 GoToSocial 干扰你的设置，这是很有用的。