> ## Documentation Index
> Fetch the complete documentation index at: https://www.cometchat.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Localization

> Configure multi-language localization, custom translations, and date/time formatting in CometChat React UI Kit.

<Accordion title="AI Integration Quick Reference">
  | 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](https://github.com/cometchat/cometchat-uikit-react/blob/v6/src/resources/CometChatLocalize/cometchat-localize.ts) |
</Accordion>

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](https://github.com/cometchat/cometchat-uikit-react/tree/v6/src/resources/CometChatLocalize/resources)

***

## 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              |

```javascript lines theme={null}
import { CometChatLocalize } from "@cometchat/chat-uikit-react";
import { CalendarObject } from "@cometchat/chat-uikit-react";

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.

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

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

```javascript lines theme={null}
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

<Warning>
  The translation configurations in this section are to be defined inside the [CometChat's init() method callback](/ui-kit/react/react-js-integration#step-3:-initialize-cometchat-ui-kit).
</Warning>

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

```javascript lines theme={null}
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.

```javascript lines theme={null}
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.

```javascript lines theme={null}
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.

```javascript lines theme={null}
const userLang = CometChatLocalize.getBrowserLanguage();
console.log(userLang);
```

### getLocalizedString

Fetches localized text based on the current language.

```javascript lines theme={null}
const translatedText = CometChatLocalize.getLocalizedString("welcome_message");
```

### getCurrentLanguage

Returns the currently set language for the UI Kit.

```javascript lines theme={null}
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.

```javascript lines theme={null}
console.log(CometChatLocalize.getDefaultLanguage());
```

### setCurrentLanguage

Updates the language at runtime without reloading the application.

```javascript lines theme={null}
CometChatLocalize.setCurrentLanguage("fr");
```

### addTranslation

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

```javascript lines theme={null}
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`.

```javascript lines theme={null}
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.

```javascript lines theme={null}
const dateLang = CometChatLocalize.getDateLocaleLanguage();
```

***

## Customization

### Global Configuration

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

```javascript lines theme={null}
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.

```tsx lines theme={null}
<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"
    })}
/>
```