Localization with the CMS API

Webflow localization provides an end-to-end solution for adapting your site for a global audience. The API gives you programmatic control over localizing both dynamic CMS Content and Static Page Content.

• CMS content localization enables you to create variants of a single CMS item for each locale.
• Static content localization uses the Pages API to update DOM elements and localize SEO metadata. Learn more about localizing pages →.

This guide covers the core concepts of CMS localization.

Key concepts

Understanding a few key concepts is essential for working with localization via the API. At its core, a single CMS item becomes a group of item variants when you add locales.

Item ID

When you create an item in multiple locales, all variants are linked by a shared itemId, which represents the entire item group.

CMS Locale ID

The cmsLocaleId is a unique locale identifier when working with CMS resources. Always include it when creating, updating, and retrieving localized CMS items.

Getting locale identifiers

To get the localeId and cmsLocaleId for your site’s configured locales, use the Get Site endpoint. The response will include a locales object containing the primary locale and any secondary locales. Before using these endpoints, you must first enable localization in the Site settings within the Designer.

1
{
2
  "locales": {
3
    "primary": {
4
      "id": "653fd9af6a07fc9cfd7a5e57",
5
      "cmsLocaleId": "653ad57de882f528b32e810e",
6
      "enabled": false,
7
      "displayName": "English (United States)",
8
      "displayImageId": null,
9
      "redirect": true,
10
      "subdirectory": "",
11
      "tag": "en-US"
12
    },
13
    "secondary": [
14
      {
15
        "id": "653fd9af6a07fc9cfd7a5e56",
16
        "cmsLocaleId": "653fd9af6a07fc9cfd7a5e5d",
17
        "enabled": true,
18
        "displayName": "French (France)",
19
        "displayImageId": null,
20
        "subdirectory": "fr-fr",
21
        "tag": "fr-FR"
22
      },
23
      {
24
        "id": "654112a3a525b2739d97664c",
25
        "cmsLocaleId": "654112a3a525b2739d97664f",
26
        "enabled": true,
27
        "displayName": "Spanish (Mexico)",
28
        "displayImageId": null,
29
        "subdirectory": "es-mx",
30
        "tag": "es-MX"
31
      }
32
    ]
33
  }
34
}

Managing localized content

You can create and update localized CMS items via the API, as well as independently publish items in each locale.

Creating localized items

Creating a new localized item is a two-step process:

1. Create items across all locales

   Call the Create Items endpoint with an array of cmsLocaleIds for every locale you want to target. Provide a single fieldData object containing the content for the primary locale. The API creates a unique item variant for each specified locale, all linked by a shared itemId and populated with the initial content.

   createItemRequest.tscreateItemResponse.json

   1
   import { WebflowClient } from "webflow-api";
   2
   3
   const webflow = new WebflowClient({
   4
     accessToken: "YOUR_ACCESS_TOKEN",
   5
   });
   6
   7
   const newItemVariants = await webflow.collections.items.createItems("COLLECTION_ID", {
   8
       cmsLocaleIds: ["CMS_LOCALE_ID_1", "CMS_LOCALE_ID_2"],
   9
       fieldData: {
   10
           name: "The Hitchhiker's Guide to the Galaxy",
   11
           slug: "the-hitchhikers-guide-to-the-galaxy",
   12
           description: "Don't Panic!",
   13
       },
   14
   })
   15
   16
   console.log(newItemVariants);

2. Update each variant with translated content

   After creating the locale-specific variants, make a request to the Update Item endpoint. In the request, pass the shared itemId, the specific cmsLocaleId for the variants you are updating, and its unique, translated fieldData.

   updateItemRequest.tsupdateItemResponse.json

   1
   import { WebflowClient } from "webflow-api";
   2
   3
   const webflow = new WebflowClient({
   4
     accessToken: "YOUR_ACCESS_TOKEN",
   5
   });
   6
   7
   const updateItems = await webflow.collections.items.updateItems(
   8
     "COLLECTION_ID",
   9
     {
   10
       items: [
   11
         {
   12
           id: "ITEM_ID",
   13
           cmsLocaleId: "CMS_LOCALE_ID-FRENCH",
   14
           fieldData: {
   15
             name: "Le Guide du voyageur galactique",
   16
             slug: "le-guide-du-voyageur-galactique",
   17
             description: "Pas de panique !",
   18
           },
   19
         },
   20
         {
   21
           id: "ITEM_ID",
   22
           cmsLocaleId: "CMS_LOCALE_ID-SPANISH",
   23
           fieldData: {
   24
             name: "Guía del autoestopista galáctico",
   25
             slug: "guia-del-autoestopista-galactico",
   26
             description: "¡Que no cunda el pánico!",
   27
           },
   28
         },
   29
       ],
   30
     }
   31
   );
   32
   33
   console.log(updateItems);

Retrieving localized items

To get localized items, use the List Items endpoint and pass the desired cmsLocaleId as a query parameter. If you omit the cmsLocaleId, the API will return items from the primary locale.

1
import { WebflowClient } from "webflow-api";
2
3
const webflow = new WebflowClient({
4
  accessToken: "YOUR_ACCESS_TOKEN",
5
});
6
7
const localizedItems = await webflow.collections.items.listItems("COLLECTION_ID", {
8
  cmsLocaleId: "CMS_LOCALE_ID,CMS_LOCALE_ID_2" // To pass multiple locales, separate the IDs with a comma within a single string
9
});
10
11
console.log(localizedItems);

Locale-specific publishing

Each locale maintains its own independent publishing state. This means you can have a version of an item live in your primary locale while the version for a secondary locale is still in a draft state. Publishing changes in one locale doesn’t affect the status of that item in any other locale. See the publishing guide for more details →.

Next steps

To ensure your site is completely localized, follow the guides for localizing pages and components.