cometchat-i18n

**事实依据：**UI Kit 的 CometChatLocalize API 和 docs/fundamentals。**官方文档：**https://www.cometchat.com/docs/fundamentals/overview · 文档 MCP：claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp（或者不使用 MCP，直接获取该 URL）。依赖符号前，请先对照已安装的软件包或源码进行验证。

用途

将 CometChat UI Kit 本地化为用户使用的语言。每个套件都附带英语和约 15 种内置语言（阿拉伯语、孟加拉语、中文、德语、西班牙语、法语、印地语、印度尼西亚语、意大利语、日语、韩语、马来语、葡萄牙语、俄语、瑞典语、土耳其语——具体语言因套件版本而异）。运行时可以添加自定义语言。

最大的注意事项：**不同套件的本地化 API 各不相同。**Web 和 Angular v5 使用 CometChatLocalize.init({ ... })（对象）；React Native v5 使用 <CometChatI18nProvider> 组件和 useCometChatTranslation hook（没有 CometChatLocalize.init）；Android 使用 CometChatLocalize.setLocale(context, "es")（Context 和代码 String）；iOS 使用 CometChatLocalize.set(locale: "es")；Flutter 完全没有 CometChatLocalize 类——请注册套件的 Translations 本地化代理。（Angular 的位置参数形式 init("es") 仅适用于 v4；v5 改为对象签名，与 React 一致。）本技能是权威参考。

---

各平台 API 一览

React（v6）——对象签名

import { CometChatLocalize } from "@cometchat/chat-uikit-react";

CometChatLocalize.init({
  language: "es",
  fallbackLanguage: "en",
});

对象字面量。init({ ... })。

React Native（v5）——CometChatI18nProvider（不是 CometChatLocalize.init）

RN v5 套件不会导出带有 .init(...) 的 CometChatLocalize 类（这是 RN v4 API）。v5 通过提供程序组件和 hook 实现本地化。在应用中（CometChatThemeProvider 内部）包裹应用，并使用 useCometChatTranslation 读取字符串：

import {
  CometChatThemeProvider,
  CometChatI18nProvider,
} from "@cometchat/chat-uikit-react-native";

const App = () => (
  <CometChatThemeProvider theme={{ mode: "light" }}>
    {/* autoDetectLanguage reads the device locale; or pin one with selectedLanguage="es" */}
    <CometChatI18nProvider autoDetectLanguage={true} fallbackLanguage="en">
      {/* your screens / kit components */}
    </CometChatI18nProvider>
  </CometChatThemeProvider>
);

// In a component:
import { useCometChatTranslation } from "@cometchat/chat-uikit-react-native";
const { t } = useCometChatTranslation();
// t("CHATS")

CometChatI18nProviderProps：selectedLanguage?、autoDetectLanguage?: boolean、fallbackLanguage?、translations?: { [code]: {...} }（已对照 shared/resources/CometChatLocalizeNew/CometChatI18nProvider.tsx 验证）。如需命令式切换，可使用 setGlobalLanguage(language, translations?, fallback?)。

Angular（v5）——对象签名

import { CometChatLocalize } from "@cometchat/chat-uikit-angular";

CometChatLocalize.init({ language: "es" });
// with more options:
CometChatLocalize.init({
  language: "es",
  fallbackLanguage: "en-US",
  timezone: "Europe/Madrid",
});

使用对象字面量，而非位置参数——在 v5（@cometchat/chat-uikit-angular@5）中，init(settings: LocalizationSettings) 接受对象，形式与 React 相同。（已在 projects/cometchat-uikit/src/lib/resources/CometChatLocalize/cometchat-localize.ts 中验证——static init(settings: LocalizationSettings)。）旧的位置参数形式 init("es") 是 v4 Angular API，不再适用。使用 CometChatLocalize.setCurrentLanguage("fr") 在运行时切换语言，使用 getLocalizedString(key) 读取键，并使用 addTranslation({ ... }) 添加自定义字符串。

Android V5——Java/Kotlin 静态方法

