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

# Upgrading from V5 to V6

> Migration guide for upgrading from CometChat React UI Kit v5 to v6 with breaking changes and new patterns.

<Accordion title="AI Integration Quick Reference">
  | Field            | Value                                                                                                                        |
  | ---------------- | ---------------------------------------------------------------------------------------------------------------------------- |
  | Package          | `@cometchat/chat-uikit-react` (replaces v5 packages)                                                                         |
  | New init pattern | `UIKitSettingsBuilder` + `CometChatUIKit.init()`                                                                             |
  | Theming          | CSS variables replace inline style objects. See [Theming](/ui-kit/react/theme)                                               |
  | Localization     | `CometChatLocalize.init(settings)` — language codes changed (e.g., `en` → `en-US`), new `CalendarObject` for date formatting |
  | Key changes      | `setLocale` → `setCurrentLanguage`, `localize` → `getLocalizedString`, `datePattern` → `CalendarObject`-based props          |
</Accordion>

The CometChat v6 React UI Kit introduces a revamped localization system with enhanced support for language management, date formatting, and missing key handling. This guide outlines the key differences and provides a step-by-step migration process from v5 to v6.

***

## Overview of Changes

| Feature                  | v5                                                     | v6                                                                       |
| ------------------------ | ------------------------------------------------------ | ------------------------------------------------------------------------ |
| Initialization           | Used `init(language, resources)` with separate params. | Uses `init(settings: LocalizationSettings)` with a configuration object. |
| Translation Management   | Manually updated translations using `resources`.       | Uses `translationsForLanguage` in `init()` and `addTranslation()`.       |
| Language Codes           | Used shorthand codes (e.g., `en`, `fr`).               | Uses full language-region codes (e.g., `en-US`, `fr`).                   |
| Date & Time Localization | Not configurable.                                      | Supports `CalendarObject` for date formatting.                           |
| Timezone Handling        | Not available.                                         | Introduced `timezone` setting.                                           |
| Missing Key Handler      | Not available.                                         | Introduced `missingKeyHandler` to handle missing translations.           |

***

## CometChatLocalize

### Initialization

