> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-feature-react-native-sdk-quotedmessage-a.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Localization

## **Overview**

React UI Kit provides **multi-language localization** to **adapt** the UI elements based on the user's preferred language settings. The **CometChatLocalize** class allows developers to:

* **Automatically detect and apply a language** based on browser/device settings.
* **Manually change the UI language**.
* **Format date and time** based on localization settings.

The v6 React UI Kit expands support for **multiple languages** and allows developers to define **custom translations**.\
The localization system now includes **language JSON files**, which store translations, and an **improved CometChatLocalize class**, which handles language detection and formatting.

***

### **Supported Languages**

React UI Kit currently supports **19 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`    |

🔗 **View JSON files for all supported languages** in the GitHub repository:\
➡ [Language JSON Files](https://github.com/cometchat/cometchat-uikit-react/tree/v6/src/resources/CometChatLocalize/resources)

***

## **CometChatLocalize**

The `CometChatLocalize` class provides methods for managing localization in the UI Kit.

🔗 **View full class file in the GitHub repository:**\
➡ [CometChatLocalize](https://github.com/cometchat/cometchat-uikit-react/blob/v6/src/resources/CometChatLocalize/cometchat-localize.ts)

***

### **LocalizationSettings**

The `LocalizationSettings` interface defines various **localization settings** for an application or component. It allows developers to configure the language, translations, time zone, and calendar formatting while providing options for automatic detection and missing key handling.

| Property                      | Type                      | Description                                                                                         |
| ----------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------- |
| `language`                    | `string`                  | The language code (e.g., `"en"`, `"fr"`) for the current localization.                              |
| `translationsForLanguage`     | `{ [key: string]: any }`  | An object containing key-value pairs for translations in the current language.                      |
| `disableAutoDetection`        | `boolean`                 | Disables automatic language detection based on the browser or device settings.                      |
| `fallbackLanguage`            | `string`                  | The **fallback language code** to use if the primary language is not available.                     |
| `disableDateTimeLocalization` | `boolean`                 | Disables localization for **date and time values**, forcing the default format.                     |
| `timezone`                    | `string`                  | The **timezone** used for date and time formatting (e.g., `"America/New_York"`, `"Europe/London"`). |
| `calendarObject`              | `CalendarObject`          | A **custom calendar format** using `CalendarObject` to define localized date and time formatting.   |
| `missingKeyHandler`           | `(key: string) => string` | A function that **handles missing translation keys**, allowing custom error handling or fallbacks.  |

***

**Example**

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

CometChatLocalize.init({
    language: "es", // Default language set to Spanish
    fallbackLanguage: "en-US", // Use English if the preferred language is not available
    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, // Allow automatic detection of browser/device language
    disableDateTimeLocalization: false, // Enable localization for date and time
    timezone: "Europe/Madrid", // Set time zone for date and time formatting
    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}`, // Custom handler for missing translations
});
```

***

### **CalendarObject**

The `CalendarObject` class defines customizable formatting for date and time representation. It allows you to format dates based on whether they are today, yesterday, last week, or other days. It also supports relative time formatting for minutes and hours.

<Warning>
  Notice

  Changing this format will **globally update** the date and time representation wherever it is used in the component.\
  However, if a **component-specific** `CalendarObject` is provided, it will take **higher precedence** over the global settings.
</Warning>

| Property               | Type     | Description                                                                                     |
| ---------------------- | -------- | ----------------------------------------------------------------------------------------------- |
| `today`                | `string` | Custom formatting for dates that fall on the same day. Example: `"Today at hh:mm A"`            |
| `yesterday`            | `string` | Custom formatting for dates that fall on the previous day. Example: `"Yesterday at hh:mm A"`    |
| `lastWeek`             | `string` | Custom formatting for dates within the last 7 days. Example: `"Last week on dddd"`              |
| `otherDays`            | `string` | Custom formatting for dates that do not fit other categories. Example: `"DD MMM YYYY, hh:mm A"` |
| `relativeTime`         | `object` | Custom formatting for relative time expressions (e.g., "2 hours ago").                          |
| `relativeTime.minute`  | `string` | Formatting for a single minute. Example: `"%d minute ago"`                                      |
| `relativeTime.minutes` | `string` | Formatting for multiple minutes. Example: `"%d minutes ago"`                                    |
| `relativeTime.hour`    | `string` | Formatting for a single hour. Example: `"%d hour ago"`                                          |
| `relativeTime.hours`   | `string` | Formatting for multiple hours. Example: `"%d hours ago"`                                        |

***

**Example**

```javascript theme={null}
import { CometChatLocalize } from "@cometchat/chat-uikit-react";
import { CalendarObject } from "./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",
        }
    })
