Working with localized content

In order to be able to create and deliver content in multiple languages, you will need to create content types that contain one or more localizable properties. String properties and chooser types: images, video and linked content, can be localized.

On this page we'll explain how to define localizable properties and explain how to retrieve content for one or more locales using the Content Delivery API and how to visualize localized content.

Locales

When adding content with localized properties, you can enter a separate value for each of the locales that you support.

A locale is a combination of language code and country code, with the language code being mandatory and the country code optional. Locales are associated with a Dynamic Content hub. To manage locales, choose the "Locale settings" menu item as shown in the image below.

Locale management is available from the Locale settings menu item
Locale management is available from the Locale settings menu item

Creating a content type to support localizable properties

To define a property with localizable values, that property must conform to the following schema definition:

http://bigcontent.io/cms/schema/v1/core#/definitions/localized-value

This schema defines a structure for content that contains values which can be translated into multiple languages. The schema definition is shown below. The most important section is the "values" property that defines an array of locale and value properties.

 "localized-value": {
      "properties": {
        "_meta": {
          "allOf": [
            { "$ref": "#/definitions/meta" },
            {
              "properties": {
                "schema": {
                  "enum": ["http://bigcontent.io/cms/schema/v1/core#/definitions/localized-value"]
                }
              }
            }
          ]
        },
        "values": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "locale": { "type": "string" },
              "value": {}
            },
            "required": ["locale", "value"]
          }
        }
      },
      "required": [ "_meta", "values" ]
    },

Example localizable properties

Strings

Here's an example of a localizable string property, the headline property from the tutorial banner example:

"headline":{  
         "allOf":[  
            {  
               "$ref":"http://bigcontent.io/cms/schema/v1/core#/definitions/localized-value"
            }
         ],
         "properties":{  
            "values":{  
               "items":{  
                  "properties":{  
                     "value":{  
                        "title":"Headline",
                        "description":"The main title of this banner",
                        "type":"string",
                        "format":"text",
                        "minLength":5,
                        "maxLength":256
                     }
                  }
               }
            }
         }
      },

The headline property uses the localized-value schema definition and includes a nested properties definition to specify additional information for each "value", including title and minimum and maximum length and its type.

Images and video choosers

Media chooser properties are properties that contain a link to images or video that the user chooses from the media library.

An example of a localizable media property, in this case the banner's background image or video, is shown below. As with the string property shown in the previous section, the background property uses the localized-value schema definition and then adds nested properties, in this case to specify that it can be either an image or video.

  "background":{  
         "allOf":[  
            {  
               "$ref":"http://bigcontent.io/cms/schema/v1/core#/definitions/localized-value"
            },
            {  
               "properties":{  
                  "values":{  
                     "items":{  
                        "properties":{  
                           "value":{  
                              "title":"Background image or video",
                              "description":"The background media of this banner",
                              "type":"object",
                              "anyOf":[  
                                 {  
                                    "$ref":"http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
                                 },
                                 {  
                                    "$ref":"http://bigcontent.io/cms/schema/v1/core#/definitions/video-link"
                                 }
                              ]
                           }
                        }
                     }
                  }
               }
            }
         ]
      }

Content choosers

Content choosers are used to link to an externally created piece of content. The user can choose an existing piece of content of the specified type from the Content Library or create a new one. If you make a content chooser property localizable, the user can choose a different content item for each locale.

The example color property shown below allows the user to select an item of the "colorvalue" content type. This content type is a combination of a color and hex value to be used as the banner color for each locale set up on the hub.

  "color":{  
         "allOf":[  
            {  
               "$ref":"http://bigcontent.io/cms/schema/v1/core#/definitions/localized-value"
            },
            {  
               "properties":{  
                  "values":{  
                     "items":{  
                        "properties":{  
                           "value":{  
                              "title":"Color selector",
                              "description":"The color of this banner",
                              "type":"object",
                              "allOf":[  
                                 {  
                                    "$ref":"http://bigcontent.io/cms/schema/v1/core#/definitions/content-link"
                                 },
                                 {  
                                    "properties":{  
                                       "contentType":{  
                                          "enum":[  
                                             "https://s3-eu-west-1.amazonaws.com/amp-product/tutorials/dynamiccontenttutorials/colorvalue.json"
                                          ]
                                       }
                                    }
                                 }
                              ]
                           }
                        }
                     }
                  }
               }
            }
         ]
      }

Localized tutorial banner example

The tutorial banner content type, including the localizable string and image properties, is shown below. In this example headline, strapline, call to action and background are localizable properties.

