国际化（i18n）

SDK 内置国际化引擎，支持 9 种语言，通过 classroom.i18n 访问。

内置语言

语言代码	语言	备注
zh-CN	简体中文	默认语言
zh-TW	繁体中文
en	英语
ja	日语
ko	韩语
vi	越南语
ar	阿拉伯语	RTL 布局自动处理
id	印尼语
es	西班牙语

指定语言

import { TencentClassroom } from '@tencent-classroom/sdk';

// 方式一：构造时指定
const classroom = new TencentClassroom({ language: 'zh-CN' });

// 方式二：运行时切换
classroom.i18n.setLocale('ja');

// 查询当前语言
classroom.i18n.getLocale(); // => 'ja'

// 是否 RTL 语言（如阿拉伯语）
classroom.i18n.isRtl(); // => false（阿拉伯语为 true）

// 获取所有已注册语言列表
classroom.i18n.getSupportedLocales(); // => ['zh-CN', 'zh-TW', 'en', 'ja', 'ko', 'vi', 'ar', 'id', 'es']

自动检测

如果不指定 language，SDK 会调用 detectSystemLocale() 自动检测浏览器语言并映射到支持的语言代码。

使用多语言词条

// 使用单个词条
classroom.i18n.t('uikit.footer.leave'); // => '离开课堂'

// 带插值参数
classroom.i18n.t('uikit.member.online', { count: 5 }); // => '5 人在线'

命名空间

SDK 词条分为两个命名空间：

命名空间	枚举值	词条前缀	用途
SDK	TI18nNamespace.SDK	sdk.	SDK 内部错误消息、TResult message
UIKit	TI18nNamespace.UIKIT	uikit.	UI 组件展示文案

词条 key 格式：{namespace}.{module}.{id}

例如：

• sdk.result.0 — SDK 成功消息
• sdk.result.20104 — SDK 错误"找不到摄像头"
• uikit.footer.leave — UIKit "离开课堂"按钮
• uikit.role.teacher — UIKit "老师"角色名

覆写部分词条

如需自定义某些文案（如把"老师"改为"讲师"），有两种方式：

方式一：构造时覆盖

const classroom = new TencentClassroom({
  language: 'zh-CN',
  // i18nOverrides: 作用于当前语言
  i18nOverrides: {
    'uikit.role.teacher': '讲师',
    'uikit.footer.leave': '退出教室',
  },
  // nameConfig: 按语言分别覆盖
  nameConfig: {
    'zh-CN': { 'uikit.role.teacher': '讲师' },
    'en': { 'uikit.role.teacher': 'Instructor' },
  },
});

方式二：运行时覆盖

classroom.i18n.setOverrides('zh-CN', {
  'uikit.role.teacher': '讲师',
  'uikit.footer.leave': '退出教室',
});

// 也可覆盖其他语言
classroom.i18n.setOverrides('en', {
  'uikit.role.teacher': 'Instructor',
});

覆盖优先级

setOverrides / i18nOverrides 的值优先于内置词条。切换语言后覆盖仍然生效。

注册全新语言

如需支持 SDK 未内置的语言（如泰语），参考本流程。以基准语言（zh-CN）为模板，逐条翻译 value 后注册为新语言即可。

翻译工作流

1. 调用 getLocaleMessages('zh-CN', TI18nNamespace.SDK) 获取所有 SDK 词条 key
2. 调用 getLocaleMessages('zh-CN', TI18nNamespace.UIKIT) 获取所有 UIKit 词条 key
3. 将 value 翻译为目标语言
4. 通过 registerExtraLocale() 分别注册到对应 namespace

获取内置词条模板

注册新语言时，需要知道所有词条 key。通过 classroom.i18n.getLocaleMessages() 可获取指定语言的完整词条表作为翻译模板：

import { TI18nNamespace } from '@tencent-classroom/sdk';

// 获取中文 SDK 命名空间的完整词条（作为翻译模板）
const sdkMessages = classroom.i18n.getLocaleMessages('zh-CN', TI18nNamespace.SDK);
console.log(Object.keys(sdkMessages));
// => ['sdk.result.0', 'sdk.result.1000', 'sdk.result.1001', ...]

// 获取中文 UIKit 命名空间的完整词条
const uikitMessages = classroom.i18n.getLocaleMessages('zh-CN', TI18nNamespace.UIKIT);
console.log(Object.keys(uikitMessages));
// => ['uikit.footer.leave', 'uikit.role.teacher', ...]

// 获取所有命名空间合并后的词条（不传第二个参数）
const allMessages = classroom.i18n.getLocaleMessages('zh-CN');

// 获取英文词条（可用于对照翻译）
const enMessages = classroom.i18n.getLocaleMessages('en');

把新语言注册到 SDK

使用 registerExtraLocale 方法：

import { TencentClassroom, TI18nNamespace } from '@tencent-classroom/sdk';

const classroom = new TencentClassroom();
await classroom.init();

// ⚠️ 每个命名空间需要单独注册
// 注册 SDK 命名空间的泰语词条
classroom.i18n.registerExtraLocale(TI18nNamespace.SDK, 'th', {
  'sdk.result.0': 'สำเร็จ',
  'sdk.result.20104': 'ไม่พบกล้อง',
  // ... 更多 SDK 词条
});

// 注册 UIKit 命名空间的泰语词条
classroom.i18n.registerExtraLocale(TI18nNamespace.UIKIT, 'th', {
  'uikit.footer.leave': 'ออกจากห้องเรียน',
  'uikit.footer.mic': 'ไมโครโฟน',
  'uikit.role.teacher': 'ครู',
  // ... 更多 UIKit 词条
});

// 切换到泰语
classroom.i18n.setLocale('th');

完整性要求

注册新语言时，应提供该命名空间下所有词条的翻译。缺失的词条将 fallback 到默认语言（zh-CN）。

语言切换事件

语言切换后 SDK 会触发事件，UIKit 层可监听刷新界面：

import { TEvent } from '@tencent-classroom/sdk';

classroom.on(TEvent.LANGUAGE_CHANGED, () => {
  // 语言已切换，UIKit 组件会自动更新（Signal 驱动）
  // 业务层如有自定义文案可在此刷新
  console.log('当前语言:', classroom.i18n.getLocale());
});

通过 setConfig 切换语言

除了 classroom.i18n.setLocale() 外，也可通过 setConfig 切换语言。两者效果相同，选择任一方式即可：

// 方式一：i18n.setLocale（直接调用 i18n 引擎）
classroom.i18n.setLocale('en');

// 方式二：setConfig（通过配置系统，会自动同步到 i18n 引擎）
classroom.setConfig({ language: 'en' });

两种方式的关系

setConfig({ language }) 内部会自动调用 i18n.setLocale(language)，并同步更新 state.config$。 使用 setConfig 的好处是可以同时更新其他配置项（如 debug、board 等），保持配置变更的一致性。

通过 state.config$ 也可订阅到语言变化：

classroom.state.config$.subscribe((config) => {
  console.log('当前语言:', config.language);
});