README
@commercetools-frontend/i18n
This package contains JSON data about the i18n messages from the different application-kit packages (e.g. application-shell
, etc). Additionally, it also loads locale data for moment
and react-intl
, which is necessary for runtime usage.
Install
$ npm install --save @commercetools-frontend/i18n
Supported locales
en
de
es
fr-FR
zh-CN
Usage
The
<AsyncLocaleData>
component, or theuseAsyncLocaleData
hook, are internally used by the<ApplicationShell>
and there is no need to use them directly. If you do need to load translation files asynchronously, we expose an additional hookuseAsyncIntlMessages
that you can use for that. The difference between those is that the "async locale data" components additionally load the application-kit and ui-kit messages, as well as the moment locales.
Using a React component with render props
With static messages
import { IntlProvider } from 'react-intl';
import { AsyncLocaleData } from '@commercetools-frontend/i18n';
const myApplicationMessages = {
en: {
Title: 'Application Title',
},
};
const Application = (props) => (
<AsyncLocaleData
locale={props.user.locale}
applicationMessages={myApplicationMessages}
>
{({ isLoading, locale, messages }) => {
if (isLoading) return null;
return (
<IntlProvider locale={locale} messages={messages}>
...
</IntlProvider>
);
}}
</AsyncLocaleData>
);
With dynamic loaded messages (code splitting)
import { IntlProvider } from 'react-intl';
import { AsyncLocaleData } from '@commercetools-frontend/i18n';
const loadMessages = (lang) => {
let loadAppI18nPromise;
switch (lang) {
case 'de':
loadAppI18nPromise = import(
'./i18n/data/de.json' /* webpackChunkName: "app-i18n-de" */
);
break;
case 'es':
loadAppI18nPromise = import(
'./i18n/data/es.json' /* webpackChunkName: "app-i18n-es" */
);
break;
default:
loadAppI18nPromise = import(
'./i18n/data/en.json' /* webpackChunkName: "app-i18n-en" */
);
}
return loadAppI18nPromise.then(
(result) => result.default,
(error) => {
// eslint-disable-next-line no-console
console.warn(
`Something went wrong while loading the app messages for ${lang}`,
error
);
return {};
}
);
};
const Application = (props) => (
<AsyncLocaleData
locale={props.user.locale}
applicationMessages={loadMessages}
>
{({ isLoading, locale, messages }) => {
if (isLoading) return null;
return (
<IntlProvider locale={locale} messages={messages}>
...
</IntlProvider>
);
}}
</AsyncLocaleData>
);
Using a React hook
Similarly to the <AsyncLocaleData>
, we also expose a React hook.
import { IntlProvider } from 'react-intl';
import { useAsyncLocaleData } from '@commercetools-frontend/i18n';
const Application = (props) => {
const { isLoading, locale, messages } = useAsyncLocaleData({
locale: props.locale,
applicationMessages: loadMessages,
});
if (isLoading) return null;
return (
<IntlProvider locale={locale} messages={messages}>
...
</IntlProvider>
);
};
Generating translation files
After you have defined the intl
messages in your React components, you should extract those messages into the source file core.json
. This file contains a key-value map of the message id
and the message value.
To extract the messages simply run mc-scripts extract-intl [options]
.
Syncing translations with Transifex
We use Transifex as our translation tool. Once we have extracted new messages into the source file core.json
(see mc-scripts extract-inl
) and pushed/merged to main
, the file will be automatically synced with Transifex using the Transifex GitHub Integration.
Translations that have been reviewed in Transifex will be automatically pushed back to GitHub by the Transifex Bot via a Pull Request.
Shared messages
This package exposes some "shared" messages that can be used for different things like buttons, etc. instead of having duplicated messages.
The messages are exported as sharedMessages
property.