cometchat-i18n

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Purpose

目的

Localize the CometChat UI Kit to the user's language. Every kit ships with English + ~15 bundled languages (Arabic, Bengali, Chinese, German, Spanish, French, Hindi, Indonesian, Italian, Japanese, Korean, Malay, Portuguese, Russian, Swedish, Turkish — exact set varies by kit version). Custom languages can be added at runtime.

The biggest gotcha: the
init
signature differs across kits and major versions. The same audit pass that caught calls API drift caught one of these too (Angular Localize positional signature) — this skill is the canonical reference.

将CometChat UI Kit本地化适配为用户的语言。每个Kit都默认包含英文及约15种内置语言（阿拉伯语、孟加拉语、中文、德语、西班牙语、法语、印地语、印尼语、意大利语、日语、韩语、马来语、葡萄牙语、俄语、瑞典语、土耳其语——具体语言集合因Kit版本而异）。运行时可添加自定义语言。

最容易出错的点：不同Kit及主要版本的
init
签名存在差异。此前的API差异审计发现了这类问题（Angular Localize的位置参数签名）——本技能是权威参考。

API surface per family

各系列API概览

React (v6) — object signature

React (v6) — 对象参数签名

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

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

Object literal.

init({ ... })

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

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

使用对象字面量，调用方式为

init({ ... })

。

React Native (v5) — object signature

React Native (v5) — 对象参数签名

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

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

Same object signature as React.

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

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

与React的对象参数签名一致。

Angular (v4) — POSITIONAL signature

Angular (v4) — 位置参数签名

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

CometChatLocalize.init("es");
// or with custom resources:
CometChatLocalize.init("es", { es: { CHAT: "Charla" } });

Positional, not object. This was the v4.0 audit fix — calling

.init({ language: "es" })

on Angular sets

language = [object Object]

and silently breaks translations. The skill's verification checklist flags this drift.

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

CometChatLocalize.init("es");
// 或传入自定义资源：
CometChatLocalize.init("es", { es: { CHAT: "Charla" } });

使用位置参数，而非对象参数。这是v4.0版本审计中需要修复的问题——在Angular中调用

.init({ language: "es" })

会将

language

设置为

[object Object]

，导致翻译功能静默失效。本技能的验证清单会标记这类差异问题。

Android V5 — Java/Kotlin static method

Android V5 — Java/Kotlin静态方法

kotlin

// Kotlin
CometChatLocalize.setLocale(Locale.forLanguageTag("es"))

java

// Java
CometChatLocalize.setLocale(Locale.forLanguageTag("es"));

setLocale

, not

init

. Takes a

java.util.Locale

kotlin

// Kotlin
CometChatLocalize.setLocale(Locale.forLanguageTag("es"))

java

// Java
CometChatLocalize.setLocale(Locale.forLanguageTag("es"));

使用

setLocale

而非

init

，参数为

java.util.Locale

类型。

Android V6 (beta) — same as V5

Android V6（测试版）—— 与V5一致

V6 keeps the

setLocale(Locale)

API. No drift here.

V6版本保留

setLocale(Locale)

API，无差异问题。

iOS V5

swift

import CometChatUIKitSwift

CometChatLocalize.setLocale(locale: "es")

setLocale(locale:)

. Takes a String, not

Locale

swift

import CometChatUIKitSwift

CometChatLocalize.setLocale(locale: "es")

使用

setLocale(locale:)

，参数为String类型，而非

Locale

。

Flutter V5 (GetX-based)

Flutter V5（基于GetX）

dart

import 'package:cometchat_calls_uikit/cometchat_calls_uikit.dart';

CometChatLocalize.init(language: 'es');

Named-arg, not positional. Single string.

dart

import 'package:cometchat_calls_uikit/cometchat_calls_uikit.dart';

CometChatLocalize.init(language: 'es');

使用命名参数，而非位置参数，参数为单个字符串。

Flutter V6 (Bloc-based)

Flutter V6（基于Bloc）

dart

import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';

CometChatLocalize.init(language: 'es');

Same as V5 in Flutter — named arg.

dart

import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';

CometChatLocalize.init(language: 'es');

与Flutter V5一致——使用命名参数。

Cross-family signature summary

跨系列签名汇总

Family	Init call	Notes
React (v6)	`CometChatLocalize.init({ language, fallbackLanguage })`	Object
React Native (v5)	`CometChatLocalize.init({ language, fallbackLanguage })`	Object
Angular (v4)	`CometChatLocalize.init("es")`	Positional — drift trap
Android (V5/V6)	`CometChatLocalize.setLocale(Locale.forLanguageTag("es"))`	Method name `setLocale` , takes `Locale`
iOS (V5)	`CometChatLocalize.setLocale(locale: "es")`	Method name `setLocale` , takes String
Flutter (V5/V6)	`CometChatLocalize.init(language: 'es')`	Named arg

