@cometchat/skills 4.4.2 → 5.0.1

package/skills/cometchat-i18n/SKILL.md

@@ -1,419 +1,50 @@
 ---
 name: cometchat-i18n
-description: Localization (i18n) across all CometChat UI Kit families — React, React Native, Angular, Android (V5/V6), iOS, Flutter (V5/V6). Covers CometChatLocalize.init signature differences (positional vs object), bundled languages, custom-language registration, RTL support, fallback to English, and cross-family drift risks. Cross-family — applies wherever the agent is configuring CometChat localization.
+description: "Localize a CometChat integration — set the UI Kit language, register custom/overridden translations, handle RTL, and never leak a raw localization key into the UI. Cross-family: the mechanism is CometChatLocalize on React, Angular, iOS and Android, while React Native uses CometChatI18nProvider (there is no CometChatLocalize in the RN kit); the exact signature is fetched from each family's localize doc. Triggers: 'translate cometchat', 'change chat language', 'localization', 'i18n', 'RTL / Arabic / Hebrew chat', 'my UI shows group_info instead of a label', 'add a language to cometchat', 'custom translations'."
 license: "MIT"
-compatibility: "All CometChat UI Kit families v4.x / v5.x / v6.x"
+compatibility: "CometChatLocalize on React v7 · Angular v5 · iOS v5 · Android v6. React Native v5 uses CometChatI18nProvider + the useCometChatTranslation hook (no CometChatLocalize in the RN kit). Flutter v6 is moving to CometChatLocalize but the shipping 6.1.0 kit uses Translations (staged). Exact API per family+major from that family's localize docs."
 metadata:
   author: "CometChat"
-  version: "4.0.0"
-  tags: "cometchat i18n localization l10n cometchatlocalize languages rtl arabic hebrew bundled-languages custom-language fallback cross-family"
+  version: "1.0.0"
+  tags: "cometchat i18n localization localize rtl language translations cometchatlocalize"
 ---
 
-> **Ground truth:** the UI Kit `CometChatLocalize` API + `docs/fundamentals`. **Official docs:** https://www.cometchat.com/docs/fundamentals/overview · **Docs MCP:** `claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp` (or fetch the URL directly without MCP). Verify symbols against the installed package/source before relying on them.
+> **Ground truth:** localization is the **`CometChatLocalize`** class on **React, Angular, iOS and Android**. Two exceptions: **React Native** uses **`CometChatI18nProvider`** + the **`useCometChatTranslation`** hook (there is no `CometChatLocalize` in the RN kit — catalog-confirmed), and **Flutter** is moving to `CometChatLocalize` but the shipping **6.1.0** kit still exposes **`Translations`** (see `cometchat-flutter-v6-customization` → Localization — **STAGED** pending the kit). Exact methods and built-in string keys differ by family and major — **FETCH the signature from the resolved family's localize doc** via `cometchat-<family>-core/references/docs-map.md` (intent: localization / localize). Do not carry an API across families or majors (v6 React, for one, renamed language codes and keys). Never assert a key set from memory — look it up in the kit's `resources/<lang>/translation.json` / the localize page.
 
-## Purpose
+## Use this skill when
+Making the chat speak another language, shipping to a multi-locale or RTL market, adding/overriding wording, or fixing a UI that shows a raw key (e.g. `group_info`) instead of text.
 
