From 231571091ce40eb0d491c0779ec10680dfcc85bd Mon Sep 17 00:00:00 2001 From: anghunk Date: Tue, 10 Feb 2026 14:48:56 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E8=AF=84=E8=AE=BA?= =?UTF-8?q?=E7=BB=84=E4=BB=B6=E5=A4=9A=E8=AF=AD=E8=A8=80=E9=85=8D=E7=BD=AE?= =?UTF-8?q?=E7=9B=B8=E5=85=B3=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 在前端配置指南中增加 `lang` 配置项说明及多语言优先级规则 - 在公开配置接口文档中添加 `adminLanguage` 和 `widgetLanguage` 字段 - 更新管理后台功能设置接口文档，包含语言配置字段及详细说明 --- docs/api/admin/feature-settings.md | 69 +++++++++++++++++++----------- docs/api/public/config.md | 30 +++++++------ docs/guide/frontend-config.md | 23 +++++++++- 3 files changed, 81 insertions(+), 41 deletions(-) diff --git a/docs/api/admin/feature-settings.md b/docs/api/admin/feature-settings.md index 0696841..aed7585 100644 --- a/docs/api/admin/feature-settings.md +++ b/docs/api/admin/feature-settings.md @@ -1,17 +1,17 @@ # 功能设置相关 -管理各项功能开关的接口，包括点赞功能、图片灯箱预览、评论占位符、域名可见性等。 +管理各项功能开关的接口，包括点赞功能、图片灯箱预览、评论占位符、域名可见性、多语言等。 ## 获取功能设置 ``` -GET /admin/settings/feature +GET /admin/settings/features ``` 获取当前的功能开关配置。 - 方法：`GET` -- 路径：`/admin/settings/feature` +- 路径：`/admin/settings/features` - 鉴权：需要 Bearer Token **成功响应** @@ -24,38 +24,49 @@ GET /admin/settings/feature "enableArticleLike": true, "enableImageLightbox": true, "commentPlaceholder": "发表你的看法...", - "visibleDomains": ["example.com", "blog.example.com"] + "visibleDomains": ["example.com", "blog.example.com"], + "adminLanguage": "zh-CN", + "widgetLanguage": "auto" } ``` 字段说明： -| 字段名 | 类型 | 说明 | -| -------------------- | ------ | ---------------------- | -| `enableCommentLike` | boolean | 是否启用评论点赞功能 | -| `enableArticleLike` | boolean | 是否启用文章点赞功能 | -| `enableImageLightbox` | boolean | 是否启用评论图片灯箱预览功能 | -| `commentPlaceholder` | string \| null | 评论输入框的占位符文本 | -| `visibleDomains` | string[] | 允许显示评论组件的域名列表 | +| 字段名 | 类型 | 说明 | +| -------------------- | -------- | -------------------------------------------------------------------- | +| `enableCommentLike` | boolean | 是否启用评论点赞功能 | +| `enableArticleLike` | boolean | 是否启用文章点赞功能 | +| `enableImageLightbox` | boolean | 是否启用评论图片灯箱预览功能 | +| `commentPlaceholder` | string \| null | 评论输入框的占位符文本，留空则使用默认文案 | +| `visibleDomains` | string[] | 允许显示评论组件的域名列表 | +| `adminLanguage` | string \| null | 管理后台界面语言代码，如 `zh-CN`、`en-US`，为空则使用默认语言 | +| `widgetLanguage` | string \| null | 评论组件默认语言代码，支持 `auto` 自动根据浏览器语言选择 | + +语言相关字段说明： + +- 当配置了 `adminLanguage` 时，管理后台会优先使用该语言渲染界面 +- 当配置了 `widgetLanguage` 时，评论前端组件会以此作为默认语言； + - 如果前端实例化时显式传入 `lang` 配置项，则以前端为最高优先级 + - 当前端未传入 `lang` 时，顺序为：后端 `widgetLanguage` → 自动检测浏览器语言（如 `zh-CN`/`en-US`） ## 更新功能设置 ``` -PUT /admin/settings/feature +PUT /admin/settings/features ``` 更新功能开关配置。 - 方法：`PUT` -- 路径：`/admin/settings/feature` +- 路径：`/admin/settings/features` - 鉴权：需要 Bearer Token **请求头** -| 名称 | 必填 | 示例 | -| -------------- | ---- | ------------------ | -| `Content-Type` | 是 | `application/json` | -| `Authorization` | 是 | `Bearer ` | +| 名称 | 必填 | 示例 | +| --------------- | ---- | -------------------- | +| `Content-Type` | 是 | `application/json` | +| `Authorization` | 是 | `Bearer ` | **请求体** @@ -65,25 +76,31 @@ PUT /admin/settings/feature "enableArticleLike": true, "enableImageLightbox": true, "commentPlaceholder": "发表你的看法...", - "visibleDomains": ["example.com", "blog.example.com"] + "visibleDomains": ["example.com", "blog.example.com"], + "adminLanguage": "zh-CN", + "widgetLanguage": "auto" } ``` 字段说明： -| 字段名 | 类型 | 必填 | 说明 | -| -------------------- | ------- | ---- | ---------------------- | -| `enableCommentLike` | boolean | 否 | 是否启用评论点赞功能 | -| `enableArticleLike` | boolean | 否 | 是否启用文章点赞功能 | -| `enableImageLightbox` | boolean | 否 | 是否启用评论图片灯箱预览功能 | -| `commentPlaceholder` | string | 否 | 评论输入框的占位符文本 | -| `visibleDomains` | string[] | 否 | 允许显示评论组件的域名列表 | +| 字段名 | 类型 | 必填 | 说明 | +| -------------------- | -------- | ---- | -------------------------------------------------------------------- | +| `enableCommentLike` | boolean | 否 | 是否启用评论点赞功能 | +| `enableArticleLike` | boolean | 否 | 是否启用文章点赞功能 | +| `enableImageLightbox` | boolean | 否 | 是否启用评论图片灯箱预览功能 | +| `commentPlaceholder` | string | 否 | 评论输入框的占位符文本 | +| `visibleDomains` | string[] | 否 | 允许显示评论组件的域名列表 | +| `adminLanguage` | string | 否 | 管理后台界面语言代码，留空则不修改当前配置 | +| `widgetLanguage` | string | 否 | 评论组件默认语言代码，支持 `auto` 表示自动根据浏览器语言选择 | **说明**： - `enableImageLightbox`：启用后，评论内容中的图片可以点击放大预览 - `commentPlaceholder`：自定义评论输入框的占位符文本，留空则使用默认文本 -- `visibleDomains`：设置后，只有在此列表中的域名可以正常显示评论组件，其他域名将被隐藏。留空或为 `null` 表示不限制域名。 +- `visibleDomains`：设置后，只有在此列表中的域名可以正常显示评论组件，其他域名将被隐藏。留空或为 `null` 表示不限制域名 +- `adminLanguage`：仅影响管理后台界面，不影响评论组件语言 +- `widgetLanguage`：作为评论组件默认语言，当前端未主动传入 `lang` 时才生效 **成功响应** diff --git a/docs/api/public/config.md b/docs/api/public/config.md index f66ec3a..fc2b83b 100644 --- a/docs/api/public/config.md +++ b/docs/api/public/config.md @@ -35,24 +35,28 @@ GET /api/config/comments "enableCommentLike": true, "enableArticleLike": true, "enableImageLightbox": true, - "commentPlaceholder": "发表你的看法..." + "commentPlaceholder": "发表你的看法...", + "adminLanguage": "zh-CN", + "widgetLanguage": "auto" } ``` 字段说明： -| 字段名 | 类型 | 说明 | -| -------------------- | ------ | -------------------------------------------------------------------- | -| `adminEmail` | string | 博主邮箱地址，用于在前端展示"博主"标识，并触发管理员身份验证流程 | -| `adminBadge` | string | 博主标识文字，例如 `"博主"` | -| `avatarPrefix` | string | 头像地址前缀，如 Gravatar 或 Cravatar 需像地址 | -| `adminEnabled` | boolean | 是否启用博主标识相关展示（关闭时不显示徽标，但仍可作为管理员邮箱） | -| `allowedDomains` | Array\ | 允许调用组件的域名列表，留空则不限制 | -| `requireReview` | boolean | 是否开启新评论先审核再显示（true 表示新评论默认为待审核） | -| `enableCommentLike` | boolean | 是否启用评论点赞功能（默认 true） | -| `enableArticleLike` | boolean | 是否启用文章点赞功能（默认 true） | -| `enableImageLightbox` | boolean | 是否启用评论图片灯箱预览功能（默认 false） | -| `commentPlaceholder` | string \| null | 评论输入框的占位符文本，留空则使用默认值 | +| 字段名 | 类型 | 说明 | +| -------------------- | ----------------- | -------------------------------------------------------------------- | +| `adminEmail` | string | 博主邮箱地址，用于在前端展示"博主"标识，并触发管理员身份验证流程 | +| `adminBadge` | string | 博主标识文字，例如 `"博主"` | +| `avatarPrefix` | string | 头像地址前缀，如 Gravatar 或 Cravatar 需像地址 | +| `adminEnabled` | boolean | 是否启用博主标识相关展示（关闭时不显示徽标，但仍可作为管理员邮箱） | +| `allowedDomains` | Array\ | 允许调用组件的域名列表，留空则不限制 | +| `requireReview` | boolean | 是否开启新评论先审核再显示（true 表示新评论默认为待审核） | +| `enableCommentLike` | boolean | 是否启用评论点赞功能（默认 true） | +| `enableArticleLike` | boolean | 是否启用文章点赞功能（默认 true） | +| `enableImageLightbox`| boolean | 是否启用评论图片灯箱预览功能（默认 false） | +| `commentPlaceholder` | string \| null | 评论输入框的占位符文本，留空则使用默认值 | +| `adminLanguage` | string \| null | 管理后台界面语言代码，如 `zh-CN`、`en-US`，仅供后台使用 | +| `widgetLanguage` | string \| null | 评论前端组件默认语言代码，支持 `auto` 自动根据浏览器语言选择 | **错误响应** diff --git a/docs/guide/frontend-config.md b/docs/guide/frontend-config.md index c90367b..7c24787 100644 --- a/docs/guide/frontend-config.md +++ b/docs/guide/frontend-config.md @@ -29,8 +29,8 @@ CWD 评论组件采用 **Shadow DOM** 技术构建，基于独立根节点渲染 el: '#comments', // 必填 apiBaseUrl: 'https://your-api.example.com', // 必填，换成你的 API 地址 postSlug: 'post-unique-id-001', // 选填，自定义评论标识符，用于跨路径/多语言聚合 - siteId: 'blog', // 选填，推荐配置，用于多站点数据隔离。 - + siteId: 'blog', // 选填，推荐配置，用于多站点数据隔离 + lang: 'auto', // 选填，评论组件语言，详见下方说明 }); comments.mount(); @@ -60,10 +60,29 @@ https://cwd.js.org/cwd.js | `apiBaseUrl` | `string` | 是 | - | API 基础地址 | | `siteId` | `string` | 否 | `''` | 站点 ID，用于多站点数据隔离，推荐配置 | | `postSlug` | `string` | 否 | `window.location.pathname` | 自定义评论标识符，用于跨路径/多语言聚合 | +| `lang` | `string` | 否 | `auto` | 评论组件语言代码，支持 `zh-CN`、`en-US`、`fr` 等，`auto` 表示自动根据浏览器语言选择 | | `theme` | `'light' \| 'dark'` | 否 | `'light'` | 主题模式 | | `pageSize` | `number` | 否 | `20` | 每页显示评论数 | | `customCssUrl` | `string` | 否 | - | 自定义样式表 URL，追加到 Shadow DOM 底部 | +### 多语言配置说明 + +评论组件语言的优先级如下： + +1. 前端实例化时传入的 `lang` 参数（最高优先级） +2. 后端在「功能设置」中配置的 `widgetLanguage`（通过 `/admin/settings/features` 接口下发） +3. 浏览器语言自动检测（当以上两项都为空或为 `auto` 时生效） + +推荐做法： + +- 后端在管理后台中设置一个全局默认语言（`widgetLanguage`），例如 `zh-CN` +- 不同语言站点如有特殊需求，再在前端实例化时通过 `lang` 明确指定 + +> [!note] 目前支持的语言有： +> `zh-CN` `en-US` `zh-TW` `es` `pt` `fr` `de` `ja` `ko` `ru` `it` `nl` `ar` `hi` `id` + +如需适配其他语言，请联系我们，我们会在后续版本中添加对其他语言的支持，或者提交 pr。 + 头像前缀、博主邮箱和标识等信息由后端接口 `/api/config/comments` 提供，无需在前端进行配置。 当 `/admin/settings/comments` 中配置了“评论博主邮箱”（`adminEmail`）时：