The agent must consult this table before writing any localization code. Verify against the installed package's type definitions if uncertain — symbol drift between minor versions is real (the React v5 → v6 changed from positional to object).

系列	初始化调用	说明
React (v6)	`CometChatLocalize.init({ language, fallbackLanguage })`	对象参数
React Native (v5)	`CometChatLocalize.init({ language, fallbackLanguage })`	对象参数
Angular (v4)	`CometChatLocalize.init("es")`	位置参数——易踩坑
Android (V5/V6)	`CometChatLocalize.setLocale(Locale.forLanguageTag("es"))`	方法名为 `setLocale` ，参数为 `Locale`
iOS (V5)	`CometChatLocalize.setLocale(locale: "es")`	方法名为 `setLocale` ，参数为String
Flutter (V5/V6)	`CometChatLocalize.init(language: 'es')`	命名参数

Agent在编写任何本地化代码前必须参考此表格。若不确定，请对照已安装包的类型定义进行验证——小版本间的符号差异确实存在（React v5 → v6版本就从位置参数改为了对象参数）。

When to call init/setLocale

何时调用init/setLocale

After CometChat init is configured but before mounting any kit components:

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

kotlin

// Android — in Application.onCreate
override fun onCreate() {
  super.onCreate()
  val settings = UIKitSettings.Builder()/* ... */.build()
  CometChatUIKit.init(this, settings) {
    CometChatLocalize.setLocale(Locale.forLanguageTag(getUserLocale()))
  }
}

swift

// iOS — in App.init or AppDelegate
CometChat.init(appId: ...) { _, error in
  guard error == nil else { return }
  CometChatLocalize.setLocale(locale: Locale.preferredLanguages.first ?? "en")
}

Setting locale before init is harmless but the kit doesn't pick up the locale until init completes; some components read the locale at first render. Doing both in sequence is safest.

在CometChat初始化完成后、挂载任何Kit组件之前调用：

// React示例——在Provider中
useEffect(() => {
  CometChatUIKit.init(settings).then(() => {
    CometChatLocalize.init({ language: getUserLocale(), fallbackLanguage: "en" });
    // 现在可以挂载Kit组件
  });
}, []);

kotlin

// Android——在Application.onCreate中
override fun onCreate() {
  super.onCreate()
  val settings = UIKitSettings.Builder()/* ... */.build()
  CometChatUIKit.init(this, settings) {
    CometChatLocalize.setLocale(Locale.forLanguageTag(getUserLocale()))
  }
}

swift

// iOS——在App.init或AppDelegate中
CometChat.init(appId: ...) { _, error in
  guard error == nil else { return }
  CometChatLocalize.setLocale(locale: Locale.preferredLanguages.first ?? "en")
}

在初始化前设置语言不会产生危害，但Kit要等到初始化完成后才会读取语言设置；部分组件会在首次渲染时读取语言设置。按顺序执行初始化和语言设置是最安全的方式。

Custom languages / overriding strings

自定义语言 / 覆盖字符串

Each kit lets you register a custom language or override individual strings.

每个Kit都支持注册自定义语言或覆盖单个字符串。

React / React Native (v6)

CometChatLocalize.init({
  language: "es",
  fallbackLanguage: "en",
  resources: {
    es: {
      CHAT: "Charla",
      MESSAGES: "Mensajes",
      // ... override only the strings you want
    },
  },
});

CometChatLocalize.init({
  language: "es",
  fallbackLanguage: "en",
  resources: {
    es: {
      CHAT: "Charla",
      MESSAGES: "Mensajes",
      // ... 仅覆盖需要修改的字符串
    },
  },
});

Angular

Positional second arg:

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

使用位置参数的第二个参数：

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

Android

kotlin

val customResources = mapOf(
  "CHAT" to "Charla",
  "MESSAGES" to "Mensajes",
)
CometChatLocalize.setLocale(Locale("es"))
CometChatLocalize.addStringResources("es", customResources)   // verify symbol

The exact symbol for resource-override on Android varies by version — check the kit's published API surface.

kotlin

val customResources = mapOf(
  "CHAT" to "Charla",
  "MESSAGES" to "Mensajes",
)
CometChatLocalize.setLocale(Locale("es"))
CometChatLocalize.addStringResources("es", customResources)   // 验证符号

Android平台上用于覆盖资源的具体符号因版本而异——请查阅Kit的公开API文档。

iOS

swift

