const streami18n = new Streami18n();
Adding Internationalization (i18n)
If you deploy your app to users who speak another language, you’ll need to internationalize it. Stream’s Chat Client provides the option to translate the user-created contents of messages in addition to the UI. The React Native SDK’s UI Components are available in multiple languages out-of-the-box. At the moment we support the following languages (and more will be added in the future):
- English (en)
- French (fr)
- Hindi (hi)
- Italian (it)
- Dutch (nl)
- Turkish (tr)
- Russian (ru)
- Japanese (ja)
- Korean (ko)
Usage
The Streami18n
provides static translations for React Native components from the Stream Chat SDK.
Streami18n
is a class that uses a configuration of i18next with a subset of the functionality exposed.
Streami18n
is provided by stream-chat-react-native
and can be imported from the library.
The only step you need to start using Streami18n
is to create an instance of the class.
Streami18n
will default to English (en). If you choose to use the default English settings with Day.js you do
not need to deal directly with an instance of Streami18n
, this is taken care of for you.
If you choose to change the language, translation, or date handling, you will need to provide your modified instance of Streami18n
to the component library.
Two components require your custom instance of Streami18n
to properly pass your translation and time-date functions to the component library, OverlayProvider
and Chat
.
Both components accept an instance of Streami18n
via the prop i18nInstance
.
Providing this prop will provide your instance of Streami18n
to all of the components via context
instead of the default instance.
import { StreamChat } from 'stream-chat';
import { Chat, OverlayProvider, Streami18n } from 'stream-chat-react-native';
const client = StreamChat.getInstance('api_key');
const streami18n = new Streami18n();
export const App = () => (
<OverlayProvider i18nInstance={streami18n}>
<Chat client={client} i18nInstance={streami18n}>
{/** App components */}
</Chat>
</OverlayProvider>
);
Setting language for components
Stream provides built in translations for some languages out-of-the-box.
Streami18n
accepts two optional parameters when being instantiated, options
and i18nextConfig
.
These parameters allow you to modify the Streami18n
instance to your preferences.
As an example, let’s say we need to localize the UI of the application for a Dutch audience:
const streami18n = new Streami18n({ language: 'nl' }); // Instantiate Streami18n with Dutch strings.
Alternatively, you can also use setLanguage
method on Streami18n
class.
This is useful especially if you want to build language toggle functionality within your app.
For example, let’s say an application needs to default to English but support French:
const streami18n = new Streami18n();
...
// Logic for how a user can change the language
...
streami18n.setLanguage('fr'); // The UI will change to French.
Adding a new language
Let’s see how you can add support for additional languages in the SDK. As an example, we’ll implement a custom Polish language translation:
const streami18n = new Streami18n();
streami18n.registerTranslation('pl', {
'Copy Message': 'Kopiuj wiadomość',
'Delete Message': 'Usuń wiadomość',
'{{ firstUser }} and {{ secondUser }} are typing...': '{{ firstUser }} i {{ secondUser }} piszą...',
});
Please take a look at all the available texts here.
Overriding existing languages
You can also make line item changes to the strings for existing UI components. This is useful if you want to tweak an existing language to use regional spelling variants (American English vs. UK English, for example) same process as Adding a new language. As an example, we’ll override the translations for Dutch language:
const streami18n = new Streami18n();
streami18n.registerTranslation('nl', {
'Delete Message': 'Verwijder bericht',
});
Using device locale to set language
react-native-localize
package provides a toolbox for React Native app localization.
You can use this package to access user preferred locale, and use it to set language for chat components:
import * as RNLocalize from 'react-native-localize';
const streami18n = new Streami18n();
const userPreferredLocales = RNLocalize.getLocales();
streami18n.setLanguage(userPreferredLocales[0].languageCode);
Overriding DateTime format
React Native SDK uses Day.js internally by default to format DateTime stamp. Day.js is a lightweight alternative to Moment.js with the same modern API and has locale support as well.
Day.js provides locale config for plenty of languages, you can check the whole list of locale configs here
You can either provide the Day.js locale config while registering
language with Streami18n
(either via constructor or registerTranslation()
) or you can provide your own Day.js or Moment instance
to Streami18n constructor, which will be then used internally (using the language locale) in components.
const i18n = new Streami18n({
language: 'nl',
dayjsLocaleConfigForLanguage: {
months: [...],
monthsShort: [...],
calendar: {
sameDay: '...'
}
}
});
You can add locale config for moment while registering translation via registerTranslation
function:
const i18n = new Streami18n();
i18n.registerTranslation(
'mr',
{
'Nothing yet...': 'काहीही नाही ...',
'{{ firstUser }} and {{ secondUser }} are typing...':
'{{ firstUser }} आणि {{ secondUser }} टीपी करत आहेत ',
},
{
months: [...],
monthsShort: [...],
calendar: {
sameDay: '...'
}
}
);
Alternatively, you can use a utility library to handle DateTime by providing your own Moment
object:
import 'moment/locale/nl';
import 'moment/locale/it';
// or if you want to include all locales
import 'moment/min/locales';
import Moment from moment
const i18n = new Streami18n({
language: 'nl',
DateTimeParser: Moment
})
Or by providing your own Day.js object:
import Dayjs from 'dayjs';
import 'dayjs/locale/nl';
import 'dayjs/locale/it';
// or if you want to include all locales
import 'dayjs/min/locales';
const i18n = new Streami18n({
language: 'nl',
DateTimeParser: Dayjs,
});
If you would like to stick with English language for date-times in Stream components, you can set disableDateTimeTranslations
to true.
Translating messages
If your application has a user base that speaks more than one language, Stream’s Chat Client provides the option to automatically translate messages. For more information on using automatic machine translation for messages, see the Chat Client Guide on Translation.
Options
options
is the first optional parameter passed to Streami18n
, it is an object with all keys being optional.
DateTimeParser
Used for translating dates and times into the desired local format. Either Day.js or Moment can be used. Day.js is a dependency of the repository and used by default.
TYPE | DEFAULT |
---|---|
Dayjs | Moment | Dayjs |
dayjsLocaleConfigForLanguage
You can customize and create new locales using Day.js.
To allow accessibility to this option when using the default Day.js instance you can pass these customizations via the dayjsLocaleConfigForLanguage
key.
TYPE |
---|
object |
debug
Enable debug mode in internal i18next instance.
TYPE | DEFAULT |
---|---|
boolean | false |
disableDateTimeTranslations
Use the default English language date-times instead of those dictated by the language set.
TYPE | DEFAULT |
---|---|
boolean | false |
language
Language code for language to be used. The following options are available:
- English (
en
) - French (
fr
) - Hindi (
hi
) - Italian (
it
) - Dutch (
nl
) - Turkish (
tr
) - Russian (
ru
) - Japanese (
ja
) - Korean (
ko
)
TYPE | DEFAULT |
---|---|
string | en |
logger
Function to log warnings & errors from Streami18n
.
TYPE | DEFAULT |
---|---|
(msg?: string) => void | console.warn |
translationsForLanguage
Allows you to override the provided translations for given keys.
const streami18n = new Streami18n({
language: 'nl',
translationsForLanguage: {
'Nothing yet...': 'Nog Niet...',
'{{ firstUser }} and {{ secondUser }} are typing...': '{{ firstUser }} en {{ secondUser }} zijn aan het typen...',
},
});
TYPE |
---|
object |
I18NextConfig
i18NextConfig
is the second optional parameter passed to Streami18n
, it is an object with all keys being optional.
i18nextConfig
is used in the instantiation of the i18next instance and mostly aligns with the i18next options.
debug
Enable debug mode in internal i18next instance.
This overrides the debug
key on options if provided.
TYPE |
---|
boolean |
fallbackLng
Fallback language setting for i18next.
TYPE |
---|
FallbackLng |
interpolation
i18next interpolation setting for integrating dynamic values into translations.
TYPE | DEFAULT |
---|---|
object | { escapeValue: false } |
keySeparator
Override character to separate keys.
TYPE | DEFAULT |
---|---|
string | boolean | false |
lng
Override language to use.
TYPE |
---|
string |
nsSeparator
Override character to split namespace from key.
TYPE | DEFAULT |
---|---|
string | boolean | false |
parseMissingKeyHandler
Function to handle keys missing translations for the selected language.
TYPE | DEFAULT |
---|---|
(key: string) => string | (key) => key |
Methods
getAvailableLanguages
Returns an array of language code strings corresponding to available languages.
const availableLanguages = streami18n.getAvailableLanguages();
geti18Instance
Returns instance of i18next used within the Streami18n
instance.
const i18n = streami18n.geti18Instance();
getTranslations
Returns the current translations dictionaries for all languages.
const translations = streami18n.getTranslations();
getTranslators
Asynchronous function that returns the current translator functions.
const { t, tDateTimeParser } = await streami18n.getTranslators();
registerTranslation
Allows you to register a custom translation, this will override a translation if one already exists for the given language code. The third parameter, which is optional, is a Day.js locale, which is structured the same as dayjsLocaleConfigForLanguage.
It is suggested you look at the enTranslations.json
file exported from stream-chat-react-native
for a current list of used translation keys.
streami18n.registerTranslation('mr', {
'Nothing yet...': 'काहीही नाही ...',
'{{ firstUser }} and {{ secondUser }} are typing...': '{{ firstUser }} आणि {{ secondUser }} टीपी करत आहेत',
});
Parameters
NAME | TYPE | REQUIRED |
---|---|---|
language | string | ✔️ |
translation | object | ✔️ |
customDayjsLocale | object |
setLanguage
Asynchronous function that changes the current language and returns the new translation function.
If not initialized undefined
will be returned.
If the language fails to update the current translation function will be returned.
const t = await streami18n.setLanguage('nl');
Parameters
NAME | TYPE | REQUIRED |
---|---|---|
language | string | ✔️ |