Translation

The react-admin interface uses English as the default language. But it also supports any other language, thanks to the polyglot.js library.

Changing Locale

If you want to use another locale, you’ll have to install a third-party package. For instance, to change the interface to French, you must install the ra-language-french npm package then instruct react-admin to use it.

The <Admin> component has an i18nProvider prop, which accepts a function with the following signature:

const i18nProvider = locale => messages;

The messages should be a dictionary of interface and resource names (see the Translation Messages section below for details about the dictionary format).

React-admin calls the i18nProvider when it starts, passing the locale specified on the Admin component as parameter. The provider must return the messages synchronously. React-admin also calls the i18nProvider whenever the locale changes, passing the new locale as parameter. So the simplest example for a multilingual interface reads as follow:

import React from 'react';
import { Admin, Resource } from 'react-admin';
import frenchMessages from 'ra-language-french';
import englishMessages from 'ra-language-english';

const messages = {
    fr: frenchMessages,
    en: englishMessages,
}
const i18nProvider = locale => messages[locale];

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

export default App;

The i18nProvider may return a promise for locale change calls (except the initial call, when the app starts). This can be useful to only load the needed locale. For example:

import englishMessages from '../en.js';

const asyncMessages = {
    fr: () => import('../i18n/fr.js').then(messages => messages.default),
    it: () => import('../i18n/it.js').then(messages => messages.default),
};

const i18nProvider = 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 App = () => (
    <Admin locale="en" i18nProvider={i18nProvider}>
        ...
    </Admin>
);

Available Locales

You can find translation packages for the following languages:

In addition, the previous version of react-admin, called admin-on-rest, was translated in the following languages:

These packages are not directly interoperable with react-admin, but the upgrade is straightforward; rename the root key from “aor” to “ra”. We invite the authors of the packages listed above to republish their translations for react-admin, using a different package name.

If you want to contribute a new translation, feel free to submit a pull request to update this page with a link to your package.

Changing Locale At Runtime

If you want to offer the ability to change locale at runtime, you must provide the messages for all possible translations:

import React from 'react';
import { Admin, Resource } from 'react-admin';
import englishMessages from 'ra-language-english';
import frenchMessages from 'ra-language-french';

const messages = {
    fr: frenchMessages,
    en: englishMessages,
};
const i18nProvider = locale => messages[locale];

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

export default App;

Then, dispatch the CHANGE_LOCALE action, by using the changeLocale action creator. For instance, the following component switches language between English and French:

import React, { Component } from 'react';
import { connect } from 'react-redux';
import Button from '@material-ui/core/Button';
import { changeLocale as changeLocaleAction } from 'react-admin';

class LocaleSwitcher extends Component {
    switchToFrench = () => this.props.changeLocale('fr');
    switchToEnglish = () => this.props.changeLocale('en');

    render() {
        const { changeLocale } = this.props;
        return (
            <div>
                <div>Language</div>
                <Button onClick={this.switchToEnglish}>en</Button>
                <Button onClick={this.switchToFrench}>fr</Button>
            </div>
        );
    }
}

export default connect(undefined, { changeLocale: changeLocaleAction })(LocaleSwitcher);

Using The Browser Locale

React-admin provides a helper function named resolveBrowserLocale(), which helps you to introduce a dynamic locale attribution based on the locale configured in the user’s browser. To use it, simply pass the function as locale prop.

import React from 'react';
import { Admin, Resource, resolveBrowserLocale } from 'react-admin';
import englishMessages from 'ra-language-english';
import frenchMessages from 'ra-language-french';

const messages = {
    fr: frenchMessages,
    en: englishMessages,
};
const i18nProvider = locale => messages[locale];

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

export default App;

Translation Messages

The message returned by the i18nProvider value 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.

Translating Resource and Field Names

By default, React-admin uses resource names (“post”, “comment”, etc) and field names (“title”, “first_name”, etc) everywhere in the interface. It simply “humanizes” the technical identifiers to make them look better (e.g. “first_name” becomes “First name”).

However, before humanizing names, react-admin checks the messages dictionary for a possible translation, with the following keys:

  • ${locale}.resources.${resourceName}.name for resource names (used for the menu and page titles)
  • ${locale}.resources.${resourceName}.fields.${fieldName} for field names (used for datagrid header and form input labels)

This lets you translate your own resource and field names by passing a messages object with a resources key:

{
    resources: {
        shoe: {
            name: 'Shoe |||| Shoes',
            fields: {
                model: 'Model',
                stock: 'Nb in stock',
                color: 'Color',
            },
        },
        customer: {
            name: 'Customer |||| Customers',
            fields: {
                first_name: 'First name',
                last_name: 'Last name',
                dob: 'Date of birth',
            }
        }
    },
    ...
}

As you can see, polyglot pluralization is used here, but it is optional.

Using resources keys is an alternative to using the label prop in Field and Input components, with the advantage of supporting translation.

Mixing Interface and Domain Translations

When translating an admin, interface messages (e.g. “List”, “Page”, etc.) usually come from a third-party package, while your domain messages (e.g. “Shoe”, “Date of birth”, etc.) come from your own code. That means you need to combine these messages before passing them to <Admin>. The recipe for combining messages is to use ES6 destructuring:

// interface translations
import englishMessages from 'ra-language-english';
import frenchMessages from 'ra-language-french';

// domain translations
import * as domainMessages from './i18n';

const messages = {
    fr: { ...frenchMessages, ...domainMessages.fr },
    en: { ...englishMessages, ...domainMessages.en },
};
const i18nProvider = locale => messages[locale];

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

Translating Your Own Components

React-admin package provides a translate Higher-Order Component, which simply passes the translate function as a prop to the wrapped component:

// in src/MyHelloButton.js
import React from 'react';
import { translate } from 'react-admin';

const MyHelloButton = ({ translate }) => (
    <button>{translate('myroot.hello.world')}</button>
);

export default translate(MyHelloButton);

Tip: For your message identifiers, choose a different root name than ra and resources, which are reserved.

Tip: Don’t use translate for Field and Input labels, or for page titles, as they are already translated:

// don't do this
<TextField source="first_name" label={translate('myroot.first_name')} />

// do this instead
<TextField source="first_name" label="myroot.first_name" />

// or even better, use the default translation key
<TextField source="first_name" />
// and translate the `resources.customers.fields.first_name` key

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/

Notifications With Variables

It is possible to pass variables for polyglot interpolation with custom notifications. For example:

showNotification('myroot.hello.world', 'info', { messageArgs: { name: 'Planet Earth' } });

Assuming you have the following in your custom messages:

// in src/App.js
const messages = {
    en: {
        myroot: {
            hello: {
                world: 'Hello, %{name}!',
            },
        },
    },
};