// Kotlin — takes (Context, language-code String). Language.* are String constants.
CometChatLocalize.setLocale(context, Language.SPANISH)   // or "es"

// Java
CometChatLocalize.setLocale(context, Language.SPANISH);  // or "es"

使用 setLocale，而非 init。签名为 setLocale(Context, @Language.Code String)——需要一个 Context 和一个两字母语言代码 String（不是 java.util.Locale）。Language 提供 ENGLISH="en"、SPANISH="es"、FRENCH="fr"、GERMAN="de" 等。（已对照 chatuikit/.../localise/CometChatLocalize.java 和 Language.kt 验证。）

Android V6（稳定版）——与 V5 相同

V6 保持相同的 API：CometChatLocalize.setLocale(context, "es")（已对照 chatuikit-kotlin/.../localise/CometChatLocalize.kt:22 验证——fun setLocale(context: Context, language: String)）。V5 和 V6 之间没有差异。

iOS V5

import CometChatUIKitSwift

CometChatLocalize.set(locale: "es")   // or set(locale: Language.spanish)

方法是 set(locale:)，不是 setLocale(...)。它接受 String（或 Language）——public class func set(locale: String) / set(locale: Language)（已对照 Components/Shared/Helpers/CometChatLocalize/CometChatLocalize.swift:78,82 验证）。没有 setStringResources；请通过应用的 Localizable.strings 覆盖单个字符串。

Flutter V5 + V6 — 不存在 CometChatLocalize.init(...)

**已根据套件源代码和文档（ui-kits/cometchat-uikit-flutter-v6、documentation/docs/ui-kit/flutter/localize.mdx）验证：Flutter 不提供 CometChatLocalize 类。**本地化采用符合 Flutter 惯例的方式接入——在 MaterialApp 中注册套件的 Translations 本地化委托，并通过应用的 Locale 设置语言。此技能的早期草稿曾展示 CometChatLocalize.init(language: 'es')；该符号在 Flutter UI Kit（V5 或 V6）中不存在——请勿输出此代码。

import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart' as cc; // V6
// V5: import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart' as cc; (5.2.x)

MaterialApp(
  // Language follows the app Locale. Set `locale:` to force one, or omit to
  // follow the device + supportedLocales.
  locale: const Locale('es'),
  supportedLocales: const [
    Locale('en'), Locale('ar'), Locale('de'), Locale('es'), Locale('fr'),
    Locale('hi'), Locale('ja'), Locale('ko'), Locale('pt'), Locale('ru'),
    Locale('zh'), // …19 supported total — see the docs list
  ],
  localizationsDelegates: const [
    cc.Translations.delegate,            // ← the CometChat UI Kit strings
    GlobalMaterialLocalizations.delegate,
    GlobalWidgetsLocalizations.delegate,
    GlobalCupertinoLocalizations.delegate,
  ],
  home: const YourHomeScreen(),
);

使用 cc.Translations.of(context).users 读取翻译后的字符串。要添加自定义语言或覆盖现有语言，可继承 cc.Translations 并注册自己的 LocalizationsDelegate，且需将其放在列表中的 cc.Translations.delegate 之前（完整示例见 documentation/docs/ui-kit/flutter/localize.mdx）。

---

各系列签名摘要

系列	初始化调用	备注
React（v6）	CometChatLocalize.init({ language, fallbackLanguage })	对象
React Native（v5）	<CometChatI18nProvider autoDetectLanguage selectedLanguage="es" fallbackLanguage="en"> + useCometChatTranslation()	Provider 组件，而非 CometChatLocalize.init
Angular（v5）	CometChatLocalize.init({ language, fallbackLanguage })	对象（与 React 的形式相同）
Android（V5/V6）	CometChatLocalize.setLocale(context, "es")	方法 setLocale(Context, String code)——不是 Locale
iOS（V5）	CometChatLocalize.set(locale: "es")	方法 set(locale:)（String 或 Language）——不是 setLocale
Flutter（V5/V6）	MaterialApp(localizationsDelegates: [cc.Translations.delegate, …], supportedLocales: […], locale: Locale('es'))	没有 CometChatLocalize——注册套件的 Translations 委托，并通过 Locale 设置语言；使用 Translations.of(context) 读取