CometChatLocalize.setLocale(locale: "es")
CometChatLocalize.setStringResources(["CHAT": "Charla"], for: "es")

swift

CometChatLocalize.setLocale(locale: "es")
CometChatLocalize.setStringResources(["CHAT": "Charla"], for: "es")

Flutter

dart

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

dart

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

RTL languages

RTL语言

Arabic, Hebrew, Persian, Urdu render right-to-left. The kits handle layout direction automatically based on the locale, BUT:

Native iOS / Android: layout direction follows the device's locale OR the explicitly-set CometChat locale, whichever is set last. If your app sets the device locale to Arabic but the kit's locale is English, mismatched RTL is visible.
Web (React / Angular):
```
<html dir="rtl">
```
is required for full RTL support. The kit reads this from the document root. Set it when locale changes:

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

React Native:
```
I18nManager.forceRTL(true)
```
for global RTL flip. Requires app restart to take effect (this is the one common production bug — set RTL, app doesn't visibly change, devs miss the "restart required" warning).

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();
  }
}

Flutter: handled automatically via
```
MaterialApp.localizationsDelegates
```
+
```
Locale('ar')
```
. Flutter's framework flips layout direction on locale change without restart.

阿拉伯语、希伯来语、波斯语、乌尔都语采用从右到左（RTL）的排版方式。Kit会根据语言设置自动处理布局方向，但需注意：

原生iOS / Android：布局方向遵循设备语言设置或显式设置的CometChat语言设置，以最后设置的为准。如果你的应用将设备语言设置为阿拉伯语，但Kit语言设置为英语，会出现RTL布局不匹配的问题。
Web（React / Angular）：需要设置
```
<html dir="rtl">
```
以获得完整的RTL支持。Kit会从文档根节点读取该属性。在语言变更时设置：

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

React Native：调用
```
I18nManager.forceRTL(true)
```
实现全局RTL翻转。需要重启应用才能生效（这是常见的生产环境bug——设置了RTL，但应用布局没有变化，开发者忽略了“需要重启”的提示）。

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

if (isRTLLocale(language) && !I18nManager.isRTL) {
  I18nManager.forceRTL(true);
  if (__DEV__) {
    console.warn("已设置RTL——应用必须重启才能使布局变更生效");
  } else {
    NativeModules.DevSettings.reload();
  }
}

Flutter：通过
```
MaterialApp.localizationsDelegates
```
+
```
Locale('ar')
```
自动处理。Flutter框架会在语言变更时自动翻转布局方向，无需重启应用。

Fallback language

回退语言

Every kit falls back to English when a translation is missing for the active locale. Make this explicit:

// React/RN/Flutter
CometChatLocalize.init({ language: "es", fallbackLanguage: "en" });

Angular and iOS don't have an explicit

fallbackLanguage

arg in their

init

setLocale

API — they hardcode English fallback internally. The skill doesn't try to override this.

当当前语言缺少对应翻译时，所有Kit都会默认回退到英文显示。建议显式设置回退语言：

// React/RN/Flutter
CometChatLocalize.init({ language: "es", fallbackLanguage: "en" });

Angular和iOS的

init

setLocale

API中没有显式的

fallbackLanguage

参数——它们在内部硬编码了英文作为回退语言。本技能不尝试覆盖此默认行为。

Detecting the user's preferred language

检测用户偏好语言

// 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";

kotlin

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

swift

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

dart

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

Map these to your kit's locale convention (most kits use ISO 639-1 two-letter codes; Flutter sometimes accepts BCP47 like

en-US

// Web——浏览器语言
const language = navigator.language.split("-")[0];   // "en-US" → "en"

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

// 或使用react-native-localize适配原生RN：
import { getLocales } from "react-native-localize";
const language = getLocales()[0]?.languageCode ?? "en";

kotlin

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

swift

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

dart

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

将这些语言代码映射为Kit支持的格式（大多数Kit使用ISO 639-1双字母代码；Flutter有时接受BCP47格式如

en-US

）。

Logout / language switch — re-init the kit

登出 / 切换语言——重新初始化Kit

When the user changes language at runtime, simply call

init

setLocale

again with the new language. The kit re-renders kit components on the next render cycle. No need to logout/re-login.

For React/RN — wrap kit components in a

key={language}

to force re-mount if the kit doesn't auto-detect:

tsx

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

This is the workaround for kits that cache localized strings at first render.

当用户在运行时切换语言时，只需再次调用

init

setLocale

并传入新语言即可。Kit会在下一次渲染周期重新渲染组件。无需登出/重新登录。

对于React/RN——如果Kit无法自动检测语言变更，可以将Kit组件包裹在带有

key={language}

的容器中强制重新挂载：

tsx

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

