Skip to content
Arc XP
Product Documentation

Internationalization

Supporting multiple languages and locales is a crucial aspect of building highly available multilingual sites. Internationalization, often abbreviated as i18n, easily allows for your web content to be translated to multiple languages. PageBuilder Engine lets you translate content by using an intl.json format powered by an Airbnb library called Polyglot.js, which lets you declare files containing your translations. You can place these intl.json files at the root of your feature pack.

Terminology

The following terms are the relevant resources for PageBuilder Engine internationalization:

  • locale property in site properties.
  • localeList value at the top level of a blocks.json for filtering languages included in compiled bundle (for Themes blocks only).
  • intl.json at root of your repo. See example for Themes overrides.
  • fusion:intl and getTranslatedPhrases (polyglot.js).

How to use internationalization

Internationalization properties in Theme Settings

If you are using Theme Settings to manage your site properties and configurations, you can update the locale, textDirection, textFlow, and dateLocalization properties within the application. For more details on the available settings, see Theme Settings configurations. If you are not using Themes or prefer to make the updates directly in your feature pack files, follow the guidance below. 

Internationalization in your feature pack

For only Themes blocks: To add internationalization to a feature, you must first add a localeList to your blocks.json to declare all the translations that you would like to support:

...
"localeList": [
    "en",
    "sv",
    "no",
    "fr",
    "de",
    "es",
    "ja",
    "ko"
],
...

Then you need to add a locale to your siteProperties.

...
"values": {
    "default": {
      "siteProperties": {
        ...
        "websiteName": "The Gazette",
        "locale": "en",
        ...
      }
    }
}
...

At the root of your repo you would have a intl.json file such as:

{
  "results-list-block.see-more":{
    "en":"See More",
    "es": "Ver más"
  }
}

Then in your feature, you reference this translation by calling the method getTranslatedPhrases with your locale’s key and the sentence’s key within phrases.t():

import getTranslatedPhrases from 'fusion:intl';
...
MyTranslatedFeature = (props) => {
  const phrases = getTranslatedPhrases(getProperties(props.arcSite).locale || 'en');
  return phrases.t('results-list-block.see-more-button');
}
...

For only Themes blocks: If you would like to override translations at the root of your repo for a specific feature, you can add a intl.json within your feature’s directory.

{
  "results-list-block.see-more": {
    "en": "See More Stories",
    "es": "Ver más historias",
  }
}

Additionally, you can leverage Polyglot’s template format to display dynamic values within a translation because some languages have these variables at different places within a sentence.

{
  "results-list-block.see-more": {
    "en": "See %{number_of_stories} More Stories",
    "es": "Ver %{number_of_stories} historias más ",
  }
}

For only Themes blocks: You can set the locale, textDirection, textFlow, and dateLocalization properties in your blocks.json as a default for all sites, or at the individual site level. For example, if you want to set an individual site to handle right-to-left (rtl) text direction, along with the other localize properties, you can do so in the accepted formats.  

    {
      "websitename": {
        "siteProperties": {
          "locale": "ar",
          "dateLocalization": {
            "language": "ar_EG",
            "timeZone": "Egypt",
            "dateTimeFormat": "%B %d, %Y at %l:%M%p %Z",
            "dateFormat": "%B %d, %Y"
          },
          "textDirection": "rtl"
        }
      }
    }

Adding custom fonts in Themes

For details on setting a specific font that is compatible with your site’s language, see Themes 2.0 - Developer FAQ - Add a custom font.

Alternatives

If you do not want to set a language per site in your blocks.json, alternatively you could use the requestUri prop from context to decide based on the path. For example, for /china/… it would use cn

External Resources