Adding Internationalization and Localization

The ESB includes two Web interfaces, namely the API Publisher and Developer Portal. The steps below explain how you can localize the API Publisher and the Developer Portal.

Changing the browser language

Note

  • The web applications are shipped with the following default and additional languages for demonstration and testing purposes.

    Web Application Supported Languages
    Default
    language
    Additional
    languages
    Developer Portal English Spanish
    Arabic
    Sinhala
    API Publisher English Sinhala

  • If the language that you set in the browser settings is not a supported language of the API Publisher and/or the Developer Portal web application, "English" is set as the language by default in the web applications.

  • Therefore, if you need to change the language and the language is not supported, make sure to add the language first before changing the browser language.

Set your browser language to a preferred language by following the user guide that corresponds to your browser.

For example, let's assume that you are using Google Chrome, and let's change the browser language to "Spanish".

  1. Navigate to the chrome://settings/languages URL in your browser.

    Chrome browser settings

  2. Add the highest preference to "Spanish", so that "Spanish" moves to the top of the language list.

  3. Refresh the API Publisher and Developer Portal web apps.

    The text in the browser will be translated into Spanish.

Adding a new language

Info

All the text in the Developer Portal or the API Publisher are loaded via an external JSON file. These JSON files are asynchronously fetched from the browser based on the browser locale. The locale files are available in the following locations.

Publisher <APIM_HOME>/repository/deployment/server/webapps/publisher/src/main/webapp/site/public/locales
Developer Portal <APIM_HOME>/repository/deployment/server/webapps/devportal/src/main/webapp/site/public/locales

Follow the instructions below to add a new language to the Developer Portal or the API Publisher.

Let's add support for the French language to the Developer Portal.

  1. Identify the two-letter locale code for the language that you want to add to the Developer Portal.

    The locale code for the French language is fr.

  2. Make a copy of the en.json file and rename it based on the locale code.

    Rename the copy of the <APIM_HOME>/repository/deployment/server/webapps/devportal/src/main/webapp/site/public/locales/en.json file to fr.json.

    Info

    If you are setting the browser locale to a specific regional language, for example, French (Switzerland), the language with the regional code is fr-ch. In this scenario too the two letter locale code is fr, because MWARE ESB does not support regional language switching.

  3. Change all the values that correspond to the key-value pairs to the language that you want to add to the Developer Portal.

    The JSON file (<locale-code>.json) has key-value pairs as follows:

    "Apis.Details.ApiConsole.ApiConsole.title": "Try Out",
    "Apis.Details.ApiConsole.SelectAppPanel.applications": "Appplications",
    1. Find the keys to modify.

    2. Convert each of the values into French.

Finding the keys to modify

Sometimes going through the list of keys and modifying each of the values that correspond to a specific language is not going to be enough. You may need to find a key that is responsible for a particular text in the UI. Let’s consider the following scenario.

Let's find the key for the main title named APIs in the following screen.

Main title highlighted in the Developer Portal