{  
   "$schema":"http://bigcontent.io/cms/schema/v1/schema#",
   "id":"https://s3-eu-west-1.amazonaws.com/amp-product/tutorials/dynamiccontenttutorials/localizedbannerchoosertest.json",
   "title":"localised-link.json",
   "description":"Localized chooser test",
   "type":"object",
   "allOf":[  
      {  
         "$ref":"http://bigcontent.io/cms/schema/v1/core#/definitions/content"
      }
   ],
   "propertyOrder":[  
      "headline",
      "strapline",
      "background",
      "calltoactiontext",
      "calltoactionurl"
   ],
   "properties":{  
      "background":{  
         "allOf":[  
            {  
               "$ref":"http://bigcontent.io/cms/schema/v1/core#/definitions/localized-value"
            },
            {  
               "properties":{  
                  "values":{  
                     "items":{  
                        "properties":{  
                           "value":{  
                              "title":"Background image or video",
                              "description":"The background media of this banner",
                              "type":"object",
                              "anyOf":[  
                                 {  
                                    "$ref":"http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
                                 },
                                 {  
                                    "$ref":"http://bigcontent.io/cms/schema/v1/core#/definitions/video-link"
                                 }
                              ]
                           }
                        }
                     }
                  }
               }
            }
         ]
      },
      "color":{  
         "allOf":[  
            {  
               "$ref":"http://bigcontent.io/cms/schema/v1/core#/definitions/localized-value"
            },
            {  
               "properties":{  
                  "values":{  
                     "items":{  
                        "properties":{  
                           "value":{  
                              "title":"Color selector",
                              "description":"The color of this banner",
                              "type":"object",
                              "allOf":[  
                                 {  
                                    "$ref":"http://bigcontent.io/cms/schema/v1/core#/definitions/content-link"
                                 },
                                 {  
                                    "properties":{  
                                       "contentType":{  
                                          "enum":[  
                                             "https://s3-eu-west-1.amazonaws.com/amp-product/tutorials/dynamiccontenttutorials/colorvalue.json"
                                          ]
                                       }
                                    }
                                 }
                              ]
                           }
                        }
                     }
                  }
               }
            }
         ]
      },
      "headline":{  
         "allOf":[  
            {  
               "$ref":"http://bigcontent.io/cms/schema/v1/core#/definitions/localized-value"
            }
         ],
         "properties":{  
            "values":{  
               "items":{  
                  "properties":{  
                     "value":{  
                        "title":"Headline",
                        "description":"The main title of this banner",
                        "type":"string",
                        "format":"text",
                        "minLength":5,
                        "maxLength":256
                     }
                  }
               }
            }
         }
      },
      "strapline":{  
         "allOf":[  
            {  
               "$ref":"http://bigcontent.io/cms/schema/v1/core#/definitions/localized-value"
            }
         ],
         "properties":{  
            "values":{  
               "items":{  
                  "properties":{  
                     "value":{  
                        "title":"Strapline",
                        "description":"The subtitle for this banner",
                        "type":"string",
                        "format":"text",
                        "maxLength":256
                     }
                  }
               }
            }
         }
      },
      "calltoactiontext":{  
         "allOf":[  
            {  
               "$ref":"http://bigcontent.io/cms/schema/v1/core#/definitions/localized-value"
            }
         ],
         "properties":{  
            "values":{  
               "items":{  
                  "properties":{  
                     "value":{  
                        "title":"Call to action text",
                        "description":"The text you want displayed with the call to action",
                        "type":"string",
                        "format":"text",
                        "maxLength":256
                     }
                  }
               }
            }
         }
      },
      "calltoactionurl":{  
         "title":"Call to action URL",
         "description":"The URL for the call to action",
         "type":"string",
         "format":"uri",
         "maxLength":256
      }
   }
}

Example content

When you create a content item from the updated tutorial banner content type, there will be separate entries for the localizable properties for each locale available on the hub. In this example en-GB, de-DE and fr-FR locales are available and separate images have been chosen for each locale, together with localized text for each language.

The tutorial banner with localizable properties
The tutorial banner with localizable properties

Here is some example content created from the tutorial banner type. Notice that the localized properties each contain a "values" array containing the value that the user entered for each locale. The fields that have not been localized are retrieved as normal.

