ra-i18n-polyglot

Polyglot i18n provider for react-admin

Polyglot i18n provider for react-admin, the frontend framework for building admin applications on top of REST/GraphQL services. It relies on polyglot.js, which uses JSON files for translations.

Installation

npm install --save ra-i18n-polyglot

Usage

Wrap the function exported by this package around a function returning translation messages based on a locale to produce a valid i18nProvider.

import * as React from "react";
import { Admin, Resource } from 'react-admin';
import polyglotI18nProvider from 'ra-i18n-polyglot';
import englishMessages from 'ra-language-english';
import frenchMessages from 'ra-language-french';

const messages = {
    fr: frenchMessages,
    en: englishMessages,
};

const i18nProvider = polyglotI18nProvider(locale => messages[locale]);

const App = () => (
    <Admin locale="en" i18nProvider={i18nProvider}>
        ...
    </Admin>
);

export default App;

Translation Messages

The message returned by the function argument should be a dictionary where the keys identify interface components, and values are the translated string. This dictionary is a simple JavaScript object looking like the following:

{
    ra: {
        action: {
            delete: 'Delete',
            show: 'Show',
            list: 'List',
            save: 'Save',
            create: 'Create',
            edit: 'Edit',
            cancel: 'Cancel',
        },
        ...
    },
}

All core translations are in the ra namespace, in order to prevent collisions with your own custom translations. The root key used at runtime is determined by the value of the locale prop.

The default messages are available here.

Asynchronous Locale Change

The function passed as parameter of polyglotI18nProvider can return a Promise for messages instead of a messages object. This lets you lazy load messages upon language change.

Note that the messages for the default locale (used by react-admin for the initial render) must be returned in a synchronous way.

import polyglotI18nProvider from 'ra-i18n-polyglot';
import englishMessages from 'ra-language-english';

const asyncMessages = {
    fr: () => import('ra-language-french').then(messages => messages.default),
    it: () => import('ra-language-italian').then(messages => messages.default),
};

const messagesResolver = locale => {
    if (locale === 'en') {
        // initial call, must return synchronously
        return englishMessages;
    }
    // change of locale after initial call returns a promise
    return asyncMessages[params.locale]();
}

const i18nProvider = polyglotI18nProvider(messagesResolver);

Using Specific Polyglot Features

Polyglot.js is a fantastic library: in addition to being small, fully maintained, and totally framework agnostic, it provides some nice features such as interpolation and pluralization, that you can use in react-admin.

const messages = {
    'hello_name': 'Hello, %{name}',
    'count_beer': 'One beer |||| %{smart_count} beers',
};

// interpolation
translate('hello_name', { name: 'John Doe' });
=> 'Hello, John Doe.'

// pluralization
translate('count_beer', { smart_count: 1 });
=> 'One beer'

translate('count_beer', { smart_count: 2 });
=> '2 beers'

// default value
translate('not_yet_translated', { _: 'Default translation' });
=> 'Default translation'

To find more detailed examples, please refer to http://airbnb.io/polyglot.js/

Changelog

v4.0.0

React-admin v4 focuses on modernizing the inner workings of the library. It improves the developper experience a great deal, and paves the way for future changes. It is the result of 6 months of intensive refactoring, development, and test.

The following list concerns version 4.0.0, as well as all the pre-releases (alpha, beta, and rc).

🎉 New features

