Create localizations

With content item localization you start with a content item created for one locale and create localized variants for whatever locales you choose to support. A separate copy of the entire content item, with its own unique content ID and revision history, will be created for each locale you localize it to.

You can localize a content item from the Content Library or content form as explained on the content item localization page, or by using the Dynamic Content Management API. On this page we'll explain how to use the API to localize a content item for use in your backend applications such as webhook integrations and automations.

Note that you must include an access token in the authorization header of the request, as explained on the using the Dynamic Content Management API page.

Create localizations request

POST content/content-items/{content-item-id}/localize

Replace {content-item-id} with the id of the item to be localized.

Example request URL:

The following request creates variants of the content item id b42893f6-42b9-4a0c-b4bc-c46d0d087485 for each of the locales specified in the request body.

https://api.amplience.net/v2/content/content-items/b42893f6-42b9-4a0c-b4bc-c46d0d087485/localize

Request body

The item body must contain the content item version and the locales to which you want the item to be localized. version should be the latest version of the content item. You can find the latest version from the content item properties pane in the content form.

Example request body:

The following request specifies that version 1 of the content item is localized into the fr-FR and de-DE locales.

{
  "version": 1,
  "locales": [ "fr-FR", "de-DE" ]
}

You can also list the existing localizations of a content item so you can determine the variants that have already been created.

Response

The response will contain the content item from which the variants were created. If the request is successful, an asynchronous localization job will be started which will create the requested content items for each of the specified locales.

You can only create one variant of a content item for each locale. If you attempt to create more than one variant for each locale, you will still receive a 202 accepted response, but the variant will not be created.

Status codes

Status code Description
202 Accepted
400 Bad Request
403 Forbidden. Authorization required

Example response

An example response is shown below.

  "status": "IN_PROGRESS",
  "rootContentItem": {
    "label": "Winter banner",
    "locale": "en-US",
    "id": "b42893f6-42b9-4a0c-b4bc-c46d0d087485"
  },
  "requestedLocales": [
    "fr-FR",
    "de-DE"
  ],
  "createdBy": "e86a8e69-2c70-4a96-a112-1df4acca5ea7",
  "createdDate": "2021-11-15T15:16:41.708Z",
  "_links": {
    "content-root": {
      "href": "https://api.amplience.net/v2/content/content-items/b42893f6-42b9-4a0c-b4bc-c46d0d087485"
    },
    "findByRootContentItem": {
      "href": "https://api.amplience.net/v2/content/localization-jobs/search/findByRootContentItem?id=b42893f6-42b9-4a0c-b4bc-c46d0d087485{&page,size,sort}",
      "templated": true
    }
  }
}

Usage notes

The localize operation will create variants of the given content item and its descendants with the specified locales. If the request is successful, a localization job will be started which will create the necessary content items asynchronously.

Localized content will be created either in the same repository, or in a repository in the same localization group to which the corresponding target locale has been assigned.

You can also localized content that links to other content items, such as carousels and grids. The rules for creating variants of linked content are described in detail on the localizing linked content page.

In order for the localize request to be successful, the following conditions must be met:

  1. The source content item must have a locale.
  2. The target locales must be supported by the hub.
  3. A variant of the source content item must not already exist in any of the specified locales.
  4. You must specify the current version of the source content item.

Localization overview

Content item localization