Localizable content types

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

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"
                                          ]
                                       }
                                    }
                                 }
                              ]
                           }
                        }
                     }
                  }
               }
            }
         ]
      }

Arrays

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"
                        }
                     }
                  }
               }
            }
         }
      }

To see how a localized array of strings is shown on the content editing form, expand the section below.

Inline content

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.

"roundel":{  
         "allOf":[  
            {  
               "$ref":"http://bigcontent.io/cms/schema/v1/core#/definitions/localized-value"
            }
         ],
         "properties":{  
            "values":{  
               "items":{  
                  "properties":{  
                     "value":{  
                        "allOf":[  
                           {  
                              "$ref":"https://s3-eu-west-1.amazonaws.com/amp-product/tutorials/dynamiccontenttutorials/roundel.json"
                           }
                        ]
                     }
                  }
               }
            }
         }
      }

To see how the localized inline content is shown on the content editing form, expand the section below.

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

Localization overview

results matching ""

    No results matching ""