Introduce ra-i18n-i18next

docs/Translation.md

@@ -130,6 +130,70 @@ const App = () => (
 
 Check [the translation setup documentation](./TranslationSetup.md) for details about `ra-i18n-polyglot` and how to configure it.
 
+## `ra-i18n-i18next`
+
+React-admin also provides a package called `ra-i18n-i18next` that leverages [the i18next library](https://www.i18next.com/) to build an `i18nProvider` based on a dictionary of translations.
+
+You might prefer this package over `ra-i18n-polyglot` when:
+- you already use i18next services such as [locize](https://locize.com/)
+- you want more control on how you organize translations, leveraging [multiple files and namespaces](https://www.i18next.com/principles/namespaces)
+- you want more control on how you [load translations](https://www.i18next.com/how-to/add-or-load-translations)
+- you want to use features not available in Polyglot such as:
+    - [advanced formatting](https://www.i18next.com/translation-function/formatting);
+    - [nested translations](https://www.i18next.com/translation-function/nesting)
+    - [context](https://www.i18next.com/translation-function/context)
+
+```tsx
+// in src/i18nProvider.js
+import i18n from 'i18next';
+import { useI18nextProvider, convertRaTranslationsToI18next } from 'ra-i18n-i18next';
+import en from 'ra-language-english';
+import fr from 'ra-language-french';
+
+const i18nInstance = i18n.use(
+    resourcesToBackend(language => {
+        if (language === 'fr') {
+            return import(
+                `ra-language-french`
+            ).then(({ default: messages }) =>
+                convertRaTranslationsToI18next(messages)
+            );
+        }
+        return import(`ra-language-english`).then(({ default: messages }) =>
+            convertRaTranslationsToI18next(messages)
+        );
+    })
+);
+
+export const useMyI18nProvider = () => useI18nextProvider({
+    i18nInstance,
+    availableLocales: [
+        { locale: 'en', name: 'English' },
+        { locale: 'fr', name: 'French' },
+    ],
+});
+
+// in src/App.tsx
+import { Admin } from 'react-admin';
+import { useMyI18nProvider } from './i18nProvider';
+
+const App = () => {
+    const i18nProvider = useMyI18nProvider();
+    if (!i18nProvider) return null;
+
+    return (
+        <Admin
+            i18nProvider={i18nProvider}
+            dataProvider={dataProvider}
+        >
+            ...
+        </Admin>
+    );
+};
+```
+
+Check [the ra-i18n-i18next documentation](https://github.com/marmelab/react-admin/tree/master/packages/ra-i18n-i18next) for details.
+
 ## Translation Files
 
 `ra-i18n-polyglot` relies on JSON objects for translations. This means that the only thing required to add support for a new language is a JSON file.

packages/ra-i18n-i18next/README.md

@@ -0,0 +1,228 @@
+# i18next i18n provider for react-admin
+
+i18next i18n provider for [react-admin](https://github.com/marmelab/react-admin), the frontend framework for building admin applications on top of REST/GraphQL services. It relies on [i18next](https://www.i18next.com/).
+
+You might prefer this package over `ra-i18n-polyglot` when:
+- you already use i18next services such as [locize](https://locize.com/)
+- you want more control on how you organize translations, leveraging [multiple files and namespaces](https://www.i18next.com/principles/namespaces)
+- you want more control on how you [load translations](https://www.i18next.com/how-to/add-or-load-translations)
+- you want to use features not available in Polyglot such as:
+    - [advanced formatting](https://www.i18next.com/translation-function/formatting);
+    - [nested translations](https://www.i18next.com/translation-function/nesting)
+    - [context](https://www.i18next.com/translation-function/context)
+
+## Installation
+
+```sh
+npm install --save ra-i18n-i18next
+```
+
+## Usage
+
+```tsx
+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
+
+```tsx
+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.
+
+```tsx
+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](https://www.i18next.com/overview/configuration-options) for details.
+
+```tsx
+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.
+
+```tsx
+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
+
+```ts
+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:
+
+```ts
+import englishMessages from 'ra-language-english';
+import { convertRaMessagesToI18next } from 'ra-i18n-18next';
+
+const messages = convertRaMessagesToI18next(englishMessages, {
+   prefix: '#{',
+  suffix: '}#',
+});
+```

packages/ra-i18n-i18next/package.json

@@ -0,0 +1,39 @@
+{
+    "name": "ra-i18n-i18next",
+    "version": "4.13.4",
+    "description": "i18next i18n provider for react-admin",
+    "main": "dist/cjs/index.js",
+    "module": "dist/esm/index.js",
+    "types": "dist/cjs/index.d.ts",
+    "sideEffects": false,
+    "files": [
+        "*.md",
+        "dist",
+        "src"
+    ],
+    "authors": [
+        "François Zaninotto"
+    ],
+    "repository": "marmelab/react-admin",
+    "homepage": "https://github.com/marmelab/react-admin#readme",
+    "bugs": "https://github.com/marmelab/react-admin/issues",
+    "license": "MIT",
+    "scripts": {
+        "build": "yarn run build-cjs && yarn run build-esm",
+        "build-cjs": "rimraf ./dist/cjs && tsc --outDir dist/cjs",
+        "build-esm": "rimraf ./dist/esm && tsc --outDir dist/esm --module es2015",
+        "watch": "tsc --outDir dist/esm --module es2015 --watch"
+    },
+    "dependencies": {
+        "i18next": "^23.5.1",
+        "ra-core": "^4.13.4",
+        "react-i18next": "^13.2.2"
+    },
+    "devDependencies": {
+        "cross-env": "^5.2.0",
+        "i18next-resources-to-backend": "^1.1.4",
+        "rimraf": "^3.0.2",
+        "typescript": "^5.1.3"
+    },
+    "gitHead": "e936ff2c3f887d2e98ef136cf3b3f3d254725fc4"
+}