Prerequisites

  • Chrome web browser.
  • React Developer Tools extension for Google Chrome.
    1. Right-click over the title named APIs and select Inspect Element.

      Right click menu

      The Chrome Developer Tools will open.

    2. Click on Components and copy the ID of the text component.

      Inspect element window

    Changing the direction of the UI

    MWARE ESB has the capability of direction change for the Developer Portal web application. This feature enables you to entirely change the default direction of the UI from LTR (Left To Right) to RTL (Right to Left). This is required if you are trying to add support for languages such as Arabic.

    Follow the instructions below to change the direction of the UI:

    1. Add the specific configuration in the userTheme.json file.

      Add the following configuration to change the page direction to RTL (Right To Left).

      !!! note If you have already done customizations to the default theme, make sure to merge the following with the existing changes carefully.

       {
        "direction": "rtl",
      } 
    2. Reload the Developer Portal to view the changes.

    Info

    If you have done the theme changes for the instance via the <APIM_HOME>/repository/deployment/server/webapps/devportal/src/main/webapp/site/public/theme/userTheme.json file the above configuration is valid. However, if it is the tenant theme file (userTheme.json) the variable assignment is not required and the userTheme.json file has to be a valid JSON file. For example, the valid configuration that should go into the userTheme.json file to change the page direction to RTL (Right To Left) is as follows:

        {
        "direction": "rtl",
        }

    Tip

    Learn more about Tenant theming.

    Enabling the language switch

    MWARE ESB has the capability of language switching for the Developer Portal web application.

    Note

    • When you switch between languages via the language switch, it will take precedence over the browser locale.
    • If you do not select a language and -
      • If the browser locale exists in the list of languages given in the language switch, the browser locale will be automatically selected from the list of available languages.
      • If the browser locale does not exist in the list of languages, then "English" will get automatically set as the language switch.
    • When you enable the language switch, the direction of each language will take precedence over the root level direction.

    Follow the instructions below to enable the language switch:

    1. Open the <APIM_HOME>/repository/deployment/server/webapps/devportal/src/main/webapp/site/public/theme/userTheme.json file.

    2. Add the following configuration to the file to enable the language switch.

      Note

      If you have already done customizations to the default theme, make sure to merge the following with the existing changes carefully.

      {
          "custom": {
              "languageSwitch": {
                  "active": true,
                  "languages": [
                  {
                          "key": "en",
                          "image": "/site/public/images/flags/en.png",
                          "imageWidth": 24,
                          "text": "English",
                          "direction": "ltr"
                      }
                  ],
                  "showFlag": true,
                  "showText": true,
                  "minWidth": 60
              }
          }
      }
    3. Optionally, add a language.

      Note

      This is only applicable if you have added a new language to the respective web application, which is not a language that is available by default.

      const DefaultConfigurations = {
          direction: 'ltr',
          custom: {
              languageSwitch: {
                  active: true,
                  languages: [
                      {
                          key: 'fn',
                          image: '/site/public/images/flags/fn.png',
                          imageWidth: 24, // in pixles
                          text: 'French',
                          direction: 'ltr',
                      }
                  ]
              }
          }
      }
    4. Customize the language switch if required.

      The following are the additional parameters that are available to customize the language switch.

      Key value
      showFlag default set to true. Setting the value to false will hide the flag and display only the text.
      showText default set to true. Setting the value to false will hide the text and display only the flag.
      minWidth Sets the width of the whole element. The default is set to 60 pixels.
      const DefaultConfigurations = {
          direction: 'ltr',
          custom: {
              languageSwitch: {
                  active: false,
                  languages: [
                      {
                          key: 'fn',
                          image: '/site/public/images/flags/fn.png',
                          imageWidth: 24, // in pixles
                          text: 'French',
                          direction: 'ltr',
                      }
                  ],
                  showFlag: true,
                  showText: true,
                  minWidth: 60, // Width of the language switcher in pixles
              }
          }
      }
    5. Reload the Developer Portal to view the changes.

      Now, a switch will be displayed in the top menu to change the language.

      Switch language option

    Languages available by default

    The following are the languages available by default.

    "languages": [
                    {
                        "key": "en",
                        "image": "/site/public/images/flags/en.png",
                        "imageWidth": 24, // in pixles
                        "text": "English",
                        "direction": "ltr"
                    },
                    {
                        "key": "es",
                        "image": "/site/public/images/flags/sp.png",
                        "imageWidth": 24, // in pixles
                        "text": "Spanish",
                        "direction": "ltr"
                    },
                    {
                        "key": "ar",
                        "image": "/site/public/images/flags/ar.png",
                        "imageWidth": 24, // in pixles
                        "text": "Arabic",
                        "direction": "ltr"
                    },
                    {
                        "key": "si",
                        "image": "/site/public/images/flags/si.png",
                        "imageWidth": 24, // in pixles
                        "text": "Sinhala",
                        "direction": "ltr"
                    }
                ],

    The following is the complete configuration related to localization.

    {
        "custom": {
            "languageSwitch": {
                "active": true,
                "languages": [
                    {
                        "key": "en",
                        "image": "/site/public/images/flags/en.png",
                        "imageWidth": 24, // in pixles
                        "text": "English",
                        "direction": "ltr"
                    },
                    {
                        "key": "es",
                        "image": "/site/public/images/flags/sp.png",
                        "imageWidth": 24, // in pixles
                        "text": "Spanish",
                        "direction": "ltr"
                    },
                    {
                        "key": "ar",
                        "image": "/site/public/images/flags/ar.png",
                        "imageWidth": 24, // in pixles
                        "text": "Arabic",
                        "direction": "ltr"
                    },
                    {
                        "key": "si",
                        "image": "/site/public/images/flags/si.png",
                        "imageWidth": 24, // in pixles
                        "text": "Sinhala",
                        "direction": "ltr"
                    }
                ],
                "showFlag": true,
                "showText": true,
                "minWidth": 60 // Width of the language switcher in pixles
            }
         }
    }

    Advanced concepts

    The following document describes how i18n is implemented in the API Publisher and the Developer Portal web applications, how you can auto-generate the language file, and how to programmatically convert the locale file from one language to any other language.

    How internationalization (i18n) works in MWARE ESB React Apps

    Top