```

***

### **Component Guide**

<Warning>
  Note

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

#### Report Message

To add translations for any flag reason, a key in the form of `flag_message_reason_id_{reason_id}` is to be defined with the translated strings to be displayed for that `reason_id` in the UI. The translations for `flag_message_reason_id_spam`, `flag_message_reason_id_sexual`, `flag_message_reason_id_harassment` are present by default.

**Usage**

* Define translations for custom flag message reasons.
* The reason name would be displayed when the required translation is not found.

**Example**

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

// Add translations for flag reason keys for the required languages
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`, a key in the form of `message_composer_mention_{label}` is to be defined with the translated strings to be displayed for that label in the UI. The translations for `message_composer_mention_all` is present by default.

**Usage**

* Define translations for custom mentionAllLabel.
* Helps customize the `@all` label used in the app while mentioning all group members.

**Example**

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

// Add translations for mentionAllLabel for the required languages
CometChatLocalize.addTranslation({
    "en-GB": {
        "message_composer_mention_channel": "channel",
    },
    "es": {
        "message_composer_mention_channel": "canal",
    }
});
```

***

### **Methods**

#### Initialize CometChatLocalize

This method initializes the localization system with default values and optional configurations.

**Usage**

* Set the default language, timezone, and fallback settings.
* Define a custom calendar format if required.
* Customize how missing keys are handled.

**Example**

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

// Initialize localization settings
CometChatLocalize.init({
    language: "es", // Default language: Spanish
    fallbackLanguage: "en-US", // Fallback if translation is missing
    disableAutoDetection: false, // Enable browser language detection
    timezone: "Europe/Madrid",
    missingKeyHandler: (key) => `Missing translation: ${key}`,
});
```

***

#### Get Browser Language

This method detects the language set in the user's browser or device settings.

**Usage**

* Automatically set the app’s language based on the user’s browser settings.
* Helps in making the UI multilingual without requiring user input.

**Example**

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

***

#### Get Localized String

This method fetches localized text based on the current language.

**Usage**

* Retrieve translations dynamically without hardcoding values in multiple languages.
* Useful for UI elements, buttons, alerts, and system messages.

**Example**

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

***

#### Get Current Language

This method returns the currently set language for the UI Kit.

**Usage**

* Useful to debug and display the currently active language.
* Helps when dynamically switching between languages.

**Example**

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

***

#### Get Default Language

This method returns the system-preferred language.

**Usage**

* If disableAutoDetection is enabled, the method returns the fallback language.
* If auto-detection is enabled, it returns the browser's preferred language.

**Example**

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

***

#### Set Current Language

This method updates the language at runtime without reloading the application.

**Usage**

* Allow users to change the language via a settings menu.
* Ensure that UI elements are updated instantly after changing the language.

**Example**

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

***

#### Add Custom Translations

This method allows you to add custom translations to the existing ones dynamically. It ensures that new translations are merged into the existing localization data.

**Usage**

* You can define custom translation keys and override the existing translations.
* You can add new languages to the existing translations.
* Useful when you want to support additional words or phrases not present in the default language files.

**Example**

```javascript theme={null}
CometChatLocalize.addTranslation({
    "en-US": { "welcome_message": "Welcome to CometChat!" }
});
```

***

#### **Customisation**

CometChat UI Kit provides **flexible customization options** for date/time format. Users can configure **global settings** using `CometChatLocalize.init()` or pass a `CalendarObject` directly to individual components for **component-specific** customization.

* **Global Configuration:** When settings are provided in `CometChatLocalize.init()`, all UI components will automatically use the configured date/time formats.
* **Component-Specific Configuration:** If a `CalendarObject` is passed to a component, it **overrides** the global settings and applies only to that specific instance.

**Global Configuration Example**

To apply a **custom date format** globally across the whole UI Kit.

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

**Component-Specific Customization Example**

To apply a **custom date format** only within a specific component.

```csharp 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"
    })}
/>
```

***