ra-i18n-i18next
v5.3.4
Published
i18next i18n provider for react-admin
Downloads
1,602
Readme
i18next i18n provider for react-admin
i18next adapter for react-admin, the frontend framework for building admin applications on top of REST/GraphQL services.
You might prefer this package over ra-i18n-polyglot
when:
- you already use i18next services such as locize
- you want more control on how you organize translations, leveraging multiple files and namespaces
- you want more control on how you load translations
- you want to use features not available in Polyglot such as:
Installation
npm install --save ra-i18n-i18next
Usage
import { Admin } from 'react-admin';
import { useI18nextProvider, convertRaMessagesToI18next } from 'ra-i18n-i18next';
import englishMessages from 'ra-language-english';
const App = () => {
const i18nProvider = useI18nextProvider({
options: {
resources: {
translations: convertRaMessagesToI18next(englishMessages)
}
}
});
if (!i18nProvider) return (<div>Loading...</div>);
return (
<Admin i18nProvider={i18nProvider}>
...
</Admin>
);
};
API
useI18nextProvider
hook
A hook that returns an i18nProvider for react-admin applications, based on i18next.
You can provide your own i18next instance but don't initialize it, the hook will do it for you with the options you may provide. Besides, this hook already adds the initReactI18next
plugin to i18next.
Usage
import { Admin } from 'react-admin';
import { useI18nextProvider, convertRaMessagesToI18next } from 'ra-i18n-i18next';
import englishMessages from 'ra-language-english';
const App = () => {
const i18nProvider = useI18nextProvider({
options: {
resources: {
translations: convertRaMessagesToI18next(englishMessages)
}
}
});
if (!i18nProvider) return (<div>Loading...</div>);
return (
<Admin i18nProvider={i18nProvider}>
...
</Admin>
);
};
Parameters
| Parameter | Required | Type | Default | Description |
| -------------------- | -------- | ----------- | ------- | ---------------------------------------------------------------- |
| i18nextInstance
| Optional | I18n | | Your own i18next instance. If not provided, one will be created. |
| options
| Optional | InitOptions | | The options passed to the i18next init function |
| availableLocales
| Optional | Locale[] | | An array describing the available locales. Used to automatically include the locale selector menu in the default react-admin AppBar |
i18nextInstance
This parameter lets you pass your own instance of i18next, allowing you to customize its plugins such as the backends.
import { Admin } from 'react-admin';
import { useI18nextProvider } from 'ra-i18n-i18next';
import i18n from 'i18next';
import Backend from 'i18next-http-backend';
import LanguageDetector from 'i18next-browser-languagedetector';
const App = () => {
const i18nextInstance = i18n
.use(Backend)
.use(LanguageDetector);
const i18nProvider = useI18nextProvider({
i18nextInstance
});
if (!i18nProvider) return (<div>Loading...</div>);
return (
<Admin i18nProvider={i18nProvider}>
...
</Admin>
);
};
options
This parameter lets you pass your own options for the i18n init
function.
Please refer to the i18next documentation for details.
import { Admin } from 'react-admin';
import { useI18nextProvider } from 'ra-i18n-i18next';
import i18n from 'i18next';
const App = () => {
const i18nProvider = useI18nextProvider({
options: {
debug: true,
}
});
if (!i18nProvider) return (<div>Loading...</div>);
return (
<Admin i18nProvider={i18nProvider}>
...
</Admin>
);
};
availableLocales
This parameter lets you provide the list of available locales for your application. This is used by the default react-admin AppBar to detect whether to display a locale selector.
import { Admin } from 'react-admin';
import { useI18nextProvider, convertRaTranslationsToI18next } from 'ra-i18n-i18next';
import i18n from 'i18next';
import resourcesToBackend from 'i18next-resources-to-backend';
const App = () => {
const i18nextInstance = i18n.use(
// Here we use a Backend provided by i18next that allows us to load
// the translations however we want.
// See https://www.i18next.com/how-to/add-or-load-translations#lazy-load-in-memory-translations
resourcesToBackend(language => {
if (language === 'fr') {
// Load the ra-language-french package and convert its translations in i18next format
return import(
`ra-language-french`
).then(({ default: messages }) =>
convertRaTranslationsToI18next(messages)
);
}
// Load the ra-language-english package and convert its translations in i18next format
return import(`ra-language-english`).then(({ default: messages }) =>
convertRaTranslationsToI18next(messages)
);
})
);
const i18nProvider = useI18nextProvider({
i18nextInstance,
availableLocales: [
{ locale: 'en', name: 'English' },
{ locale: 'fr', name: 'French' },
],
});
if (!i18nProvider) return (<div>Loading...</div>);
return (
<Admin i18nProvider={i18nProvider}>
...
</Admin>
);
};
convertRaMessagesToI18next
function
A function that takes translations from a standard react-admin language package and converts them to i18next format. It transforms the following:
- interpolations wrappers from
%{foo}
to{{foo}}
unless a prefix and/or a suffix are provided - pluralization messages from a single key containing text like
"key": "foo |||| bar"
to multiple keys"foo_one": "foo"
and"foo_other": "bar"
Usage
import englishMessages from 'ra-language-english';
import { convertRaMessagesToI18next } from 'ra-i18n-18next';
const messages = convertRaMessagesToI18next(englishMessages);
Parameters
| Parameter | Required | Type | Default | Description |
| -------------------- | -------- | ----------- | ------- | ---------------------------------------------------------------- |
| raMessages
| Required | object | | An object containing standard react-admin translations such as provided by ra-language-english |
| options
| Optional | object | | An object providing custom interpolation suffix and/or suffix |
options
If you provided interpolation options to your i18next instance, you should provide them when calling this function:
import englishMessages from 'ra-language-english';
import { convertRaMessagesToI18next } from 'ra-i18n-18next';
const messages = convertRaMessagesToI18next(englishMessages, {
prefix: '#{',
suffix: '}#',
});