Localize

Overview

CometChat UI Kit provides language localization to adapt to the language of a specific country or region. This document outlines how a developer can customize localization provided by UI Kit to their requirements.

CometChatI18nProvider is a context provider that enables developers to supply custom translations and manage localization across their application.

Presently, the UI Kit supports 19 languages for localization, which are:

• English (en, en-US, en-GB)
• Chinese (zh, zh-TW)
• Spanish (es)
• Hindi (hi)
• Russian (ru)
• Portuguese (pt)
• Malay (ms)
• French (fr)
• German (de)
• Swedish (sv)
• Lithuanian (lt)
• Hungarian (hu)
• Italian (it)
• Korean (ko)
• Japanese (ja)
• Dutch (nl)
• Turkish (tr)

Customization

The CometChatI18nProvider component enables developers to pass custom translations. Developers can override existing translations or add new ones.

The CometChatI18nProvider component accepts the following props:

• selectedLanguage: The language to use for translations. Defaults to the user’s device language, or defaults to English if autoDetectLanguage is false.
• autoDetectLanguage: Whether to automatically detect the user’s device language.
• translations: An object containing the translation overrides for each language.

Users can provide new languages by adding a new key in the translations object.

To ensure the app dynamically adapts to the device’s language settings and properly displays localized content, it must be wrapped in the CometChatI18nProvider. Without this wrapper, automatic language detection and custom translations will not work in the app’s UI.

Prerequisites

To enable localization features in your React Native application, you need to install the react-native-localize package. This package provides native device locale detection and is required for the automatic language detection functionality.

Installation

Install the required dependency:

npm install react-native-localize

Usage

Here is how you can implement custom localization:

Basic Usage (System Language Detection)

TypeScript

import React from 'react';
import { SafeAreaView } from 'react-native';
import { 
  CometChatThemeProvider, 
  CometChatI18nProvider, 
} from '@cometchat/chat-uikit-react-native';

const App = () => {
  return (
    <SafeAreaView style={{ flex: 1 }}>
      <CometChatThemeProvider theme={{ mode: 'light' }}>
        <CometChatI18nProvider
         autoDetectLanguage={true}
        >
          {/* Other Components */}
        </CometChatI18nProvider>
      </CometChatThemeProvider>
    </SafeAreaView>
  );
};

Overriding Translations

TypeScript

import React from 'react';
import { SafeAreaView } from 'react-native';
import { 
  CometChatThemeProvider, 
  CometChatI18nProvider, 
} from '@cometchat/chat-uikit-react-native';

const App = () => {
  const translations = {
    // Overridden translations
    "en-US": {
      CHATS: 'Welcome to the CometChat App',
    },
    "en-GB": {
      CHATS: 'Welcome to CometChat',
    },
    custom: {
      CHATS: "Welcome"
    },
  };

  return (
    <SafeAreaView style={{ flex: 1 }}>
      <CometChatThemeProvider theme={{ mode: 'light' }}>
        <CometChatI18nProvider
          selectedLanguage="custom"
          translations={translations}>
          {/* Other Components */}
        </CometChatI18nProvider>
      </CometChatThemeProvider>
    </SafeAreaView>
  );
};

Using Translations in Custom Components

TypeScript

import React from 'react';
import { View, Text, TouchableOpacity } from 'react-native';
import { 
  useCometChatTranslation 
} from '@cometchat/chat-uikit-react-native';

const CustomComponent = () => {
  const { t } = useCometChatTranslation();

  return (
    <View style={{ padding: 20 }}>
      <Text style={{ fontSize: 18, fontWeight: 'bold' }}>
        {t("WELCOME_MESSAGE")}
      </Text>
      <TouchableOpacity 
        style={{ marginTop: 10, padding: 10, backgroundColor: '#007bff' }}
        onPress={() => {
          console.log(t("BUTTON_CLICKED"));
        }}>
        <Text style={{ color: 'white', textAlign: 'center' }}>
          {t("CLICK_HERE")}
        </Text>
      </TouchableOpacity>
    </View>
  );
};

CometChat UI-Kit provides a useCometChatTranslation hook to access translations within components, which can be used when developing custom components.

Customization Capabilities

Below are the things which the developer can customize:

• Set a supported language (selectedLanguage): The developer can set a language out of the 19 supported languages.
• Customize default localization strings (translations): The developer can customize default localization strings for a particular language.
• Add custom strings (translations): A developer can add custom strings in the localization for a particular language.
• Add a new language (translations): The developer can add completely new languages.
• Disable auto detection (autoDetectLanguage): The developer can disable auto detection of device language.
• Handle missing keys : The developer can handle missing localization key.
• Set fallback language (fallbackLanguage): The developer can set fallback language.

By using the CometChatI18nProvider component and useCometChatTranslation hook, you can provide a user-friendly, localized experience to your users, enhancing the overall user experience within your application.