{  
   "@context":"http://context.system.cms.amplience.com/v0.0/api",
   "@type":"QueryResult",
   "result":[  
      {  
         "@id":"http://content.cms.amplience.com/7b3a88ca-895a-4c24-b711-d2eec1563b83"
      }
   ],
   "@graph":[  
      {  
         "_meta":{  
            "schema":"https://s3-eu-west-1.amazonaws.com/amp-product/tutorials/dynamiccontenttutorials/localizedbannerchoosertest.json",
            "name":"localized-hat-collection"
         },
         "calltoactiontext":{  
            "values":[  
               {  
                  "locale":"en-GB",
                  "value":"Buy now"
               },
               {  
                  "locale":"de-DE",
                  "value":"Kaufen"
               },
               {  
                  "locale":"fr-FR",
                  "value":"Acheter"
               }
            ],
            "_meta":{  
               "schema":"http://bigcontent.io/cms/schema/v1/core#/definitions/localized-value"
            }
         },
         "background":{  
            "values":[  
               {  
                  "locale":"en-GB",
                  "value":{  
                     "@id":"http://image.cms.amplience.com/34b14fb4-e590-4d37-b254-504a4c6c7de9"
                  }
               },
               {  
                  "locale":"de-DE",
                  "value":{  
                     "@id":"http://image.cms.amplience.com/50d6d113-67e1-40f0-af44-2f830959d39a"
                  }
               },
               {  
                  "locale":"fr-FR",
                  "value":{  
                     "@id":"http://image.cms.amplience.com/a76b51d3-0c80-436f-9bb5-a72c46cc5d59"
                  }
               }
            ],
            "_meta":{  
               "schema":"http://bigcontent.io/cms/schema/v1/core#/definitions/localized-value"
            }
         },
         "calltoactionurl":"http://www.amplience.com",
         "strapline":{  
            "values":[  
               {  
                  "locale":"en-GB",
                  "value":"Our new hat collection"
               },
               {  
                  "locale":"de-DE",
                  "value":"Die besten Hüte"
               },
               {  
                  "locale":"fr-FR",
                  "value":"Notre nouvelle collection de chapeaux"
               }
            ],
            "_meta":{  
               "schema":"http://bigcontent.io/cms/schema/v1/core#/definitions/localized-value"
            }
         },
         "headline":{  
            "values":[  
               {  
                  "locale":"en-GB",
                  "value":"Our new hat collection"
               },
               {  
                  "locale":"de-DE",
                  "value":"Neue Hutkollektion"
               },
               {  
                  "locale":"fr-FR",
                  "value":"Notre nouvelle collection de chapeaux"
               }
            ],
            "_meta":{  
               "schema":"http://bigcontent.io/cms/schema/v1/core#/definitions/localized-value"
            }
         },
         "@type":"https://s3-eu-west-1.amazonaws.com/amp-product/tutorials/dynamiccontenttutorials/localizedbannerchoosertest.json",
         "@id":"http://content.cms.amplience.com/7b3a88ca-895a-4c24-b711-d2eec1563b83"
      },
      {  
         "_meta":{  
            "schema":"http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
         },
         "id":"34b14fb4-e590-4d37-b254-504a4c6c7de9",
         "name":"hat-woman-english",
         "endpoint":"ampproduct",
         "defaultHost":"i1.adis.ws",
         "@id":"http://image.cms.amplience.com/34b14fb4-e590-4d37-b254-504a4c6c7de9",
         "mediaType":"image"
      },
      {  
         "_meta":{  
            "schema":"http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
         },
         "id":"50d6d113-67e1-40f0-af44-2f830959d39a",
         "name":"hat-woman-german",
         "endpoint":"ampproduct",
         "defaultHost":"i1.adis.ws",
         "@id":"http://image.cms.amplience.com/50d6d113-67e1-40f0-af44-2f830959d39a",
         "mediaType":"image"
      },
      {  
         "_meta":{  
            "schema":"http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
         },
         "id":"a76b51d3-0c80-436f-9bb5-a72c46cc5d59",
         "name":"hat-woman-french",
         "endpoint":"ampproduct",
         "defaultHost":"i1.adis.ws",
         "@id":"http://image.cms.amplience.com/a76b51d3-0c80-436f-9bb5-a72c46cc5d59",
         "mediaType":"image"
      }
   ]
}

Using the Content Delivery API with locales

You can use the Delivery API to retrieve the full localized content for all locales, as shown in the example content above, or filter it by a specific locale.

To filter the content by a specified locale, use the locale parameter. In the example below we are requesting content for the de-DE locale.

Note that the query below retrieves published content, but to request unpublished content you can replace c1.adis.ws with a virtual staging environment. See the Delivery API page for more details.

