i18next
A powerful internationalization framework for Effector which is based on i18next.
Installation
First, you need to install integration and its peer dependency:
pnpm install @withease/i18next i18next
yarn add @withease/i18next i18next
npm install @withease/i18next i18next
API
Initialization
All you need to do is to create an integration by calling createI18nextIntegration
with an integration options:
instance
: an instance of i18next or Store with i18next instance; it is better to pass a Store because it will be possible to use isolated i18next instance and avoid using global state.setup
: after this Event all listeners will be installed, and the integration will be ready to use; it is required because it is better to use explicit initialization Event in the application.teardown?
: after this Event all listeners will be removed, and the integration will be ready to be destroyed.
import i18next from 'i18next';
import { createStore, createEvent, fork, allSettled } from 'effector';
import { createI18nextIntegration } from '@withease/i18next';
// Event that should be called after application initialization
const appStarted = createEvent();
// Create Store for i18next instance
const $i18nextInstance = createStore(null);
const integration = createI18nextIntegration({
// Pass Store with i18next instance to the integration
instance: $i18nextInstance,
setup: appStarted,
});
// You can fill $someInstance later during runtime
// e.g., during fork on client or server
const scope = fork({
values: [[$i18nextInstance, i18next.createInstance(/* ... */)]],
});
await allSettled(appStarted, { scope });
Usage
Returned from createI18nextIntegration
integration contains the following fields:
$t
A Store containing a translation function, can be used anywhere in your app.
const { $t } = createI18nextIntegration({
/* ... */
});
const $someTranslatedString = $t.map((t) => t('cityPois.buttonText'));
The second argument is an optional object with options for the translation function.
const $city = createStore({ name: 'Moscow' });
const { $t } = createI18nextIntegration({
/* ... */
});
const $someTranslatedString = combine({ city: $city, t: $t }, ({ city, t }) =>
t('cityPois.buttonText', {
cityName: city.name,
})
);
In both cases, result will be a Store containing a translated string. It will be updated automatically when the language or available translations will be changed.
translated
A factory that returns Store containing a translated string.
const { translated } = createI18nextIntegration({
/* ... */
});
const $someTranslatedString = translated('premiumLabel.BrandOne');
The second argument is an optional object with options for the translation function. Options can be a Store or a plain value.
const $city = createStore({ name: 'Moscow' });
const { translated } = createI18nextIntegration({
/* ... */
});
const $someTranslatedString = translated('cityPois.buttonText', {
cityName: $city.map((city) => city.name),
});
Also, you can pass a template string with Store parts of a key:
const $pathOfAKey = createStore('BrandOne');
const { translated } = createI18nextIntegration({
/* ... */
});
const $someTranslatedString = translated`premiumLabel.${$pathOfAKey}`;
Result of the factory will be a Store containing a translated string. It will be updated automatically when the language or available translations will be changed.
$isReady
A Store containing a boolean value that indicates whether the integration is ready to use.
const { $isReady } = createI18nextIntegration({
/* ... */
});
reporting
An object with the following fields:
missingKey
, Event will be triggered when a key is missing in the translation resources, requires addingsaveMissing
option to the i18next instance.
const { reporting } = createI18nextIntegration({
/* ... */
});
sample({ clock: reporting.missingKey, target: sendWarningToSentry });