cometchat-i18n

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.

---

API surface per family

React (v6) — object signature

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

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

Object literal. init({ ... }).

React Native (v5) — object signature

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

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

Same object signature as React.

Angular (v4) — POSITIONAL signature

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.

Android V5 — Java/Kotlin static method

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

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

setLocale, not init. Takes a java.util.Locale.

Android V6 (beta) — same as V5

V6 keeps the setLocale(Locale) API. No drift here.

iOS V5

import CometChatUIKitSwift

CometChatLocalize.setLocale(locale: "es")

setLocale(locale:). Takes a String, not Locale.

Flutter V5 (GetX-based)

import 'package:cometchat_calls_uikit/cometchat_calls_uikit.dart';

CometChatLocalize.init(language: 'es');

Named-arg, not positional. Single string.

Flutter V6 (Bloc-based)

import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';

CometChatLocalize.init(language: 'es');

Same as V5 in Flutter — named arg.

---

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).

---

When to call 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
  });
}, []);

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

// 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.

---

Custom languages / overriding strings

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

React / React Native (v6)

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

Angular

Positional second arg:

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

Android

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.

iOS

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

Flutter

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

---

RTL languages

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

1. 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.
2. 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]);

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

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

---

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.

---

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

// 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'

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

---

Logout / language switch — re-init the 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:

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

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

---

Anti-patterns

1. 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.
2. Setting locale before kit init. Some kits ignore the early call. Always sequence: kit init → localize init.
3. No fallback language on web/RN/Flutter. Missing translations show as raw keys (CHAT_HEADER_TITLE etc.) instead of English fallback.
4. document.dir not synced with locale on web. RTL languages render LTR — broken layout.
5. I18nManager.forceRTL without app restart. Layout doesn't flip; devs think the kit is broken.
6. Hardcoding language in skill output. Always read user preference (browser/device/explicit setting).
7. Custom resources keyed by lowercase ID ("chat" instead of "CHAT"). Kit string keys are uppercase by convention. Mismatched case = no override applied.
8. Trusting the audit-fix-once mindset. Localize signatures can drift in future minor versions. Re-verify on kit upgrade.

---

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

---

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"