docs: 添加评论组件多语言配置相关文档

- 在前端配置指南中增加 `lang` 配置项说明及多语言优先级规则
- 在公开配置接口文档中添加 `adminLanguage` 和 `widgetLanguage` 字段
- 更新管理后台功能设置接口文档,包含语言配置字段及详细说明
This commit is contained in:
anghunk
2026-02-10 14:48:56 +08:00
parent ccd558090c
commit 231571091c
3 changed files with 81 additions and 41 deletions

View File

@@ -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();
</script>
@@ -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`)时: