語言與本地化

官網、文件、租戶控制台、平臺後臺和聊天網頁支援簡體中文、繁體中文和英語。語言只改變展示，不改變介面路徑、協議錯誤碼、人民幣幣種、計費統計時區或使用者傳送的內容。

網頁與文件語言

語言	文件路徑	語言標識
簡體中文	`/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 如何顯示多語言 ​

通知與運營內容 ​