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. Use locale IDs to target specific locales when creating, updating, and retrieving 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.

{
  "locales": {
    "primary": {
      "id": "653fd9af6a07fc9cfd7a5e57",
      "cmsLocaleId": "653ad57de882f528b32e810e",
      "enabled": false,
      "displayName": "English (United States)",
      "displayImageId": null,
      "redirect": true,
      "subdirectory": "",
      "tag": "en-US"
    },
    "secondary": [
      {
        "id": "653fd9af6a07fc9cfd7a5e56",
        "cmsLocaleId": "653fd9af6a07fc9cfd7a5e5d",
        "enabled": true,
        "displayName": "French (France)",
        "displayImageId": null,
        "subdirectory": "fr-fr",
        "tag": "fr-FR"
      },
      {
        "id": "654112a3a525b2739d97664c",
        "cmsLocaleId": "654112a3a525b2739d97664f",
        "enabled": true,
        "displayName": "Spanish (Mexico)",
        "displayImageId": null,
        "subdirectory": "es-mx",
        "tag": "es-MX"
      }
    ]
  }
}

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 one entry in items. Set allCmsLocales: true on that entry and provide the primary locale’s content in fieldData. The API creates a variant in every current site locale, including the primary locale. The variants share an item ID and the same initial content.

   To target selected locales, use cmsLocaleIds instead. Omit both selectors to create the item in the primary locale only.

   This example shows a site with two locales. The two variants count as two items toward the 100-item request limit.

   createItemRequest.tscreateItemResponse.json

   const response = await fetch(
     "https://api.webflow.com/v2/collections/COLLECTION_ID/items/insert",
     {
       method: "POST",
       headers: {
         Authorization: "Bearer YOUR_ACCESS_TOKEN",
         "Content-Type": "application/json",
       },
       body: JSON.stringify({
         items: [
           {
             allCmsLocales: true,
             fieldData: {
               name: "The Hitchhiker's Guide to the Galaxy",
               slug: "the-hitchhikers-guide-to-the-galaxy",
               description: "Don't Panic!",
             },
           },
         ],
       }),
     }
   );
   const newItemVariants = await response.json();
   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

   import { WebflowClient } from "webflow-api";
   const webflow = new WebflowClient({
     accessToken: "YOUR_ACCESS_TOKEN",
   });
   const updateItems = await webflow.collections.items.updateItems(
     "COLLECTION_ID",
     {
       items: [
         {
           id: "ITEM_ID",
           cmsLocaleId: "CMS_LOCALE_ID-FRENCH",
           fieldData: {
             name: "Le Guide du voyageur galactique",
             slug: "le-guide-du-voyageur-galactique",
             description: "Pas de panique !",
           },
         },
         {
           id: "ITEM_ID",
           cmsLocaleId: "CMS_LOCALE_ID-SPANISH",
           fieldData: {
             name: "Guía del autoestopista galáctico",
             slug: "guia-del-autoestopista-galactico",
             description: "¡Que no cunda el pánico!",
           },
         },
       ],
     }
   );
   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.

To read several locales at once, pass a comma separated list of CMS locale IDs. To get every variant of one item, combine that with filter[id][eq] and the item’s ID.

GET /v2/collections/{collection_id}/items
  ?cmsLocaleId=CMS_LOCALE_ID_1,CMS_LOCALE_ID_2
  &filter[id][eq]=ITEM_ID

Get Item returns a single item, so it accepts one locale. Use List Items for the multi-locale read.

import { WebflowClient } from "webflow-api";
const webflow = new WebflowClient({
  accessToken: "YOUR_ACCESS_TOKEN",
});
const localizedItems = await webflow.collections.items.listItems("COLLECTION_ID", {
  cmsLocaleId: "CMS_LOCALE_ID,CMS_LOCALE_ID_2" // To pass multiple locales, separate the IDs with a comma within a single string
});
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.