语言与本地化

官网、文档、租户控制台、平台后台和聊天网页支持简体中文、繁体中文和英语。语言只改变展示，不改变接口路径、协议错误码、人民币币种、计费统计时区或用户发送的内容。

网页与文档语言

语言	文档路径	语言标识
简体中文	`/docs/…`	`zh-CN`
繁体中文	`/zh-TW/docs/…`	`zh-TW`
英语	`/en/docs/…`	`en`

从导航栏切换语言，侧栏、站内链接和搜索也切到对应语言。译文页可能标有“初稿”，可以通过原文入口核对中文版本。示例中的字段、接口路径和代码不随译文改名。

控制台、后台和聊天网页在登录前后均可选择语言。语言优先级为：有效 lang 查询参数 → 本机已保存的选择 → 登录账号偏好 → 浏览器语言 → 简体中文。手动切换会保存本机偏好，已登录的控制台／后台账号还会保存个人偏好。切换不会清空正在填写的表单。

zh-Hant、zh-HK 等可归一到繁体，zh-Hans 归一到简体，英语地区变体归一到 en。请传明确的语言标识，不要根据国家、账单地址推断用户的展示语言。

接口请求与错误文案

业务服务端可以使用 Accept-Language 表达偏好，例如 en 或 zh-TW。后端协商语言，相关响应通过 Content-Language 标明，Vary: Accept-Language 表示语言会影响响应。不要把不同用户的本地化结果放入同一份无语言区分的缓存。

字段	用途
`error.code`	稳定的机器判断依据
`error.details`	更具体的业务原因，如 `reason`、`field`
`error.message`	当前协商语言下给人看的说明，不能解析它做业务分支
`error.message_key`	可选稳定文案键，供支持本地文案的客户端使用
`error.message_params`	可选插值参数；缺失时不能假定错误响应不完整
`error.request_id`	排查请求，不受展示语言影响

旧客户端仍可使用 message，新客户端按 code、details 决定重试或页面行为，再用本地化文案展示。WebSocket 错误保持原错误码，也可携带文案元数据。租户同步回调返回的自定义拒绝文字属于业务内容，按原文展示。

App Token 不会因为设置语言而改变授权范围。普通业务应用不要用平台账号语言接口替自己的用户设置语言；SDK 展示语言由宿主管理。

账号语言偏好接口

当前登录身份	方法与路径
租户控制台账号	`PUT /console/v1/account/locale`
平台管理员	`PUT /platform/v1/me/locale`

请求体：

json

{"locale":"en"}

接口只修改当前登录人的偏好，不接受其他账号 ID；返回的个人资料包含 locale，不会覆盖同时编辑的姓名等其他资料。这是控制台／平台会话接口，不是 App Token 的应用业务接口。

SDK 如何显示多语言

SDK／组件	使用方式
Web	从 `@deeprespond/im-web/locale` 导入 `createLocale`、`describeError`；`createLocale('en')` 或 `createLocale('zh-TW')` 的结果传给显示辅助函数
微信小程序提示目录	从 `@deeprespond/im-web/miniprogram/locale/en` 或 `…/zh-TW` 导入对应目录
React／Vue UIKit	给 `UIKitProvider` 设置 `locale="en"` 或 `locale="zh-TW"`
Android	使用 `DRLocale.en`、`DRLocale.zhTW` 或 `DRLocale.forLanguage(tag)`，传给显示辅助函数的 `locale`
Flutter	从 `package:deeprespond_im_flutter/render.dart` 导入 `en`、`zhTW`、`localeForLanguage(tag)`，传给显示辅助函数和 `describeError`

Web 示例：

import { createLocale, describeError } from '@deeprespond/im-web/locale';

const locale = createLocale('en');
const message = describeError(error, 'en');

示例中的 error 是你捕获的 SDK 错误；locale 可传给摘要、群提示等显示辅助函数。语言目录在本地，不调用在线翻译。宿主负责保存选择，切换语言不会翻译用户消息或更改协议值。已有应用应确认实际安装的包含对应出口，不只核对仓库源码版本。

通知与运营内容

账号语言偏好参与系统通知的语言选择。平台需分别配置对应语言的邮件和短信模板，模板参数、验证码有效期和业务校验保持一致。缺少指定语言的通知变体时会明确失败，不会静默换成另一种语言的安全验证码。

短信模板需要供应商分别审核；示例配置中的 _en、_zh_TW 后缀不是已经审核可发送的编号。页面支持英语，不表示英语短信已经开通。自部署维护人员应在升级时核对实际通知目录、模板 ID 和投递结果。

套餐名称与说明、更新日志、版权／开发者和页脚 HTML 等由平台维护语言变体。运营内容缺少翻译时可以显示原内容，更新日志会标明实际内容语言。这与验证码模板的失败规则不同。业务价格、配额和币种不因展示语言改变。

常见问题

改语言后又恢复了：检查 URL 是否仍有 lang，本机选择是否保存，以及是否登录了另一个账号。
接口变成英语但页面仍有中文：检查 SDK 是否使用了所选目录；用户消息、业务回调文字和缺少翻译的运营内容可能保留原文。
英文页面看到旧计费规则：通过中文原文入口核对并向平台反馈页面地址；不要根据旧译文自行改变实际余额结算。
通知发送失败：核对该语言模板是否存在、短信编号是否已审核及业务凭证是否仍有效；不要重复生成验证码来掩盖模板配置错误。

接口通用约定见接入概述，错误处理见错误码。

语言与本地化 ​

网页与文档语言 ​

接口请求与错误文案 ​

账号语言偏好接口 ​

SDK 如何显示多语言 ​

通知与运营内容 ​