-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 mechanism (per family, one shape)
+Most UI Kits localize through `CometChatLocalize` (React Native is the exception — it uses `CometChatI18nProvider` + the `useCometChatTranslation` hook): it can **detect** the user's browser/device language and **set** the active locale, and it exposes the current locale to components (which read their strings from it). The three things you do:
+1. **Set the locale** — let it auto-detect, or set it explicitly to match your app's language switcher. Do this **before** the surface renders (alongside init), so components mount already localized. (React v7: pass the `locale` prop on `CometChatProvider` — `<CometChatProvider locale="fr">` — applied on mount/change.)
+2. **Register custom / overridden translations** — add your own strings or override the kit defaults per locale (e.g. React v7: `CometChatLocalize.getSharedInstance()?.addTranslation({ "en-us": { key: "value" } })` — an **INSTANCE** method taking a **nested per-language** map; reach the live instance via `getSharedInstance()`, never `new CometChatLocalize()`; other families have the equivalent — **React Native** instead uses the `CometChatI18nProvider` **`translations`** prop, keyed on the **active** language code: under the default auto-detect that's the 2-letter device code, so use `translations={{ "en": { KEY: "value" } }}` — a regional key like `en-US` is ignored unless you also pass `selectedLanguage="en-US"`, and codes must match the kit's keys **exactly (case-sensitive)** — e.g. `zh-tw` is lowercase but `en-US`/`en-GB` are uppercase-region; not `addTranslation`. Provider props: `selectedLanguage` · `autoDetectLanguage` · `translations` · `fallbackLanguage` — `{DOCS_BASE}/ui-kit/react-native/localize`). Fetch the exact call for your family.
+3. **Read a string yourself** where you render kit text in your own markup — use the family's localized-string accessor (React v7: `useLocale().getLocalizedString(key)`), never a hardcoded English literal.
 
-The biggest gotcha: **the localization API differs across kits.** Web + Angular v5 use `CometChatLocalize.init({ ... })` (object); **React Native v5 uses a `<CometChatI18nProvider>` component + `useCometChatTranslation` hook (no `CometChatLocalize.init`)**; **Android uses `CometChatLocalize.setLocale(context, "es")`** (Context + code String); **iOS uses `CometChatLocalize.set(locale: "es")`**; **Flutter has no `CometChatLocalize` class at all — register the kit's `Translations` localization delegate.** (Angular's positional `init("es")` was a v4-only form — v5 moved to the object signature, matching React.) This skill is the canonical reference.
+The exact class methods, the supported language list, and the key namespace are per family+major — **fetch them**; this file is the discipline, the docs are the signatures.
 