编写任何本地化代码之前，Agent 必须查阅此表。如有疑问，请根据已安装软件包的类型定义进行验证——各系列的本地化接口确实有所不同（例如，React Native 从 CometChatLocalize 类改为 <CometChatI18nProvider> 组件；Flutter 则从未提供过 CometChatLocalize 类）。

---

何时调用 init/setLocale

配置好 CometChat 初始化后、挂载任何套件组件前：

// React example — in your provider
useEffect(() => {
  CometChatUIKit.init(settings)?.then(() => {
    CometChatLocalize.init({ language: getUserLocale(), fallbackLanguage: "en" });
    // Now mount kit components
  });
}, []);

// Android — in Application.onCreate. setLocale takes (Context, code String).
override fun onCreate() {
  super.onCreate()
  val settings = UIKitSettings.UIKitSettingsBuilder()/* ... */.build()
  CometChatUIKit.init(this, settings, object : CometChat.CallbackListener<String>() {
    override fun onSuccess(p: String) {
      CometChatLocalize.setLocale(this@MyApp, getUserLocale())   // e.g. "es"
    }
    override fun onError(e: CometChatException) {}
  })
}

// iOS — in App.init or AppDelegate. The method is set(locale:), takes a String.
CometChat.init(appId: ...) { _, error in
  guard error == nil else { return }
  let code = Locale.preferredLanguages.first?.split(separator: "-").first.map(String.init) ?? "en"
  CometChatLocalize.set(locale: code)
}

在初始化前设置区域设置不会造成问题，但套件要等初始化完成后才会采用该区域设置；某些组件会在首次渲染时读取区域设置。依次完成这两步最为稳妥。

---

自定义语言 / 覆盖字符串

每个套件都允许注册自定义语言或覆盖单个字符串。

React / React Native（v6）

CometChatLocalize.init({
  language: "es",
  fallbackLanguage: "en",
  // FLAT key->value map for the ACTIVE language (NOT a nested `resources: { es: {...} }`
  // object — LocalizationSettings has no `resources` field; it's silently ignored).
  translationsForLanguage: {
    "Chat": "Charla",
    "Messages": "Mensajes",
    // ... override only the strings you want, for the active language
  },
});
// To add overrides for additional languages, call CometChatLocalize.addTranslation({...}) per language.

React Native（v5）——Provider 上的 translations 属性

<CometChatI18nProvider
  selectedLanguage="es"
  translations={{ es: { CHATS: "Charla", MESSAGES: "Mensajes" } }}
>
  {/* … */}
</CometChatI18nProvider>

以相同方式添加全新语言：使用 translations={{ custom: { CHATS: "…" } }}，并设置 selectedLanguage="custom"。

Angular

使用对象形式初始化，然后通过 addTranslation 注册自定义字符串（v5）：

CometChatLocalize.init({ language: "es" });
CometChatLocalize.addTranslation({
  es: { CHAT: "Charla", MESSAGES: "Mensajes" },
});

Android

Android 套件的 CometChatLocalize 没有字符串覆盖 API（没有 addStringResources/setStringResources）。请使用 Android 原生方式覆盖单个字符串——在应用资源中添加包含套件字符串键的 values-es/strings.xml；Android 资源解析会为当前区域设置选取相应内容。

CometChatLocalize.setLocale(context, "es")   // selects the locale; string overrides live in res/values-es/

iOS

iOS 也没有 setStringResources API。请使用套件字符串键，通过应用的 Localizable.strings（按区域设置放入对应的 .lproj）覆盖字符串；set(locale:) 只用于选择当前区域设置。

CometChatLocalize.set(locale: "es")   // overrides live in es.lproj/Localizable.strings

Flutter

Flutter 没有 CometChatLocalize.init——要覆盖或添加字符串，请继承套件的 Translations 委托，并在 MaterialApp.localizationsDelegates 中将自己的委托注册在 cc.Translations.delegate 之前（完整示例见 documentation/docs/ui-kit/flutter/localize.mdx）：