In CometChat v5 UI Kit, the [`CometChatLocalize.init()`](/ui-kit/react/v5/localize#methods) accepts 2 parameters: `language` & `resources`

```js title="V5 UI Kit" lines theme={null}
CometChatLocalize.init("en", {
  CHATS: "Chats",
});
```

In CometChat v6 UI Kit, the [`CometChatLocalize.init()`](/ui-kit/react/localize#initialize-cometchatlocalize) method accepts a [localization setting](/ui-kit/react/localize#localizationsettings) instead of individual parameters.

```js title="V6 UI Kit" lines theme={null}
CometChatLocalize.init({
  language: "en-US",
  translationsForLanguage: {
    "en-US": { conversation_chat_title: "Chats" },
  },
  disableAutoDetection: false,
  disableDateTimeLocalization: false,
  timezone: "Europe/Madrid",
  calendarObject: new CalendarObject({
    today: "hh:mm A",
    yesterday: "[Yesterday]",
    otherDays: "DD MMM YYYY, hh:mm A",
    relativeTime: {
      minute: "%d minute ago",
      minutes: "%d minutes ago",
      hour: "%d hour ago",
      hours: "%d hours ago",
    },
  }),
  missingKeyHandler: (key) => `Missing translation: ${key}`,
});
```

***

### Language Code Changes

In CometChat v5 UI Kit, the language code for English was `en`. In CometChat v6 UI Kit, the language codes have been expanded to distinguish between regional variants:

* `en-US` for American English
* `en-GB` for British English

There are no changes for any other languages.

***

### Managing Translations

In CometChat v5 UI Kit, the only way to add or override translations was by passing them in the [`init()`](/ui-kit/react/v5/localize#methods) method.

```js title="V5 UI Kit" lines theme={null}
CometChatLocalize.init("en", {
  CHATS: "Chats",
});
```

In CometChat v6 UI Kit, translations can be added or overridden using the [`init()`](/ui-kit/react/localize#initialize-cometchatlocalize) method or the [`addTranslation()`](/ui-kit/react/localize#add-custom-translations) method.

```js title="V6 UI Kit" lines theme={null}
CometChatLocalize.addTranslation({
  "en-US": { conversation_chat_title: "Chats" },
});
```

***

### Handling Date & Time Localization

CometChat v5 UI Kit lacked support for date formatting, but CometChat v6 UI Kit introduces the [`CalendarObject`](/ui-kit/react/localize#calendarobject) for date and time formatting.

```js title="V6 UI Kit" lines theme={null}
const formattedDate = new CalendarObject({
  today: "[Today at] hh:mm A",
  yesterday: "[Yesterday at] hh:mm A",
  otherDays: "DD MMM YYYY, hh:mm A",
});
CometChatLocalize.init({
  calendarObject: formattedDate,
});
```

***

### Handling Missing Translation Keys

CometChat v5 UI Kit did not handle missing translation keys, whereas CometChat v6 UI Kit introduces a [`missingKeyHandler`](/ui-kit/react/localize#initialize-cometchatlocalize) for better control.

```javascript title="V6 UI Kit" lines theme={null}
CometChatLocalize.init({
  missingKeyHandler: (key) => `Missing translation: ${key}`,
});
```

***

### Migrating JSON Translation Files

In CometChat v5 UI Kit, the language code for English was `en`.

```json title="V5 UI Kit" lines theme={null}
{
  "en": {
    "CHATS": "Chats"
  }
}
```

In CometChat v6 UI Kit, the language codes have been expanded to distinguish between regional variants: `en-US` & `en-GB`.

```json title="V6 UI Kit" lines theme={null}
{
  "en-US": {
    "conversation": "conversation_chat_title"
  }
}
```

Make sure your JSON translation files follow the new format.

***

## Additional Resources

<CardGroup cols={2}>
  <Card title="CometChatLocalize Class" icon="code" href="https://github.com/cometchat/cometchat-uikit-react/blob/v6/src/resources/CometChatLocalize/cometchat-localize.ts">
    View the source code for the localization class.
  </Card>

  <Card title="Language JSON Files" icon="language" href="https://github.com/cometchat/cometchat-uikit-react/tree/v6/src/resources/CometChatLocalize/resources">
    Browse all available language translation files.
  </Card>
</CardGroup>

***

## Property Changes

In CometChat v6 UI Kit, several props and methods in components and the CometChatLocalize class have been updated. Below is a detailed reference of renamed, added, and removed properties and methods.

### Conversations

#### New Properties

| Name                      | Type           | Description                                                                        |
| ------------------------- | -------------- | ---------------------------------------------------------------------------------- |
| lastMessageDateTimeFormat | CalendarObject | Format for displaying the timestamp of the last message in the conversations list. |

#### Removed Properties

| Name        | Type         | Description                                                                        |
| ----------- | ------------ | ---------------------------------------------------------------------------------- |
| datePattern | DatePatterns | Format for displaying the timestamp of the last message in the conversations list. |

### Message Header

#### New Properties

| Name                       | Type           | Description                                                              |
| -------------------------- | -------------- | ------------------------------------------------------------------------ |
| lastActiveAtDateTimeFormat | CalendarObject | Format for displaying the "last active" timestamp in the message header. |

### Message List

#### New Properties

| Name                        | Type           | Description                                                                       |
| --------------------------- | -------------- | --------------------------------------------------------------------------------- |
| separatorDateTimeFormat     | CalendarObject | Format for the date separators in the message list.                               |
| stickyDateTimeFormat        | CalendarObject | Format for sticky date headers displayed in the message list.                     |
| messageSentAtDateTimeFormat | CalendarObject | Format for the timestamp displayed next to messages.                              |
| messageInfoDateTimeFormat   | CalendarObject | Format for timestamps displayed in message details (e.g., delivery or read time). |

#### Removed Properties

| Name        | Type         | Description                                                       |
| ----------- | ------------ | ----------------------------------------------------------------- |
| datePattern | DatePatterns | Format for the date separators & sticky date in the message list. |
| timePattern | DatePatterns | Format for the timestamp displayed next to messages.              |

### Thread Header

#### New Properties

| Name                        | Type           | Description                                          |
| --------------------------- | -------------- | ---------------------------------------------------- |
| separatorDateTimeFormat     | CalendarObject | Format for the date separators.                      |
| messageSentAtDateTimeFormat | CalendarObject | Format for the timestamp displayed next to messages. |

### Call Logs

#### New Properties

| Name                        | Type           | Description                                                  |
| --------------------------- | -------------- | ------------------------------------------------------------ |
| callInitiatedDateTimeFormat | CalendarObject | Format for displaying the call initiation time in call logs. |

#### Removed Properties

| Name        | Type         | Description                                  |
| ----------- | ------------ | -------------------------------------------- |
| datePattern | DatePatterns | Format for rendering dates in the call logs. |

### CometChatLocalize Class

#### New Methods

| Name                  | Description                                                       |
| --------------------- | ----------------------------------------------------------------- |
| addTranslation        | Adds custom translations to the default translations.             |
| getDefaultLanguage    | Returns the default language.                                     |
| getDateLocaleLanguage | Returns the language used for date localization.                  |
| formatDate            | Formats a timestamp based on the provided calendar configuration. |

#### Renamed Methods

| Name               | Description                                              | Old Name  |
| ------------------ | -------------------------------------------------------- | --------- |
| getCurrentLanguage | Gets the current language.                               | getLocale |
| setCurrentLanguage | Sets the current language.                               | setLocale |
| getLocalizedString | Localizes the given string based on the active language. | localize  |

#### Removed Methods

| Name               | Description                                                        |
| ------------------ | ------------------------------------------------------------------ |
| getLanguageCode    | Returns the language code of current language.                     |
| setDefaultLanguage | Sets the default language if no language is passed in init method. |
| isRTL              | Returns true if the active language is rtl otherwise return false. |
| getDir             | Returns `rtl` or `ltr` based on the active language.               |

***

## Next Steps

<CardGroup cols={2}>
  <Card title="React.js Integration" href="/ui-kit/react/react-js-integration">
    Fresh v6 setup guide for React.js.
  </Card>

  <Card title="Components Overview" href="/ui-kit/react/components-overview">
    Explore all v6 prebuilt UI components.
  </Card>

  <Card title="Theme" href="/ui-kit/react/theme">
    New CSS variable-based theming system.
  </Card>

  <Card title="Methods" href="/ui-kit/react/methods">
    Init, login, logout, and other UI Kit methods.
  </Card>
</CardGroup>

***