• Add <Admin requireAuth> to hide the app until auth is checked (#7475)
• Add <Admin basename> to allow mounting react-admin inside a sub path (#7100, #6917)
• Add the ability to pass custom params to all dataProvider hooks (#7116)
• Add support for partial pagination (i.e. no total) (#7120)
• Add support for sx props in all ra-ui-materialui components (#7175)
• Add headless <Form> component (#7087)
• Add <ReferenceOneField> (#7060)
• Add <CustomRoutes> (#7345)
• Add useStore and persistent preferences (backport from ra-enterprise) (#7158, #7366)
• Add Saved Queries (#7354)
• Add <ToggleThemeButton> (#7340)
• Add <LocalesMenuButton> (#7332)
• Add useSetTheme (#7008)
• Add combineDataProvider helper (#7055)
• Add <Datagrid expandSingle> to limit the number of expanded rows to 1 (#7454)
• Add <ChoicesContextProvider> in all ReferenceInputs to avoid child cloning and allow choices filtering, pagination, and sorting (#7185)
• Add <FileInput validateFileRemoval> prop to allow confirmation before file deletion (#7003)
• Add ability to register custom <Resource options> (#7392)

📦 Dependency Updates

• Add React 18 compatibility (#7377)
• Upgrade material-ui to v5 (#6650)
• Use react-query for data fetching instead of home made solution (#6779, #6916, #7006, #7016, #7025, #6891, #7035, #7020, #7035, #7001)
• Replace react-final-form with react-hook-form (#7087)
• Upgrade react-router to V6 (#6873)
• Replace Quill by TipTap in <RichTextInput> (#7153)
• Upgrade dependencies to their latest major versions

🏹 Updated Syntax

• Change the Record TypeScript name to RaRecord (#7078)
• Change data provider hooks signature to reflect the data provider signature
• Remove prop injection and child cloning, use context instead (#7060, #7218, #7215, #7214, #7207, #7206, #7205, #7203).
• Remove record prop injection
• Remove permissions injection in main route controllers (#6921)
• Avoid cloning Inputs components to pass variant and margin, and document theme override instead (#7223)
• Rename loading to isLoading in authProvider hooks return type (#7334)
• Rename initialValues to defaultValues in <Form> (caused by switch to react-hook-form)
• Move bulkActionButtons from <List> to <Datagrid> (#7114)
• Rename currentSort to sort (#7076)
• Change setSort signature to make it consistent across components (#7065)
• Use Material UI autocomplete instead of our own (#6924, #6971)
• Rename <TranslationProvider> to <I18nContextProvider>
• Switch <WithPermissions> wrapping to a useAuthenticated hook in main controllers (#6921)
• Move <Notification> component into <AdminUI> to avoid gotchas when overriding the layout (#7082)

🧹 Cleanup

• Remove Redux (#7177)
• Remove redux-saga and saga-based side effects (#6684)
• Remove connected-react-router (#6704)
• Remove basePath (#7100)
• Remove addLabel prop in Field components (#7223)
• Remove Resource initialization, Store Resource definitions in Context rather than in store (#7051)
• Remove HOCs (like addField) and render props
• Remove useQuery and useMutation (as react-query already provides them) (#7001)
• Remove application cache and validUntil (#7001)
• Remove useVersion (#7001)
• Remove allowEmpty prop in choice inputs (#7200)
• Remove deprecated sort prop in <DataGridHeaderCell> (#7065)
• Remove <FormWithRedirect> and handleSubmitWithRedirect (#7087)
• Remove TestContext (<AdminContext> does the trick) and ra-test (#7148)
• Remove declarative side effects support in dataProvider (#6687)
• Remove useGetMatching (use getList instead) (#6916)
• Remove support for undoable prop now that we have mutationMode (#6711)
• Remove withTranslate HOC (#7157)
• Remove ra-test (#7148)
• Use esbuild instead of webpack for simple example
• Use GitHub actions instead of Travis for CI

📚 Updated Documentation

• The v4 documentation was deeply reorganized to allow easier discovery and faster navigation.
• Most of the common hooks and components now have a dedicated documentation page.
• We've added a Storybook to help you discover the components API.
• The demos (e-commerce, CRM) were updated to show how to build application in idiomatic react-admin.

🪜 Upgrade Guide

As this is a major release, there are breaking changes. We documented all the changes required in a react-admin v3 application to make it compatible with version 4 in the react-admin v4 Upgrade Guide.

📊 Statistics

• 1,259 changed files
• 2,210 commits
• 100,420 additions and 90,560 deletions (code and documentation)

Since react-admin counts about 112,000 lines of code, this means that 90% of the codebase was touched.

💌 Thank You

Many thanks to all the contributors (whether they helped developing, testing, documenting, proofreading react-admin v4), and in particular to the core team (fzaninotto, djhi, WiXSL) for their hard work.