class MyTranslations extends cc.Translations {
  @override
  String get chats => 'Charla';   // override individual getters
}
// register MyTranslationsDelegate() ahead of cc.Translations.delegate

---

从右到左书写的语言

阿拉伯语、希伯来语、波斯语和乌尔都语从右向左显示。各套件会根据区域设置自动处理布局方向，但：

1. 原生 iOS / Android：布局方向遵循设备的区域设置或显式设置的 CometChat 区域设置，以最后设置的为准。如果应用将设备区域设置为阿拉伯语，但套件的区域设置为英语，就会出现 RTL 不匹配。
2. Web（React / Angular）：需要设置 <html dir="rtl"> 才能获得完整的 RTL 支持。套件会从文档根节点读取此设置。区域设置变化时，请进行设置：

useEffect(() => {
  const lang = currentLocale;
  document.documentElement.dir = ["ar", "he", "fa", "ur"].includes(lang) ? "rtl" : "ltr";
  CometChatLocalize.init({ language: lang });
}, [currentLocale]);

3. React Native：使用 I18nManager.forceRTL(true) 全局翻转 RTL 布局。需要重启应用才能生效（这是一个常见的线上问题——设置 RTL 后应用看起来没有变化，开发者忽略了“需要重启”的警告）。

import { I18nManager, NativeModules, Platform } from "react-native";

if (isRTLLocale(language) && !I18nManager.isRTL) {
  I18nManager.forceRTL(true);
  if (__DEV__) {
    console.warn("RTL set — app must restart for layout change to apply");
  } else {
    NativeModules.DevSettings.reload();
  }
}

4. Flutter：通过 MaterialApp.localizationsDelegates + Locale('ar') 自动处理。Flutter 框架会在区域设置变化时翻转布局方向，无需重启。

---

回退语言

当当前区域设置缺少翻译时，每个套件都会回退到英语。请明确指定：

// React/RN/Angular (object signature) — fallbackLanguage is a settings field
CometChatLocalize.init({ language: "es", fallbackLanguage: "en-US" });

Angular v5 的 LocalizationSettings 包含 fallbackLanguage（已在 cometchat-localize.ts 中确认——默认为 en-US）。RN 的 <CometChatI18nProvider> 接受 fallbackLanguage 属性。Flutter 的 Translations 代理和 iOS 的 set(locale:) 不提供显式的回退参数——它们会在内部回退到英语，因此此技能不会尝试覆盖它们。

---

检测用户的首选语言

// Web — browser language
const language = navigator.language.split("-")[0];   // "en-US" → "en"

// React Native — device language
import * as Localization from "expo-localization";    // Expo
const language = Localization.locale.split("-")[0];

// or react-native-localize for bare RN:
import { getLocales } from "react-native-localize";
const language = getLocales()[0]?.languageCode ?? "en";

// Android
val language = Locale.getDefault().language          // "en"

// iOS
let language = Locale.preferredLanguages.first?.split(separator: "-").first.map(String.init) ?? "en"

// Flutter
import 'dart:ui';
final language = window.locale.languageCode;          // 'en'

将这些映射到套件的区域设置约定（大多数套件使用 ISO 639-1 双字母代码；Flutter 有时也接受 en-US 这样的 BCP47 格式）。

---

退出登录 / 切换语言 — 重新初始化套件

用户在运行时更改语言时，只需使用新语言再次调用 init/setLocale。套件组件会在下一个渲染周期重新渲染。无需退出登录后重新登录。

对于 React/RN——在套件组件外层使用 key={language}，以便在套件无法自动检测时强制重新挂载：

<div key={language}>
  <CometChatConversations />
</div>

这是针对会在首次渲染时缓存本地化字符串的套件的变通方法。

---

高级初始化选项 + 日期/时间格式（web / JS 系列）

CometChatLocalize.init(settings)（web、RN、Angular）接受的不只是语言——LocalizationSettings 还包含基础方案中省略的选项（均已在 cometchat-uikit-react-v6/src/resources/CometChatLocalize/cometchat-localize.ts 中确认）：

