> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-llms-scoped-indexes.mintlify.site/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/v6/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"
    })}
/>
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.