https://c1.adis.ws/cms/content/query?store=ampproduct&query={"sys.iri":"http://content.cms.amplience.com/7b3a88ca-895a-4c24-b711-d2eec1563b83"}&locale=de-DE

This is the inlined version of the returned content. Notice that the localized fields are returned for the de-DE locale. This content can then be rendered with the same code used for unlocalized content.

{  
   "@id":"http://content.cms.amplience.com/7b3a88ca-895a-4c24-b711-d2eec1563b83",
   "_meta":{  
      "schema":"https://s3-eu-west-1.amazonaws.com/amp-product/tutorials/dynamiccontenttutorials/localizedbannerchoosertest.json",
      "name":"localized-hat-collection"
   },
   "calltoactiontext":"Kaufen",
   "background":{  
      "@id":"http://image.cms.amplience.com/50d6d113-67e1-40f0-af44-2f830959d39a",
      "_meta":{  
         "schema":"http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
      },
      "id":"50d6d113-67e1-40f0-af44-2f830959d39a",
      "name":"hat-woman-german",
      "endpoint":"ampproduct",
      "defaultHost":"i1.adis.ws",
      "mediaType":"image"
   },
   "calltoactionurl":"http://www.amplience.com",
   "strapline":"Die besten Hüte",
   "headline":"Neue Hutkollektion",
   "@type":"https://s3-eu-west-1.amazonaws.com/amp-product/tutorials/dynamiccontenttutorials/localizedbannerchoosertest.json"
}

Locale filtering rules

There are a number of rules that the Delivery API uses to determine which locale to use based on the locale parameter.

  • An exact match such as locale=fr-FR will return content for the chosen locale
  • locale=* will return content for the first locale that contains a value, in the order set in locale settings on the hub
  • locale=en-* will return content for the first locale that has "en" as a language code

If the locale cannot be found then the localized values will be set to null.

Visualizing localized content

On the Visualizations page we explain the concepts behind creating a visualization for a content type. Visualizations provide a preview of content items of this type in the content editing window. To visualize localized content, you will need to update your visualizations to handle locales.

When you set up a visualization for a content type, you will specify its URI, together with a set of tokens including the content ID of the content to be visualized and the virtual staging environment (VSE) within which the visualization is displayed. For localized content you need to support an additional token: {{locales}}, as shown in the "Register content type" window below:

Developers need to add a locales token to their visualization URI to support locales
Developers need to add a locales token to their visualization URI to support locales

Here's the Visualization URI that's shown in the example:

https://s3-eu-west-1.amazonaws.com/amp-product/tutorials/dynamiccontenttutorials/tutorialbannerlocaleviz.html?api={{vse.domain}}&content={{content.sys.id}}&locale={{locales}}

If you include the token in your visualization URI, then when you show a visualization for content of this type in the content editing window, a locales menu is displayed, allowing the user to choose the locale to use to display the visualization.

Choosing the locale to use to visualize the content item
Choosing the locale to use to visualize the content item

When the user chooses a locale, this will be included in the query parameters sent to your visualization. You will need to retrieve this parameter and use it to build up a query to send to the Content Delivery API in order to retrieve the localized content.

For the updated tutorial banner example, we now retrieve the query parameters as follows:

  const encodedQuery = encodeURIComponent(JSON.stringify({'sys.iri':`http://content.cms.amplience.com/${getQueryVar('content')}`}));
  const contentDeliveryUrl = `//${getQueryVar('api')}/cms/content/query?store=store&query=${encodedQuery}&locale=${getQueryVar('locale')}`;

Here's an example query generated if the user selected the de-DE locale. This is decoded for easier reference:

//1vkz2i2i1hlau19hndnr03duvb.staging.bigcontent.io/cms/content/query?store=store&query={"sys.iri":"http://content.cms.amplience.com/e368be7e-59df-4216-8dc6-2171984cbf38"}&locale=de-DE

As shown in the Using the Delivery API with locales section above, adding the locale to the query sent to the Delivery API will return the content localized for this locale, together with any properties that have not been localized. You can then use the returned content to render the visualization.

For an example of a visualization that supports locales download the complete updated tutorial banner visualization.

Custom card support for localized content

As explained in custom cards, if you are creating your own card rather than using one of the built-in cards available when you register a content type, then you will specify the URI of the card web app using the same format as a visualization. If you include a {{locales}} token in the URI when you set up a custom card, then the default locale will be sent to the card as a parameter.

Media and content choosers

The Content Delivery API

Visualizations

Custom cards

results matching ""

    No results matching ""