Localization - CometChat Docs

AI Agent Component Spec

Field	Value
Package	`@cometchat/chat-uikit-react`
Import	`import { CometChatLocalize } from "@cometchat/chat-uikit-react";`
Set language	`CometChatLocalize.setCurrentLanguage("fr")`
Init with config	`CometChatLocalize.init({ language: "es", fallbackLanguage: "en-US", disableAutoDetection: false })`
Add translations	`CometChatLocalize.addTranslation({ "en-US": { "welcome_message": "Welcome!" } })`
Supported languages	19: en-US, en-GB, nl, fr, de, hi, it, ja, ko, pt, ru, es, tr, zh, zh-TW, ms, sv, lt, hu
Date formatting	Use `CalendarObject` for custom date/time patterns
Source	GitHub

The CometChatLocalize class manages multi-language localization for the UI Kit. It handles automatic language detection, manual language switching, custom translations, and date/time formatting.

Supported Languages

Language	Code
English (United States)	`en-US`
English (United Kingdom)	`en-GB`
Dutch	`nl`
French	`fr`
German	`de`
Hindi	`hi`
Italian	`it`
Japanese	`ja`
Korean	`ko`
Portuguese	`pt`
Russian	`ru`
Spanish	`es`
Turkish	`tr`
Chinese	`zh`
Chinese (Traditional)	`zh-TW`
Malay	`ms`
Swedish	`sv`
Lithuanian	`lt`
Hungarian	`hu`

Language JSON files on GitHub

LocalizationSettings

Configuration interface for CometChatLocalize.init().

Property	Type	Description
`language`	`string`	Language code (e.g., `"en"`, `"fr"`) for the current localization
`translationsForLanguage`	`{ [key: string]: any }`	Key-value pairs for translations in the current language
`disableAutoDetection`	`boolean`	Disables automatic language detection based on browser/device settings
`fallbackLanguage`	`string`	Fallback language code if the primary language is not available
`disableDateTimeLocalization`	`boolean`	Disables localization for date and time values, forcing the default format
`timezone`	`string`	Timezone for date and time formatting (e.g., `"America/New_York"`, `"Europe/London"`)
`calendarObject`	`CalendarObject`	Custom calendar format for localized date and time formatting
`missingKeyHandler`	`(key: string) => void`	Handles missing translation keys with custom error handling or fallbacks

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

CometChatLocalize.init({
    language: "es",
    fallbackLanguage: "en-US",
    translationsForLanguage: {
        "es": { 
            "welcome_message": "¡Bienvenido a CometChat!", 
            "logout_message": "Has cerrado sesión con éxito." 
        },
        "fr": {
            "welcome_message": "Bienvenue sur CometChat!",
            "logout_message": "Vous vous êtes déconnecté avec succès."
        }
    },
    disableAutoDetection: false,
    disableDateTimeLocalization: false,
    timezone: "Europe/Madrid",
    calendarObject: new CalendarObject({
        today: "[Hoy a las] hh:mm A",
        yesterday: "[Ayer a las] hh:mm A",
        lastWeek: "[Última semana el] dddd",
        otherDays: "DD MMM YYYY, hh:mm A",
        relativeTime: {
            minute: "%d minuto atrás",
            minutes: "%d minutos atrás",
            hour: "%d hora atrás",
            hours: "%d horas atrás",
        }
    }),
    missingKeyHandler: (key) => `Missing translation for: ${key}`,
});

CalendarObject

Defines customizable formatting for date and time representation. Supports relative time formatting for minutes and hours.

Changing this format globally updates the date and time representation wherever it is used. If a component-specific CalendarObject is provided, it takes higher precedence over the global settings.

Property	Type	Description
`today`	`string`	Format for dates on the same day. Example: `"Today at hh:mm A"`
`yesterday`	`string`	Format for dates on the previous day. Example: `"Yesterday at hh:mm A"`
`lastWeek`	`string`	Format for dates within the last 7 days. Example: `"Last week on dddd"`
`otherDays`	`string`	Format for dates that do not fit other categories. Example: `"DD MMM YYYY, hh:mm A"`
`relativeTime`	`object`	Custom formatting for relative time expressions
`relativeTime.minute`	`string`	Single minute format. Example: `"%d minute ago"`
`relativeTime.minutes`	`string`	Multiple minutes format. Example: `"%d minutes ago"`
`relativeTime.hour`	`string`	Single hour format. Example: `"%d hour ago"`
`relativeTime.hours`	`string`	Multiple hours format. Example: `"%d hours ago"`