• translationsForLanguage — 在初始化时注入自定义字符串覆盖项（addTranslation 的便捷写法）。
• missingKeyHandler — 对任何缺少翻译的键调用的回调（可记录该键，或返回回退值）。有助于发现自定义语言中的缺漏。
• timezone — IANA 时区字符串（例如 "America/New_York"），用于套件格式化时间戳。

日期/时间格式由 CalendarObject 控制（从套件导出，位于 utils/CalendarObject.ts）——可全局传入，或按组件传入（例如组件的 lastActiveAtDateTimeFormat 样式属性），以控制套件呈现相对时间和绝对时间的方式。有关完整的 CalendarObject 字段列表，以及 flag_message_reason_* / message_composer_mention_* 翻译键约定，请查询 docs MCP / ui-kit/react/localize。

这些内容适用于 web/JS 系列。原生系列（Android/iOS/Flutter）通过各自的资源/字符串机制进行本地化——请参阅各系列对应的 -core/-troubleshooting 技能。

---

反模式

1. 为不同产品系列使用了错误的本地化接口。 Web + Angular v5 使用 CometChatLocalize.init({ language })（对象）；React Native v5 使用 <CometChatI18nProvider> + useCometChatTranslation（不要使用 CometChatLocalize.init）；Android 使用 CometChatLocalize.setLocale(context, "es")；iOS 使用 CometChatLocalize.set(locale: "es")；Flutter 没有 CometChatLocalize——请注册工具包的 Translations 委托。旧版的位置参数形式 init("es") 仅适用于 Angular v4。如不确定，请核对已安装软件包的类型定义。
2. 在初始化工具包之前设置区域设置。 有些工具包会忽略提前调用。请始终按以下顺序执行：初始化工具包 → 初始化本地化。
3. Web/RN/Flutter 未设置回退语言。 缺少翻译时会显示原始键（如 CHAT_HEADER_TITLE），而不是回退到英语。
4. Web 上的 document.dir 未与区域设置同步。 RTL 语言会以 LTR 方式呈现，导致布局错乱。
5. 调用 I18nManager.forceRTL 后未重启应用。 布局不会翻转，开发者会误以为工具包有问题。
6. 在技能输出中硬编码语言。 请始终读取用户偏好（浏览器／设备／明确设置）。
7. 自定义资源使用小写 ID 作为键（"chat" 而不是 "CHAT"）。工具包字符串键按惯例使用大写。大小写不匹配 = 不会应用覆盖。
8. 认为审计修复一次就一劳永逸。 本地化接口可能会在未来的小版本中发生变化。升级工具包时请重新核对。

---

验证清单

• init / setLocale 的签名与上表中的产品系列相符
• 工具包初始化完成后再设置区域设置
• 在支持的平台上设置了 fallbackLanguage（React、RN、Flutter）
• Web：document.documentElement.dir 与 RTL 语言同步
• React Native：设置 RTL 时提醒 I18nManager.forceRTL 需要重启
• 自定义资源使用大写字符串键
• 从浏览器／设备检测语言，而非硬编码
• 切换语言时重新初始化（或使用 key={language} 作为变通方法）
• 冒烟测试：切换到已打包的非英语语言，验证工具包组件已本地化
• 冒烟测试：切换到缺少资源的语言，验证回退到英语
• RTL 冒烟测试：在 Web（使用 dir="rtl"）、RN（使用 I18nManager.forceRTL）以及原生 Android/iOS 上测试阿拉伯语／希伯来语，确保工具包组件正确镜像

---

参考

• cometchat-{family}-core — 工具包初始化顺序和惯例（本地化钩子会在初始化后阶段执行）
• cometchat-{family}-customization — 自定义字符串资源／主题字符串
• cometchat-{family}-troubleshooting — 本地化未生效时的排查方法（缓存、执行顺序、回退）
• cometchat-a11y — 相关技能；本地化与无障碍支持相结合，涵盖了大部分“生产级润色”工作