@cometchat/skills 4.0.0 → 4.2.0

package/skills/cometchat-i18n/SKILL.md

@@ -0,0 +1,358 @@
+---
+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.
+license: "MIT"
+compatibility: "All CometChat UI Kit families v4.x / v5.x / v6.x"
+allowed-tools: "shell, file-read, file-search, file-list, ask-user"
+metadata:
+  author: "CometChat"
+  version: "4.0.0"
+  tags: "cometchat i18n localization l10n cometchatlocalize languages rtl arabic hebrew bundled-languages custom-language fallback cross-family"
+---
+
+## 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
+
+```ts
+import { CometChatLocalize } from "@cometchat/chat-uikit-react";
+
+CometChatLocalize.init({
+  language: "es",
+  fallbackLanguage: "en",
+});
+```
+
+Object literal. `init({ ... })`.
+
+### React Native (v5) — object signature
+
+```ts
+import { CometChatLocalize } from "@cometchat/chat-uikit-react-native";
+
+CometChatLocalize.init({
+  language: "es",
+  fallbackLanguage: "en",
+});
+```
+
+Same object signature as React.
+
+### Angular (v4) — POSITIONAL signature
+
+```ts
+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
+// Kotlin
+CometChatLocalize.setLocale(Locale.forLanguageTag("es"))
+```
+
+```java
+// 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
+
+```swift
+import CometChatUIKitSwift
+
+CometChatLocalize.setLocale(locale: "es")
+```
+
+`setLocale(locale:)`. Takes a String, not `Locale`.
+
+### Flutter V5 (GetX-based)
+
+```dart
+import 'package:cometchat_calls_uikit/cometchat_calls_uikit.dart';
+
+CometChatLocalize.init(language: 'es');
+```
+
+Named-arg, not positional. Single string.
+
+### Flutter V6 (Bloc-based)
+
+```dart
+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:
+
+```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
+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.
+
+---
+
+## 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",
+  resources: {
+    es: {
+      CHAT: "Charla",
+      MESSAGES: "Mensajes",
+      // ... override only the strings you want
+    },
+  },
+});
+```
+
+### Angular
+
+Positional second arg:
+
+```ts
+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.
+
+### iOS
+
+```swift
+CometChatLocalize.setLocale(locale: "es")
+CometChatLocalize.setStringResources(["CHAT": "Charla"], for: "es")
+```
+
+### Flutter
+
+```dart
+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:
+
+```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/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
+
+```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.
+
+---
+
+## 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"

package/skills/cometchat-ios/SKILL.md

@@ -2,7 +2,7 @@
 name: cometchat-ios
 description: Entry-point for CometChat iOS UI Kit integration in any Swift/iOS project. Detects the project type, gathers requirements through an interactive conversation, and writes production-quality integration code for UIKit and SwiftUI applications.
 license: "MIT"
-allowed-tools: "executeBash, readFile, fileSearch, listDirectory, AskUserQuestion"
+allowed-tools: "shell, file-read, file-search, file-list, ask-user"
 metadata:
   author: "CometChat"
   version: "3.0.0"
@@ -13,7 +13,7 @@ metadata:
 
 The user wants to add CometChat to any iOS project. Trigger phrases:
 
-- `/cometchat`
+- `/cometchat` (or invoke the cometchat-ios skill via your agent's mechanism — keyword "cometchat" or "integrate chat" works in most agents)
 - "add cometchat", "integrate cometchat", "add chat to my app"
 - "add messaging", "add chat ui", "add in-app chat"
 - "integrate chat in ios", "add chat to swift app"
@@ -84,7 +84,7 @@ Store this mental map — you'll use it throughout the conversation.
 
 **Ask the user for their CometChat credentials:**
 
-Use `AskUserQuestion`:
+Ask the user (preserve this exact shape — `question`, `header`, `multiSelect`, `options[].label`, `options[].description` — agents have varying primitive names but all support this structured form):
 - **question:** "Let's set up CometChat. Do you have your credentials?"
 - **header:** "CometChat Setup"
 - **multiSelect:** false
@@ -111,7 +111,7 @@ Direct them to:
 
 #### 3a. "What are you building?"
 
-Use `AskUserQuestion`:
+Ask the user (preserve the structured shape — `question`/`header`/`multiSelect`/`options[].label`/`options[].description`):
 - **question:** "What kind of app are you building?"
 - **header:** "Your app"
 - **multiSelect:** false
@@ -251,7 +251,7 @@ After writing code:
 
 ### Step 7 — Iteration menu
 
-Use `AskUserQuestion`:
+Ask the user (preserve the structured shape — `question`/`header`/`options[].label`/`options[].description`):
 - **question:** "What would you like to do next?"
 - **header:** "Next step"
 - **options:**