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

# Localization

> Configure multi-language support, override translations globally, and add custom languages.

<Accordion title="AI Integration Quick Reference">
  | Field | Value |
  | - | - |
  | Package | `@cometchat/chat-uikit-angular` |
  | Key class | `CometChatLocalize` (static class for all localization) |
  | Key pipe | `TranslatePipe` (`translate` pipe in templates) |
  | Required setup | `CometChatUIKit.init(uiKitSettings)` |
  | Purpose | Multi-language support with runtime switching and global overrides |
  | Features | 19 built-in languages, runtime switching, custom translations |
  | Related | [Date/Time Formatting](/ui-kit/angular/customization/localization) \| [Theming](/ui-kit/angular/customization/theming) |
</Accordion>

CometChat UIKit supports 19 languages out of the box with runtime language switching. You can override translations globally without modifying source files.

| Capability | Description |
| - | - |
| Built-in languages | en-US, en-GB, de, fr, es, ja, ko, zh, zh-TW, ru, hi, ms, pt, sv, lt, hu, it, nl, tr |
| Runtime switching | Change language at any time via `setCurrentLanguage` |
| Global overrides | Replace any translation key for a language |
| Custom languages | Add entirely new languages at runtime |

***

## Setting the Language

```typescript expandable theme={null}
import { CometChatLocalize } from '@cometchat/chat-uikit-angular';

// Initialize with a specific language
CometChatLocalize.init({
  language: 'es',
  timezone: 'Europe/Madrid'
});

// Switch language at runtime
CometChatLocalize.setCurrentLanguage('fr');
```

***

## Global Translation Overrides

Override specific translation keys for any language:

```typescript expandable theme={null}
CometChatLocalize.addTranslation({
  'en-US': {
    'conversation_chat_title': 'Conversations',
    'conversation_delete': 'Remove',
    'message_composer_placeholder': 'Write something...'
  },
  'es': {
    'conversation_chat_title': 'Conversaciones',
    'conversation_delete': 'Eliminar'
  }
});
```

Existing keys are replaced; new keys are added. All other translations remain unchanged.

***

## Using the Translate Pipe

```html theme={null}
<!-- Basic usage -->
<h2>{{ 'conversation_chat_title' | translate }}</h2>

<!-- With parameters -->
<span>{{ 'add_n_members' | translate:{ n: 5 } }}</span>
```

### Resolution Priority

When resolving a translation key:

1. Global translation for current language
2. Fallback language translation (default: en-US)
3. Returns the key itself if nothing found

***

## Adding a New Language

```typescript expandable theme={null}
CometChatLocalize.addTranslation({
  'custom-lang': {
    'conversation_chat_title': 'Chats',
    'conversation_delete': 'Delete',
    'message_composer_placeholder': 'Type a message',
    // Add all required keys
  }
});

CometChatLocalize.setCurrentLanguage('custom-lang');
```

***

## Programmatic Translation

In TypeScript code (outside templates):

```typescript theme={null}
const title = CometChatLocalize.getLocalizedString('conversation_chat_title');
```

***

## Initialization Options

```typescript expandable theme={null}
CometChatLocalize.init({
  language: 'es',                    // Active language
  fallbackLanguage: 'en-US',         // Fallback when key not found
  timezone: 'Europe/Madrid',         // Timezone for date formatting
  disableAutoDetection: false,       // Disable browser language detection
  disableDateTimeLocalization: false, // Disable date/time localization
  translationsForLanguage: {         // Custom translations to merge
    'en-US': { 'custom_key': 'value' }
  },
  calendarObject: {                  // Custom date format (see Date/Time docs)
    today: 'HH:mm',
    yesterday: '[Yesterday]',
    lastWeek: 'dddd',
    otherDays: 'DD/MM/YYYY'
  },
  missingKeyHandler: (key) => {      // Called when a key is not found
    console.warn(`Missing translation: ${key}`);
  }
});
```

***

## Date & Time Localization

### CalendarObject

Use `CalendarObject` to customize how dates and times are displayed throughout the UIKit. 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"` |

```typescript expandable theme={null}
import { CometChatLocalize, CalendarObject } from '@cometchat/chat-uikit-angular';

new CalendarObject({
  today: '[Today at] hh:mm A',
  yesterday: '[Yesterday at] hh:mm A',
  lastWeek: '[Last week on] dddd',
  otherDays: 'DD MMM YYYY, hh:mm A',
  relativeTime: {
    minute: '%d minute ago',
    minutes: '%d minutes ago',
    hour: '%d hour ago',
    hours: '%d hours ago',
  }
})
```

### Global Configuration

Apply a custom date format globally via `CometChatLocalize.init()`:

```typescript expandable theme={null}
import { CometChatLocalize, CalendarObject } from '@cometchat/chat-uikit-angular';

CometChatLocalize.init({
  language: 'es',
  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',
    }
  })
});
```

### Component-Specific Configuration

Pass a `CalendarObject` directly to a component to override the global format for that component only:

```html theme={null}
<cometchat-message-header
  [group]="groupObj"
  [lastActiveAtDateTimeFormat]="customDateFormat"
></cometchat-message-header>
```

```typescript theme={null}
import { CalendarObject } from '@cometchat/chat-uikit-angular';

customDateFormat = new CalendarObject({
  today: '[Today at] hh:mm A',
  yesterday: '[Yesterday at] hh:mm A',
  otherDays: 'DD MMM YYYY, hh:mm A'
});
```

### formatDate

Format a Unix timestamp using a `CalendarObject` directly:

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

Returns a formatted date `string`.

```typescript expandable theme={null}
import { CometChatLocalize, CalendarObject } from '@cometchat/chat-uikit-angular';

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


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