Lazy I18n
Lazy i18n is a collection of React components and hooks that support internationalization for multiple languages by asynchronously loading key-value pair translation files.
Install
-
npm install lazy-i18n
or yarn add lazy-i18n
Use
Wrap your application in the I18nProvider
component. The locale
prop
specifies which translations should be used. The fallbackLocale
prop is an
optional value that specifies which translations should be used if a translation
is not present in the locale
. The translations
prop specifies translations
for each locale. In the following example, the en
locale is eagerly loaded
while the es
locale is lazily loaded.
import { I18nProvider } from 'lazy-i18n';
import en from './path/to/en.json';
const TRANSLATIONS = {
en, // <-- eager load
es: () => import('./path/to/es.json'), // <-- lazy load
};
function App() {
return (
<I18nProvider fallbackLocale="en" locale="es" translations={TRANSLATIONS}>
<Main />
</I18nProvider>
);
}
To use your translation files, you can import the I18n
component, passing the
translation key as a child and translation variables as props. Translation
variables will replace instances of $variableName
(prefixed with $
) with the
variable's value.
import I18n from 'lazy-i18n';
// Hello world!
function Main() {
return <I18n user="world">Hello $user!</I18n>;
}
You can also import the useTranslate
hook, where the first parameter is the
translation key and the second parameter is a record of translation variables.
This is useful when you need to translate props for a component that only
accepts strings.
import { useTranslate } from 'lazy-i18n';
function Picture() {
const translate = useTranslate();
// Hello world!
const alt = translate('Hello $user!', {
user: 'world',
});
return <img alt={alt} src="hello.jpg" />;
}
When a lazy-loaded translation has not yet loaded, the useTranslate
hook's
function will return undefined
. You can use this to render placeholder text.
import { useTranslate } from 'lazy-i18n';
function Title() {
const translate = useTranslate();
return <h1>{translate('My website') || '...'}</h1>;
}
API
I18n
The I18n
component translates its children based on the I18nProvider
context. Its props represent variables in the translation string.
<I18n var1="one" var2="two">three</I18n>
is analogous to
translate('three', { var1: 'one', var2: 'two' })
when using the useTranslate
hook.
import I18n from 'lazy-i18n';
function MyString() {
return (
<I18n var1="one" var2="two">
three
</I18n>
);
}
I18nProvider
import { I18nProvider } from 'lazy-i18n';
The I18nProvider
component provides a React context allowing the I18n
components and useTranslate
hooks to access the translations.
The I18nProvider
component accepts the following props:
fallbackLocale
Type: keyof translations
(optional)
When present, the I18n
component and useTranslate
hook will first attempt to
load translations from the locale
translations. Only if the locale
translations do not contain the specified translation key, the component or hook
will then load and look for the translation key in the fallback locale.
const ES = {
Spanish: 'Espanol',
};
const EN = {
English: 'English',
};
// Use English, but fallback to Spanish if a property does not exist in English.
function App() {
return (
<I18nProvider
fallbackLocale="es"
locale="en"
translations={{
en: EN,
es: ES,
}}
>
<Spanish />
</I18nProvider>
);
}
// Translate the string "Spanish."
function Spanish() {
return <I18n>Spanish</I18n>;
}
In the above example, since the string "Spanish" does not exist in the en
locale, the es
fallback locale will be used. <Spanish />
displays "Espanol"
to the user.
LoadingComponent
Type: ComponentType
optional
The LoadingComponent
prop specifies a component to render when using the
<I18n>
component while the translations are still loading.
By default, this component is three animating dots.
locale
Type: keyof translations
(required)
The locale
prop specifies the property in the translations
prop to use for
all translations.
translations
Type: Record<string, Translations>
(required)
The translations
prop contains all translations for all languages. As the
locale
prop changes, the I18n
component and useTranslate
hook will
re-render with the translations used in the translations
prop for the
specified locale.
useTranslate
import { useTranslate } from 'lazy-i18n';
The useTranslate
hook returns a function that translates a provided key.
function Button() {
const translate = useTranslate();
return <button>{translate('Submit')}</button>;
}
If your translation requires variables, you may pass them as the second
parameter to the translate
function.
function Button({ type = 'form' }) {
const translate = useTranslate();
return <button>{translate('Submit $type', { type })}</button>;
}
<Button type="form" /> // Submit form
<Button type="order" /> // Submit order
<Button type="resume" /> // Submit resume
Types
Translations
The Translations
type provided to the translations
prop can be an
eager-loaded or lazy-loaded Record<string, string>
. Example valid values:
- Default exports:
import en from './en.json';
- Dynamic imports:
const en = () => import('./en.json');
- Module exports:
const en = require('./en.json');
- On-demand imports:
const en = () => require('./en.json');