Internationalization
How to internationalize a site or application that uses the HPE Design System.
Overview
Internationalizion (I18N) and Localization (L10N) are important for web content and applications which are intended to be used by global users. It's even important for users in a single location who simply speak different languages.
Internationalization is the process of tailoring application content to different languages or even locations. Localization is the process of translating content and behavior for a particular language or location.
Even if you don't localize the messages and content of your application or site in a
different language, users can benefit from your site being internationalized. Part
of internationalizating is making your site recognize the locale set in the browser
and format things like dates and times, currency and numbers specifically
for that locale. Browsers have great built-in support for formatting that content
appropriately for the locale. For example, a user in Australia or the United Kingdom
may be perfectly happy with your content being in English but would much prefer any
dates or times be presented with the day of the month before the month
(28/06/2021 versus 6/28/2021). This is easy to do with Date.toLocalDateString().
Guidelines
Depending on how your site or application is implemented, you'll need to pick an appropriate mechanism for choosing a language and locale and then provide content for the language and locale the user chose. You can provide a control in the application that allows the user to pick a language or simply try to use the preference set by the browser. Browsers include the user's locale preferences (if set) in header in the page request. Your application or site can choose localized content that best matches a locale from this list. Even if you don't have content for one of the preferred languages or allowed the user to set the language another way, it's best to still format dates, numbers and such given their preferred locale whenever possible.
Once the site has chosen a locale from the user's preferences your site needs to provide the appropriate content given the selected locale. If you have implemented your application with Grommet, there are some default messages for components like Menu and FormField that will require localization. For example, the required message that accompanies a required FormField.
Localizing Grommet
Messages needed for Grommet components can be provided in a single place by using the
messages property on the Grommet component itself.
<Grommet messages={{ messages: { textField: { required: 'This field is required' } ... } }}>
If you're using other packages for internationalization like react-intl or react-i18next, it's even easier to provide a function which accesses the messages on demand by id.
For react-intl:
import { useIntl } from 'react-intl'; ... const intl = useIntl(); ... <Grommet messages={{ format: options => intl.formatMessage(options) }}>
For react-i18next:
import { useTranslation } from 'react-intl'; ... const { t } = useTranslation(); ... <Grommet messages={{ format: ({id}) => t(id) }}>
Then just provide the Grommet messages along with your other localized messages. See the Grommet component documentation for details on what messages are needed.
If needed you can also provide customized messages to the Grommet components
which need them. The components which have localizable messages also support
a messages property which accepts their specific messages. In most cases it
easiest to provide the messages as above to the Grommet component instead.
However, if you want to specify customized messages for a component in a few
specific use cases you can certainly do that via the messages property
for those components.
Examples
To see some example code and localization of a Grommet application take a look
at the Grommet I18N example. It shows
how you can use either react-intl or react-i18next with Grommet and includes
a few localized language examples.
Still have questions?
Something missing or looking for more information? Get in touch to help make the HPE Design System better.