----
-
-## API surface per family
-
-### React (v6) — object signature
-
-```ts
-import { CometChatLocalize } from "@cometchat/chat-uikit-react";
-
-CometChatLocalize.init({
-  language: "es",
-  fallbackLanguage: "en",
-});
-```
-
-Object literal. `init({ ... })`.
-
-### React Native (v5) — `CometChatI18nProvider` (NOT `CometChatLocalize.init`)
-
-The RN v5 kit does **not** export a `CometChatLocalize` class with `.init(...)` (that was the v4 RN API). v5 localizes through a **provider component** + a hook. Wrap your app (inside `CometChatThemeProvider`) and read strings with `useCometChatTranslation`:
-
-```tsx
-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]: {...} }` (verified vs `shared/resources/CometChatLocalizeNew/CometChatI18nProvider.tsx`). For imperative switching there's `setGlobalLanguage(language, translations?, fallback?)`.
-
-### Angular (v5) — OBJECT signature
-
-```ts
-import { CometChatLocalize } from "@cometchat/chat-uikit-angular";
-
-CometChatLocalize.init({ language: "es" });
-// with more options:
-CometChatLocalize.init({
-  language: "es",
-  fallbackLanguage: "en-US",
-  timezone: "Europe/Madrid",
-});
-```
-
-**Object literal, not positional** — in v5 (`@cometchat/chat-uikit-angular@5`), `init(settings: LocalizationSettings)` takes an object, the same shape as React. (Verified in `projects/cometchat-uikit/src/lib/resources/CometChatLocalize/cometchat-localize.ts` — `static init(settings: LocalizationSettings)`.) The old positional `init("es")` form was the **v4** Angular API and no longer applies. Switch language at runtime with `CometChatLocalize.setCurrentLanguage("fr")`, read keys with `getLocalizedString(key)`, and add custom strings with `addTranslation({ ... })`.
-
-### Android V5 — Java/Kotlin static method
-
-```kotlin
-// Kotlin — takes (Context, language-code String). Language.* are String constants.
-CometChatLocalize.setLocale(context, Language.SPANISH)   // or "es"
-```
-
-```java
-// Java
-CometChatLocalize.setLocale(context, Language.SPANISH);  // or "es"
-```
-
-`setLocale`, not `init`. **Signature is `setLocale(Context, @Language.Code String)`** — a Context plus a two-letter language-code String (NOT a `java.util.Locale`). `Language` exposes `ENGLISH="en"`, `SPANISH="es"`, `FRENCH="fr"`, `GERMAN="de"`, … (verified vs `chatuikit/.../localise/CometChatLocalize.java` + `Language.kt`).
-
-### Android V6 (stable) — same as V5
-
-V6 keeps the same API: `CometChatLocalize.setLocale(context, "es")` (verified vs `chatuikit-kotlin/.../localise/CometChatLocalize.kt:22` — `fun setLocale(context: Context, language: String)`). No drift between V5 and V6.
-
-### iOS V5
-
-```swift
-import CometChatUIKitSwift
-
-CometChatLocalize.set(locale: "es")   // or set(locale: Language.spanish)
-```
-
-The method is **`set(locale:)`**, not `setLocale(...)`. It takes a String (or a `Language`) — `public class func set(locale: String)` / `set(locale: Language)` (verified vs `Components/Shared/Helpers/CometChatLocalize/CometChatLocalize.swift:78,82`). There is no `setStringResources` — override individual strings via your app's `Localizable.strings`.
-
-### Flutter V5 + V6 — there is NO `CometChatLocalize.init(...)`
-
-> **Verified against the kit source + docs (`ui-kits/cometchat-uikit-flutter-v6`, `documentation/docs/ui-kit/flutter/localize.mdx`): Flutter does NOT expose a `CometChatLocalize` class.** Localization is wired the idiomatic Flutter way — register the kit's `Translations` localization delegate on your `MaterialApp` and drive the language through the app's `Locale`. Earlier drafts of this skill showed `CometChatLocalize.init(language: 'es')`; that symbol does not exist in the Flutter UI Kit (V5 or V6) — do not emit it.
-
-```dart
-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(),
-);
-```
-
-Read a translated string with `cc.Translations.of(context).users`. Add a custom
-language or override one by subclassing `cc.Translations` and registering your
-own `LocalizationsDelegate` *before* `cc.Translations.delegate` in the list
-(full recipe in `documentation/docs/ui-kit/flutter/localize.mdx`).
-
----
-
-## Cross-family signature summary
-
-| Family | Init call | Notes |
-|---|---|---|
-| React (v6) | `CometChatLocalize.init({ language, fallbackLanguage })` | Object |
-| React Native (v5) | `<CometChatI18nProvider autoDetectLanguage selectedLanguage="es" fallbackLanguage="en">` + `useCometChatTranslation()` | **Provider component, NOT `CometChatLocalize.init`** |
-| Angular (v5) | `CometChatLocalize.init({ language, fallbackLanguage })` | Object (same shape as React) |
-| Android (V5/V6) | `CometChatLocalize.setLocale(context, "es")` | Method `setLocale(Context, String code)` — NOT a `Locale` |
-| iOS (V5) | `CometChatLocalize.set(locale: "es")` | Method `set(locale:)` (String or `Language`) — NOT `setLocale` |
-| Flutter (V5/V6) | `MaterialApp(localizationsDelegates: [cc.Translations.delegate, …], supportedLocales: […], locale: Locale('es'))` | **No `CometChatLocalize`** — register the kit's `Translations` delegate + drive via `Locale`; read with `Translations.of(context)` |
-
-The agent must consult this table before writing any localization code. **Verify against the installed package's type definitions** if uncertain — the localization surface genuinely differs per family (e.g. React Native moved from a `CometChatLocalize` class to the `<CometChatI18nProvider>` component; Flutter never had a `CometChatLocalize` class).
-
----
-
-## When to call init/setLocale
-
-After CometChat init is configured but before mounting any kit components:
-
-```ts
-// 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. 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) {}
-  })
-}
-```
-
-```swift
-// 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)
-}
-```
-
-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)
-
-```ts
-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) — `translations` prop on the provider
-
-```tsx
-<CometChatI18nProvider
-  selectedLanguage="es"
-  translations={{ es: { CHATS: "Charla", MESSAGES: "Mensajes" } }}
->
-  {/* … */}
-</CometChatI18nProvider>
-```
-
-Add a brand-new language the same way: `translations={{ custom: { CHATS: "…" } }}` with `selectedLanguage="custom"`.
-
-### Angular
-
-Init with the object signature, then register custom strings via `addTranslation` (v5):
-
-```ts
-CometChatLocalize.init({ language: "es" });
-CometChatLocalize.addTranslation({
-  es: { CHAT: "Charla", MESSAGES: "Mensajes" },
-});
-```
-
-### Android
+## Never render a raw key
+A snake_case token in the UI (`group_info`, `add_members`, `sample_*`) means a **missing or wrong key** — the localizer returns the key on a miss. Causes and fixes:
+- The component isn't inside the kit provider/localization context → wrap it (the provider auto-wires localization).
+- The key changed across majors (v5→v6/v7 moved keys, some under `sample_*`) → look up the CURRENT key in the kit's `resources/<lang>/translation.json` or the localize doc; don't guess.
+- You hardcoded a raw key as a label → use the component or the localized-string accessor.
 
-The Android kit has **no string-override API** on `CometChatLocalize` (no `addStringResources`/`setStringResources`). Override individual strings the Android-native way — add a `values-es/strings.xml` with the kit's string keys to your app resources; Android resource resolution picks them up for the active locale.
+## RTL (Arabic, Hebrew, Farsi, Urdu)
+- Set the document/layout direction to RTL for RTL locales (web: `dir="rtl"` on the app root or the locale-driven wrapper; native: the platform's RTL layout support). The kit follows the surrounding direction; your host must set it.
+- **React Native exception:** the RN kit ships **no RTL locale** — its built-in languages (≈18, plus English regional aliases; `{DOCS_BASE}/ui-kit/react-native/localize` → Supported Languages) are all LTR (no Arabic/Hebrew/Farsi/Urdu). An RTL language is only possible as a custom `translations` entry + a matching `selectedLanguage`, with the host handling layout direction — re-check that page before promising RTL chat on React Native.
+- Don't hard-code left/right margins/paddings on the kit's ancestors — use logical properties (`margin-inline-start`, etc.) so your chrome mirrors correctly.
+- Verify icons/affordances that imply direction (back, send) read correctly mirrored.
 
-```kotlin
-CometChatLocalize.setLocale(context, "es")   // selects the locale; string overrides live in res/values-es/
-```
-
-### iOS
-
-iOS has **no `setStringResources` API** either. Override strings via your app's `Localizable.strings` (per-locale `.lproj`) using the kit's string keys; `set(locale:)` only selects the active locale.
-
-```swift
-CometChatLocalize.set(locale: "es")   // overrides live in es.lproj/Localizable.strings
-```
-
-### Flutter
-
-Flutter has **no `CometChatLocalize.init`** — subclass the kit's `Translations` delegate to override or add strings, and register your delegate *before* `cc.Translations.delegate` in `MaterialApp.localizationsDelegates` (full recipe in `documentation/docs/ui-kit/flutter/localize.mdx`):
-
-```dart
-class MyTranslations extends cc.Translations {
-  @override
-  String get chats => 'Charla';   // override individual getters
-}
-// register MyTranslationsDelegate() ahead of cc.Translations.delegate
-```
-
----
-
-## 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:
-
-```ts
-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).
-
-```ts
-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:
-
-```ts
-// React/RN/Angular (object signature) — fallbackLanguage is a settings field
-CometChatLocalize.init({ language: "es", fallbackLanguage: "en-US" });
-```
-
-Angular v5's `LocalizationSettings` carries `fallbackLanguage` (verified in `cometchat-localize.ts` — defaults to `en-US`). RN's `<CometChatI18nProvider>` takes a `fallbackLanguage` prop. Flutter's `Translations` delegate and iOS's `set(locale:)` don't expose an explicit fallback arg — they fall back to English internally, so the skill doesn't try to override it there.
-
----
-
-## Detecting the user's preferred language
-
-```ts
-// 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`).
-
----
-
-## 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:
-
-```tsx
-<div key={language}>
-  <CometChatConversations />
-</div>
-```
-
-This is the workaround for kits that cache localized strings at first render.
-
----
-
-## Advanced init options + date/time formatting (web / JS family)
-
-`CometChatLocalize.init(settings)` (web, RN, Angular) accepts more than a language — the `LocalizationSettings` carries options the basic recipe omits (all verified in `cometchat-uikit-react-v6/src/resources/CometChatLocalize/cometchat-localize.ts`):
-
-- **`translationsForLanguage`** — inject custom string overrides at init (sugar for `addTranslation`).
-- **`missingKeyHandler`** — a callback invoked with any key that has no translation (log it, or return a fallback). Great for catching gaps in custom languages.
-- **`timezone`** — IANA zone string (e.g. `"America/New_York"`) used when the kit formats timestamps.
-
-**Date/time formatting** is controlled with `CalendarObject` (exported from the kit, `utils/CalendarObject.ts`) — pass one globally or per-component (e.g. a component's `lastActiveAtDateTimeFormat`-style prop) to control how the kit renders relative/absolute times. Query the docs MCP / `ui-kit/react/localize` for the full `CalendarObject` field list and the `flag_message_reason_*` / `message_composer_mention_*` translation-key conventions.
-
-> These are web/JS-family details. Native families (Android/iOS/Flutter) localize through their own resource/string mechanisms — see the per-family `-core`/`-troubleshooting` skills.
-
----
-
-## Anti-patterns
-
-1. **Using the wrong localization surface for the family.** Web + **Angular v5** take `CometChatLocalize.init({ language })` (object); **React Native v5** uses `<CometChatI18nProvider>` + `useCometChatTranslation` (NO `CometChatLocalize.init`); **Android** uses `CometChatLocalize.setLocale(context, "es")`; **iOS** uses `CometChatLocalize.set(locale: "es")`; **Flutter** has no `CometChatLocalize` — register the kit's `Translations` delegate. The legacy positional `init("es")` only ever applied to Angular **v4**. Verify against the installed package's types if unsure.
-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
-
----
+## Also
+- **Dates/times/numbers** localize with the locale; confirm the family's date-format option (v6+ added date-format controls) matches the user's region.
+- **User-generated content is not translated** by localization — that's the `message-translation` feature (per-message, `cometchat-<family>-features`), a different thing from UI-Kit localization.
+- **Keep host i18n and kit i18n in sync** — when your app switches language, also switch the kit's language so the chat doesn't stay in the old one: set `CometChatLocalize` (React · Angular · iOS · Android), or change the `selectedLanguage` prop on `CometChatI18nProvider` (**React Native** — there is no `CometChatLocalize` setter there).
 
-## Pointers
+## Common pitfalls
+1. **Raw keys in the UI** — missing/renamed key or missing provider; look up the current key, don't guess.
+2. **Carrying an API across families/majors** — v6 React changed codes/keys; fetch per family.
+3. **Locale set after render** — set it before/with init so the surface mounts localized.
+4. **RTL not applied by the host** — the kit mirrors within the direction you set; set `dir`/layout direction yourself.
+5. **Confusing UI localization with message translation** — different features.
 
-- `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"
+## Verify it works
+Switching the app language re-renders the chat in that language · no snake_case keys appear in the UI · custom/overridden strings show · an RTL locale mirrors layout and direction-sensitive icons · dates/times read in the locale · your language switcher and the kit's language (`CometChatLocalize`, or React Native's `selectedLanguage` prop) stay in sync.