Creating Content and Pages in Other Locales

This guide explains how to use the Management API to create content items and pages in multiple locales, including how to create locale variants that are linked to existing items in another language.

Key Concepts

When saving a content item or page, the API uses the combination of the item ID and the locale (from the API route) to determine whether to create a new item, update an existing item, or create a locale variant.

• -1 = create a new item
• > 0 (existing ID) = update an existing item, or create a locale variant if the item doesn't exist in that locale yet

Creating New Content Items

To create a brand new content item with no locale linking, set contentID to -1:

POST /api/v1/instance/{guid}/{locale}/item

{
  "contentID": -1,
  "properties": {
    "referenceName": "blog-posts",
    "definitionName": "BlogPost",
    "state": 1,
    "itemOrder": 0
  },
  "fields": {
    "title": "My First Post",
    "body": "Hello world"
  }
}

Creating Content Items in Another Locale (Locale Variants)

To create a locale variant of an existing content item, use the original contentID from the source locale. The API automatically detects that the item exists in another locale and creates the linked variant.

For example, if you have a content item with contentID: 456 in en-us and want to create the French version:

POST /api/v1/instance/{guid}/fr-ca/item

{
  "contentID": 456,
  "properties": {
    "referenceName": "blog-posts",
    "definitionName": "BlogPost",
    "state": 1
  },
  "fields": {
    "title": "Mon premier article",
    "body": "Bonjour le monde"
  }
}

The API sees that contentID: 456 exists in en-us but not in fr-ca, and creates the fr-ca locale variant linked to the original.

No additional query parameters are needed for content items. The contentID alone drives locale linking.

Typical Workflow

1. Fetch the content item from the source locale
2. Modify the field values (e.g. translate them)
3. Save to the target locale with the same contentID

// Fetch from source locale
const contentItem = await apiClient.contentMethods.getContentItem(
  contentId, guid, "en-us")

// Translate fields…
contentItem.fields.title = translatedTitle
contentItem.fields.body = translatedBody

// Save to target locale — keep the original contentID
await apiClient.contentMethods.saveContentItem(contentItem, guid, "fr-ca")

// Fetch from source locale
var contentItem = await client.contentMethods.GetContentItem(
    contentId, guid, "en-us");

// Translate fields…
contentItem.fields["title"] = translatedTitle;
contentItem.fields["body"] = translatedBody;

// Save to target locale — keep the original contentID
await client.contentMethods.SaveContentItem(
    contentItem, guid, "fr-ca");

Creating New Pages

To create a brand new page with no locale linking, set pageID to -1:

POST /api/v1/instance/{guid}/{locale}/page?parentPageID={parentId}

{
  "pageID": -1,
  "name": "About Us",
  "title": "About Us",
  "menuText": "About Us",
  "channelID": 1,
  "zones": {}
}

Creating Pages in Another Locale (Locale Variants)

Pages work differently from content items. To create a locale variant of a page, you need to:

1. Set pageID to -1 (new page)
2. Pass the original page ID via the pageIDInOtherLocale query parameter
3. Pass the source locale via the otherLocale query parameter

POST /api/v1/instance/{guid}/fr-ca/page?pageIDInOtherLocale=789&otherLocale=en-us

{
  "pageID": -1,
  "name": "a-propos",
  "title": "A propos de nous",
  "menuText": "A propos",
  "channelID": 1,
  "zones": {}
}

The API fetches the page structure from the source locale and creates the linked variant in the target locale.

Typical Workflow

1. Fetch the page from the source locale
2. Modify translatable properties (title, menuText, SEO fields)
3. Set pageID to -1
4. Save to the target locale with pageIDInOtherLocale and otherLocale query parameters

// Fetch from source locale
const page = await apiClient.pageMethods.getPage(pageId, guid, "en-us")
const originalPageId = page.pageID

// Translate properties…
page.title = translatedTitle
page.menuText = translatedMenuText

// Set pageID to -1 for a new page in the target locale
page.pageID = -1

// Save to target locale with locale-linking params
await apiClient.pageMethods.savePage(page, guid, "fr-ca", originalPageId, "en-us")

// Fetch from source locale
var page = await client.pageMethods.GetPage(
    pageId, guid, "en-us");

int originalPageId = page.pageID.Value;

// Translate properties…
page.title = translatedTitle;
page.menuText = translatedMenuText;

// Set pageID to -1 for a new page in the target locale
page.pageID = -1;

// Save to target locale with locale-linking params
await client.pageMethods.SavePage(
    page, guid, "fr-ca",
    pageIDInOtherLocale: originalPageId,
    otherLocale: "en-us");

Summary

Why the difference?

Content items and pages use different mechanisms for locale linking:

• Content items — The batch processor automatically checks if the given contentID exists in another locale. If it does, the locale variant is created. No extra parameters needed.
• Pages — The page ID alone isn't enough to establish the link. The pageIDInOtherLocale and otherLocale query parameters explicitly tell the API which page in which locale to link to.