这是针对那些在首次渲染时缓存本地化字符串的Kit的解决方案。

Anti-patterns

反模式

Calling
init
with the wrong signature. Object instead of positional on Angular, vice-versa on React. The audit pass catches this — don't ship without verifying.
Setting locale before kit init. Some kits ignore the early call. Always sequence: kit init → localize init.
No fallback language on web/RN/Flutter. Missing translations show as raw keys (
```
CHAT_HEADER_TITLE
```
etc.) instead of English fallback.
document.dir
not synced with locale on web. RTL languages render LTR — broken layout.
I18nManager.forceRTL
without app restart. Layout doesn't flip; devs think the kit is broken.
Hardcoding language in skill output. Always read user preference (browser/device/explicit setting).
Custom resources keyed by lowercase ID (
```
"chat"
```
instead of
```
"CHAT"
```
). Kit string keys are uppercase by convention. Mismatched case = no override applied.
Trusting the audit-fix-once mindset. Localize signatures can drift in future minor versions. Re-verify on kit upgrade.

调用
init
时使用错误的签名：在Angular中使用对象参数而非位置参数，或在React中反之。审计会发现此类问题——发布前务必验证。
在Kit初始化前设置语言：部分Kit会忽略提前设置的语言。务必按顺序执行：Kit初始化 → 本地化初始化。
在Web/RN/Flutter中未设置回退语言：缺少翻译时会显示原始键值（如
```
CHAT_HEADER_TITLE
```
等），而非英文回退内容。
Web上
document.dir
未与语言设置同步：RTL语言会以LTR方式渲染——布局错乱。
调用
I18nManager.forceRTL
后未重启应用：布局未翻转，开发者误以为Kit存在问题。
在技能输出中硬编码语言：始终读取用户偏好（浏览器/设备/显式设置）。
自定义资源使用小写键名（如
```
"chat"
```
而非
```
"CHAT"
```
）。Kit的字符串键名约定为大写。键名大小写不匹配会导致覆盖失效。
认为审计修复一次就一劳永逸：本地化签名在未来的小版本中可能发生变化。升级Kit时务必重新验证。

Verification checklist

验证清单

```
init
```
/
```
setLocale
```
signature matches the family in the table above
Locale set AFTER kit init resolves
```
fallbackLanguage
```
set where supported (React, RN, Flutter)
Web:
```
document.documentElement.dir
```
synced with RTL languages
React Native:
```
I18nManager.forceRTL
```
warning + restart on RTL set
Custom resources use uppercase string keys
Language detection from browser/device, not hardcoded
Re-init on language switch (or
```
key={language}
```
workaround)
Smoke test: switch to a bundled non-English language, verify kit components localize
Smoke test: switch to a missing-resource language, verify English fallback
RTL smoke test: Arabic / Hebrew on web (with
```
dir="rtl"
```
) and RN (with
```
I18nManager.forceRTL
```
) and native Android/iOS — kit components mirror correctly

```
init
```
/
```
setLocale
```
的签名与上述表格中的对应系列一致
语言设置在Kit初始化完成后执行
在支持的平台（React、RN、Flutter）上设置了
```
fallbackLanguage
```
Web：
```
document.documentElement.dir
```
与RTL语言同步
React Native：设置RTL时添加提示并重启应用
自定义资源使用大写字符串键名
语言检测来自浏览器/设备，而非硬编码
切换语言时重新初始化（或使用
```
key={language}
```
的解决方案）
冒烟测试：切换到一种内置非英文语言，验证Kit组件已本地化
冒烟测试：切换到一种缺少资源的语言，验证英文回退机制生效
RTL冒烟测试：在Web（设置
```
dir="rtl"
```
）、RN（调用
```
I18nManager.forceRTL
```
）及原生Android/iOS上测试阿拉伯语/希伯来语——Kit组件布局正确镜像

Pointers

参考链接

```
cometchat-{family}-core
```
— kit init order and conventions (localize hooks into the post-init phase)
```
cometchat-{family}-customization
```
— custom string resources / theme strings
```
cometchat-{family}-troubleshooting
```
— when localization doesn't apply (cache, sequence, fallback)
```
cometchat-a11y
```
— sister skill; localization + accessibility together cover the bulk of "production polish"

```
cometchat-{family}-core
```
— Kit初始化顺序及约定（本地化需挂钩到初始化完成后的阶段）
```
cometchat-{family}-customization
```
— 自定义字符串资源 / 主题字符串
```
cometchat-{family}-troubleshooting
```
— 本地化未生效时的排查（缓存、顺序、回退）
```
cometchat-a11y
```
— 配套技能；本地化+无障碍支持共同构成“生产级完善度”的核心部分