new CalendarObject({
    today: "[Hoy a las] hh:mm A",
    yesterday: "[Ayer a las] hh:mm A",
    lastWeek: "[Última semana el] dddd",
    otherDays: "DD MMM YYYY, hh:mm A",
    relativeTime: {
        minute: "%d minuto atrás",
        minutes: "%d minutos atrás",
        hour: "%d hora atrás",
        hours: "%d horas atrás",
    }
})

Component Guide

The translation configurations in this section are to be defined inside the CometChat’s init() method callback.

Report Message

To add translations for any flag reason, define a key in the form flag_message_reason_id_{reason_id} with the translated strings. Translations for flag_message_reason_id_spam, flag_message_reason_id_sexual, flag_message_reason_id_harassment are present by default. The reason name is displayed when the required translation is not found.

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

CometChatLocalize.addTranslation({
    "en-GB": {
        "flag_message_reason_id_dislike": "I just don't like it",
    },
    "es": {
        "flag_message_reason_id_dislike": "Simplemente no me gusta",
    }
});

Mention All

To add translations for a custom mentionAllLabel, define a key in the form message_composer_mention_{label}. The translation for message_composer_mention_all is present by default.

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

CometChatLocalize.addTranslation({
    "en-GB": {
        "message_composer_mention_channel": "channel",
    },
    "es": {
        "message_composer_mention_channel": "canal",
    }
});

Methods

init

Initializes the localization system with default values and optional configurations.

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

CometChatLocalize.init({
    language: "es",
    fallbackLanguage: "en-US",
    disableAutoDetection: false,
    timezone: "Europe/Madrid",
    missingKeyHandler: (key) => `Missing translation: ${key}`,
});

getBrowserLanguage

Detects the language set in the user’s browser or device settings.

const userLang = CometChatLocalize.getBrowserLanguage();
console.log(userLang);

getLocalizedString

Fetches localized text based on the current language.

const translatedText = CometChatLocalize.getLocalizedString("welcome_message");

getCurrentLanguage

Returns the currently set language for the UI Kit.

console.log(CometChatLocalize.getCurrentLanguage());

getDefaultLanguage

Returns the system-preferred language. If disableAutoDetection is enabled, returns the fallback language. Otherwise returns the browser’s preferred language.

console.log(CometChatLocalize.getDefaultLanguage());

setCurrentLanguage

Updates the language at runtime without reloading the application.

CometChatLocalize.setCurrentLanguage("fr");

addTranslation

Adds custom translations to the existing ones dynamically. New translations are merged into the existing localization data.

CometChatLocalize.addTranslation({
    "en-US": { "welcome_message": "Welcome to CometChat!" }
});

formatDate

Formats a Unix timestamp (seconds) based on a CalendarObject configuration. Uses the timezone set via init().

Parameter	Type	Description
`timestamp`	`number`	Unix timestamp in seconds
`calendarObject`	`CalendarObject`	Calendar configuration for formatting

Returns a formatted date string.

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

const formatted = CometChatLocalize.formatDate(1700000000, new CalendarObject({
    today: "hh:mm A",
    yesterday: "[Yesterday]",
    lastWeek: "dddd",
    otherDays: "DD MMM YYYY, hh:mm A"
}));

getDateLocaleLanguage

Returns the language code used for date localization. If disableDateTimeLocalization is true, returns "en-US". Otherwise returns the current language.

const dateLang = CometChatLocalize.getDateLocaleLanguage();

Customization

Global Configuration

Apply a custom date format globally across the whole UI Kit via CometChatLocalize.init():

CometChatLocalize.init({
   calendarObject: new CalendarObject({
        today: "hh:mm A",
        yesterday: "[Yesterday]",
        otherDays: "DD MMM YYYY, hh:mm A"
    })
});

Component-Specific Configuration

Apply a custom date format only within a specific component. Component-level CalendarObject overrides the global settings.

<CometChatMessageHeader 
    group={groupObj} 
    lastActiveAtDateTimeFormat={new CalendarObject({
        today: "[Today at] hh:mm A",
        yesterday: "[Yesterday at] hh:mm A",
        otherDays: "DD MMM YYYY, hh:mm A"
    })}
/>

​Supported Languages

​LocalizationSettings

​CalendarObject

​Component Guide

​Report Message

​Mention All

​Methods

​init

​getBrowserLanguage

​getLocalizedString

​getCurrentLanguage

​getDefaultLanguage

​setCurrentLanguage

​addTranslation

​formatDate

​getDateLocaleLanguage

​Customization

​Global Configuration

​Component-Specific Configuration

Supported Languages

LocalizationSettings

CalendarObject

Component Guide

Report Message

Mention All

Methods

init

getBrowserLanguage

getLocalizedString

getCurrentLanguage

getDefaultLanguage

setCurrentLanguage

addTranslation

formatDate

getDateLocaleLanguage

Customization

Global Configuration

Component-Specific Configuration