cometchat-i18n

正解の参照元： UI Kit の CometChatLocalize API と docs/fundamentals です。公式ドキュメント： https://www.cometchat.com/docs/fundamentals/overview · Docs 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 フックを使用します（CometChatLocalize.init はありません）。 Android では CometChatLocalize.setLocale(context, "es")（Context とコード文字列）を使用し、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 ではプロバイダーコンポーネントとフックを使ってローカライズします。アプリを（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"

init ではなく setLocale を使用します。シグネチャは setLocale(Context, @Language.Code String) です。 Context と、2文字の言語コードを表す 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)

メソッドは setLocale(...) ではなく、set(locale:) です。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 の標準的な方法で設定します。キットの Translations ローカライゼーションデリゲートを MaterialApp に登録し、アプリの 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 で翻訳済みの文字列を取得します。独自の LocalizationsDelegate を cc.Translations のサブクラスとして実装し、リスト内で 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()	プロバイダーコンポーネントであり、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) で取得します

ローカライズコードを記述する前に、エージェントはこの表を確認する必要があります。不明な場合は、インストール済みパッケージの型定義を確認してください。ローカライズの仕様はファミリーごとに実際に異なります（たとえば、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）— プロバイダーの translations prop

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

同じ方法で新しい言語を追加できます。selectedLanguage="custom" を指定し、translations={{ custom: { CHATS: "…" } }} とします。

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

---

RTL 言語

アラビア語、ヘブライ語、ペルシア語、ウルドゥー語は右から左に表示されます。キットはロケールに基づいてレイアウト方向を自動的に処理しますが、次の点に注意してください。

1. ネイティブ iOS / Android：レイアウト方向は、デバイスのロケールまたは明示的に設定された CometChat のロケールのうち、最後に設定された方に従います。アプリでデバイスのロケールをアラビア語に設定していても、キットのロケールが英語だと、RTL の不一致が表示されます。
2. Web（React / Angular）：RTL を完全にサポートするには、<html dir="rtl"> が必要です。キットはドキュメントのルートからこの値を読み取ります。ロケールが変わったときに設定してください。

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

3. React Native：グローバルに RTL を切り替えるには I18nManager.forceRTL(true) を使用します。変更を反映するにはアプリの再起動が必要です（これは本番環境でよくある不具合のひとつです。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 の 2 文字コードを使用します。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 のシグネチャが、上の表のファミリーと一致している
• ロケールをキットの初期化後に設定すると、解決される
• サポートされている箇所（React、RN、Flutter）で fallbackLanguage を設定している
• 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 — 関連スキル。ローカライズとアクセシビリティを組み合わせることで、「本番環境向けの仕上げ」の大部分をカバーできます