Dynamic Content supports two methods of localizing your content: field level and content item localization. The information on this page applies to field level localization. You can find an introduction to both localization methods on the localization overview page.
In order to be able to create and deliver content in multiple languages using field level localization, you will need to create content types that contain one or more localizable properties. String properties, arrays and chooser types: images, video and linked content, can be localized. You can also localize inline content.
On this page we'll explain how to define localizable properties, how to retrieve content for one or more locales using the Content Delivery API, and how to visualize localized content.
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. See Locales for more details.
Creating a content type to support localizable properties
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.
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.
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 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.
Arrays can be used to contain links to external or inline content, or to contain a list of primitive types such as strings. The example below shows a tagList property, a localized array of strings that allows users to enter up to 4 tags for each locale.
"tagList":{ "allOf":[ { "$ref":"http://bigcontent.io/cms/schema/v1/core#/definitions/localized-value" } ], "properties":{ "values":{ "items":{ "properties":{ "value":{ "type":"array", "maxItems": 4, "items":{ "description":"A tag for this item", "type":"string", "title":"Tag" } } } } } } }
An example of how a localized array of strings is shown on the content editing form, is shown below.
Inline content can also be localized, as shown in the example of a roundel property below. The user can choose a roundel for each locale and this will be stored within the content item.
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 } } }
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.
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.
You can use the Content 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 cdn.amplience.net with a virtual staging environment. See the Content Delivery API overview page for more details.
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.
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 form. 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:
Here's the Visualization URI that's shown in the example:
If you include the {{locales}} token in your visualization URI, then when you show a visualization for content of this type in the content form, a locales menu is displayed, allowing the user to choose the locale to use to display the visualization.
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.
Here's an example of building the query to send to the Content Delivery API from the localized banner visualization.
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.
If you are developing a realtime visualization using the visualization SDK then you don't need to write any additional code to retrieve content for the selected locale.
Click to download the realtime visualization for the localized banner shown on this page.
To use this visualization for the localized banner use https://amp-product.s3.eu-west-1.amazonaws.com/doc-examples/visualization/realtimelocalizedbannerviz.html as the visualization URL.
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.
