packages/ra-i18n-i18next/README.md
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:
npm install --save ra-i18n-i18next
import { Admin } from 'react-admin';
import { useI18nextProvider, convertRaTranslationsToI18next } from 'ra-i18n-i18next';
import englishMessages from 'ra-language-english';
const App = () => {
const i18nProvider = useI18nextProvider({
options: {
resources: {
en: {
translation: convertRaTranslationsToI18next(englishMessages)
}
}
}
});
if (!i18nProvider) return (<div>Loading...</div>);
return (
<Admin i18nProvider={i18nProvider}>
...
</Admin>
);
};
useI18nextProvider hookA 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.
import { Admin } from 'react-admin';
import { useI18nextProvider, convertRaTranslationsToI18next } from 'ra-i18n-i18next';
import englishMessages from 'ra-language-english';
const App = () => {
const i18nProvider = useI18nextProvider({
options: {
resources: {
en: {
translation: convertRaTranslationsToI18next(englishMessages)
}
}
}
});
if (!i18nProvider) return (<div>Loading...</div>);
return (
<Admin i18nProvider={i18nProvider}>
...
</Admin>
);
};
| 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 |
i18nextInstanceThis 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>
);
};
optionsThis 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>
);
};
availableLocalesThis 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>
);
};
convertRaTranslationsToI18next functionA function that takes translations from a standard react-admin language package and converts them to i18next format. It transforms the following:
%{foo} to {{foo}} unless a prefix and/or a suffix are provided"key": "foo |||| bar" to multiple keys "foo_one": "foo" and "foo_other": "bar"import englishMessages from 'ra-language-english';
import { convertRaTranslationsToI18next } from 'ra-i18n-18next';
const messages = convertRaTranslationsToI18next(englishMessages);
| 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 |
optionsIf you provided interpolation options to your i18next instance, you should provide them when calling this function:
import englishMessages from 'ra-language-english';
import { convertRaTranslationsToI18next } from 'ra-i18n-18next';
const messages = convertRaTranslationsToI18next(englishMessages, {
prefix: '#{',
suffix: '}#',
});