How internationalization (i18n) works in API Manager React Apps

Table of content

• Libraries in use
• Developer guide: How to add i18n support in code
  • ID naming convention
    • Example
  • Add internationalization support outside the render() method
  • Add i18n support using component.
  • Note!
• Extracting locale IDs and Messages from source
• How to add a new language file (For the testing purpose)
• Troubleshooting guide
  • How to use FormattedMessage inside an `` tag of select

Libraries in use

• react-intl i18n library for managing locales
• extract-react-intl-messages generating locale files

Developer guide: How to add i18n support in code

ID naming convention

If adding i18n element in publisher, Prefix the react-intl id with the path to the source file from

<APIM_PUBLISHER_ROOT>/source/src/app/components/

replace the / with ..

Example

If you are adding a <FormattedMessage /> to below file.

<APIM_PUBLISHER_ROOT>/source/src/app/components/Apis/Create/Components/APICreateTopMenu.jsx

_{<APIM_PUBLISHER_ROOT> is /features/apimgt/org.wso2.carbon.apimgt.publisher.feature/src/main/resources/publisher-new/}

use the id as

<FormattedMessage 
        id='Apis.Create.Components.APICreateTopMenu.click.to.create.api'
        defaultMessage='Click to create API' />

Add internationalization support outside the render() method

Alert.error(intl.formatMessage({
                id: 'Apis.Create.Components.APICreateTopMenu.unsupported.file.type',
                defaultMessage: 'Unsupported File Type.'})
           );

.
.
.
export default injectIntl(APIDefinition);

Add i18n support using component.

import { FormattedMessage } from 'react-intl';

.
.
.

    <Typography variant='display1'>
        <FormattedMessage defaultMessage='APIs - Create New API' />
    </Typography>

Using useIntl hook

If you prefer using hooks to get the formatMessage method, Use the useIntl hook for that.

Note!

Do Not Update the locale files (i:e en.json) manually. Files under the

/features/apimgt/org.wso2.carbon.apimgt.publisher.feature/src/main/resources/publisher-new/site/public/locales

directory are most probably auto-generated. We need to address the local extension problem here.

Extracting locale IDs and Messages from source

Run

npm run i18n

to generate default locale (en.json & fr.json) files. We have given en as the default language and defaultMessages are in the English language. The above command will generate a fr.json file with all the IDs , But without any values against them.

You could just rename it to any locale code you wish (i:e es.json, ja.json) and fill the relevant translated text in there.

Production build

npm run build:prod

will regenerate the locale files before the webpack bundling. Since we have configured to run a production build in mvn install process, Every maven build will regenerate the locale files.

How to add a new language file (For the testing purpose)

You can add a new language file using the default English language file( en.json ) by converting it using react-intl-auto-translate tool. Install the tool as the instruction given in the instruction. Goto locales directory and run the following command.

intl-translate en.json {target_local_code} {api_key}

{target_local_code} = Locale code that you want to convert the source file

{api_key} [Optional] = Google cloud api key for Translator cloud service, If not provided, It will use a sandbox API key.

For example:

intl-translate en.json si

This will generate a <locale_code>.json file in the locale directory. Now , Change the browser locale to your desired one and see the translated text in the app.

Note

Currently , React-intl auto translator does not ignore the placeholder text values in messages. i:e

<FormattedMessage
  id="app.greeting"
  description="Greeting to welcome the user to the app"
  defaultMessage="Hello, {name}!"
  values={{
    name: <b>Eric</b>,
  }}
/>

in the above code. `"Hello, {name}!" will be blindly translated to the target language.

Troubleshooting guide

How to use FormattedMessage inside an <option /> tag of select

<FormattedMessage
     id='Apis.Details.Configuration.Configuration.access.control.restricted.by.roles'
     defaultMessage='Restricted by roles'
>
     {placeholder => <option value='RESTRICTED'>{placeholder}</option>}
</FormattedMessage>