Skip to main content

Multi-language and multi-country sites

Multi-language sites​

The Discovery CMS provides the possibility of supporting multilingual fields, in order to be able to feed multilingual frontend. First of all, you need to select for your Property the languages ​​you want to make available, by choosing all the languages ​​you want to feed in the Languages field. Once this is done, it is possible to create, or modify if existing, the desired Component or Content by selecting the Multilanguage checkbox present in the type definition modal. Finally, you need to publish the type you just changed.

Once the Property and the Components/Contents have been prepared, it is possible to set the field values ​​for the various languages. In the page editor, where you can easily identify the fields that support the functionality thanks to the language located next to the field label, just enter the value for the language shown at that moment and save. To change language, simply choose another option from the select in the column header.

multilanguage example

For multilingual attributes, the format of the object returned by the API changes. If we consider the example shown above, for a non-multilingual field the payload will be the following:

{
    "components":[
        {
            "headline":"This is My Title",
            "_type":"Discovery\/Component",
            "_id":"f64e568b-9d9a-42c4-9ef8-b4ba107b8686"
        }
    ],
    "details":{
        "title":"HomePage",
        "slug":"home"
    },
    "_id":"84b676dc-31b0-4a4c-a3e1-d64b1a5bb0c2"
}

However, if the Component component's headline field is configured as multilingual, the payload will become the following:

{
    "components":[
        {
            "_type":"Discovery\/Component",
            "_id":"f64e568b-9d9a-42c4-9ef8-b4ba107b8686",
            "translations": {
                "en_US": {
                    "headline": "This is My Title"
                },
                "it_IT": {
                    "headline": "This is my title"
                }
            }
        }
    ],
    "details":{
        "title":"HomePage",
        "slug":"home"
    },
    "_id":"84b676dc-31b0-4a4c-a3e1-d64b1a5bb0c2"
}

It is a good idea to decide what the master language of the project is, in order to offer a fallback to the master language, generally English, in case it is missing of a translation.

Title Field​

The title field is special and cannot be made multilingual. If, for example for a Content, a multilingual title is required, it is possible to add a headline (or externalTitle or equivalent) field of the multilingual String type and it is possible to proceed in one of the following ways:

  1. The internal title (the one that appears in the CMS backend) will always be inserted in the title and the external one visible on the frontend in the headline.
  2. The title in the master language (e.g. English) will always be included in the title and any translations into other languages ​​will be included in the headline.

In case 1, the frontend should always fall back to headline in the master language. In case 2, the frontend should always fall back to headline in the master language and, if empty, to the title.

It is recommended to set headline as Required for publishing in the field configuration popup.

Multi-country websites​

While in the previous section we explained how to translate texts based on the language, in this section we explain how to configure a multi-country site in order to guarantee a level of customization by geographical area.

IMPORTANT: In this context, the term country is used as a more generic term to indicate a geographic area. If the site is not specific by country, but has another type of division (e.g. Europe, North America, Asia), simply replace country with the geographical area of ​​reference: the concepts are exactly the same.

Here are some examples:

  • you want to customize an image or video based on the country
  • you want to add a section on the home page only for a specific country
  • you want to differentiate a certain section based on the country
  • you want to create completely different pages based on the country

This manual does not go into how the frontend determines the reference country. It could be a user choice, it could be linked to the user's IP, etc.

In the following sections we will assume that a Countries taxonomy has been configured with the list of countries (or geographical areas) on which you want to allow customization. Furthermore, we assume that there is a 'master' reference country to be used as a fallback if customization for the user's specific country is missing.

Customize an image or video based on country​

Let's imagine we want to personalize a certain image, for example with people of different ethnic groups depending on the country where it is delivered, in a CallToAction component. What has been explained for the image applies exactly the same way for video, audio or any other type of digital asset.

Let's define an ImageOverride component that contains the image to use for override. The component will have the following fields:

  • country di tipo Taxonomy[Countries], single value;
  • image di tipo Media[Image], single value;

In the CallToAction component we will add the following fields:

  • cover: of type Media[Image], which will contain the fallback image;
  • cover_overrides: di tipo Reference[ImageOverride], multivalue.

Once we are going to configure the CallToAction in the CMS, in cover we are going to insert the fallback image, i.e. the one to be used if the override image for the specific country is missing. Now let's imagine that we want to provide a different image for the United States. We will add a reference in cover_overrides specifying:

  • country = "United States"
  • image = (image you want to use only in the United States)

When the frontend retrieves a page containing the component configured as above, it will search among the cover_overrides for one that coincides with the current country. If it finds it, it will use the relevant image, otherwise it will use the fallback one (cover). It is up to those who develop the frontend to implement this logic, possibly including it in an ad hoc ImageWithOverride component, so as to be able to insert it into dynamically configured pages.

Customize a section of a page​

This case is very similar to the previous example, except that it applies to the entire component rather than to the single image. Let's imagine that the CallToAction component can be deactivated for some countries and completely customized (texts, images, etc.) for other countries. We will define a CallToActionOverride component with the following fields:

  • country di tipo Taxonomy[Countries], single value;
  • disabled di tipo Boolean;
  • override di tipo Reference[CallToAction], single value;

In the page I add a CallToAction component with the fallback configuration, i.e. the one to use if the specific version of country is not found. Let's imagine we want to deactivate this call to action for Germany. In the page we will insert a CallToActionOverride component with the following configuration:

  • country = "Germania";
  • disabled = true;
  • override = (empty)

Let's also imagine that we wanted to configure a completely different call to action for the United States. In the page we will insert a CallToActionOverride component with the following configuration:

  • country = "United States";
  • disabled = false;
  • override = (custom CallToAction component for US);

Whoever implements the frontend logic, when he has to display the call to action, will first look for a specific version for the current country. If he finds it:

  • if it is disabled, it displays nothing for the current country;
  • if not disabled, display the call to action in override;

If it doesn't find it, display the CallToAction with the fallback configuration.

It is up to those who develop the frontend to implement this logic, possibly including it in an ad hoc CallToActionWithOverride component, so that it can also be inserted into dynamically configured pages.

Customize pages by country​

Let's imagine we want to completely customize a page for the country Italy, while the rest of the world will see a standard page. In this case we will define two pages:

  • Fallback page, with slug = /home, to be used for all countries if a specific page does not exist;
  • Specific page for the country, with slug = /home-it, to be used for the Italy country only;

When the page is fetched, the fallback option must be passed, as in this example:

const page = useDiscoveryPage('home-it', {
fallback: 'home'
})`

This way the API will return the home-it page if it exists, otherwise home.

NOTE: The fallback option will be released in the next version of the Javascript Connector.