# Localization with the CMS API

> A guide to the concepts behind managing multi-locale content 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](/data/reference/pages-and-components/pages/list) to update DOM elements and localize SEO metadata. Learn more about [localizing pages →](/data/docs/working-with-localization/localize-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.

<CardGroup cols={2}>
  <Card
    title="Item ID"
    iconSize="12"
    iconPosition="left"
    icon={
            <>
                <img src="https://dhygzobemt712.cloudfront.net/Icons/Dark/64px/Localization.svg" alt="" className="hidden dark:block" />
                <img src="https://dhygzobemt712.cloudfront.net/Icons/Light/64px/Localization.svg" alt="" className="block dark:hidden" />
            </>
        }
  >
    When you create an item in multiple locales, all variants are linked by a shared `itemId`, which represents the entire item group.
  </Card>

  <Card
    title="CMS Locale ID"
    iconSize="12"
    iconPosition="left"
    icon={
            <>
                <img src="https://dhygzobemt712.cloudfront.net/Icons/Dark/64px/CMS.svg" alt="" className="hidden dark:block" />
                <img src="https://dhygzobemt712.cloudfront.net/Icons/Light/64px/CMS.svg" alt="" className="block dark:hidden" />
            </>
        }
  >
    The `cmsLocaleId` is a unique locale identifier when working with CMS resources. Always include it when creating, updating, and retrieving localized CMS items.
  </Card>
</CardGroup>

### Getting locale identifiers

To get the `localeId` and `cmsLocaleId` for your site's configured locales, use the [Get Site](/data/reference/sites/get) 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.

```json title={"response.json"}
{
  "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`](/data/v2.0.0/reference/cms/collection-items/staged-items/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.

   <CodeBlocks>
     ```ts title={"createItemRequest.ts"}
     import { WebflowClient } from "webflow-api";

     const webflow = new WebflowClient({
       accessToken: "YOUR_ACCESS_TOKEN",
     });

     const newItemVariants = await webflow.collections.items.createItems("COLLECTION_ID", {
         cmsLocaleIds: ["CMS_LOCALE_ID_1", "CMS_LOCALE_ID_2"],
         fieldData: {
             name: "The Hitchhiker's Guide to the Galaxy",
             slug: "the-hitchhikers-guide-to-the-galaxy",
             description: "Don't Panic!",
         },
     })

     console.log(newItemVariants);
     ```

     ```json title={"createItemResponse.json"}
     {
       "items": [
         {
           "id": "68d57edec48f9c414ae8f6cb",
           "cmsLocaleId": "664b1450fbd3987b1a4e1742",
           "lastPublished": null,
           "lastUpdated": "2025-09-25T17:41:50.163Z",
           "createdOn": "2025-09-25T17:41:50.163Z",
           "isArchived": false,
           "isDraft": true,
           "fieldData": {
             "name": "The Hitchhiker's Guide to the Galaxy",
             "slug": "the-hitchhikers-guide-to-the-galaxy",
             "description": "Don't Panic!"
           }
         },
         {
           "id": "68d57edec48f9c414ae8f6cb",
           "cmsLocaleId": "664b1450fbd3987b1a4e1740",
           "lastPublished": null,
           "lastUpdated": "2025-09-25T17:41:50.163Z",
           "createdOn": "2025-09-25T17:41:50.163Z",
           "isArchived": false,
           "isDraft": true,
           "fieldData": {
             "name": "The Hitchhiker's Guide to the Galaxy",
             "slug": "the-hitchhikers-guide-to-the-galaxy",
             "description": "Don't Panic!"
           }
         }
       ]
     }
     ```
   </CodeBlocks>

2. **Update each variant with translated content**

   After creating the locale-specific variants, make a request to the [`Update Item`](/data/v2.0.0/reference/cms/collection-items/staged-items/update-item) endpoint. In the request, pass the shared `itemId`, the specific `cmsLocaleId` for the variants you are updating, and its unique, translated `fieldData`.

   <CodeBlocks>
     ```ts title={"updateItemRequest.ts"}
     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);

     ```

     ```json title={"updateItemResponse.json"}
     {
       "items": [
         {
           "id": "68d580ac538e52f83d40d7f0",
           "cmsLocaleId": "664b1450fbd3987b1a4e1742",
           "lastPublished": null,
           "lastUpdated": "2025-09-25T17:52:39.226Z",
           "createdOn": "2025-09-25T17:49:32.860Z",
           "isArchived": false,
           "isDraft": true,
           "fieldData": {
             "name": "Le Guide du voyageur galactique",
             "slug": "le-guide-du-voyageur-galactique",
             "description": "Pas de panique !"
           }
         },
         {
           "id": "68d580ac538e52f83d40d7f0",
           "cmsLocaleId": "664b1450fbd3987b1a4e1740",
           "lastPublished": null,
           "lastUpdated": "2025-09-25T17:52:39.225Z",
           "createdOn": "2025-09-25T17:49:32.860Z",
           "isArchived": false,
           "isDraft": true,
           "fieldData": {
             "name": "Guía del autoestopista galáctico",
             "slug": "guia-del-autoestopista-galactico",
             "description": "¡Que no cunda el pánico!"
           }
         }
       ]
     }

     ```
   </CodeBlocks>

<Warning title="Adding secondary locales to existing items is not supported via the API">
  For any Collection items that **already exist**, you must add the desired secondary locales in the CMS panel within the Designer. **You can't add a new locale to an existing item via the API.**
</Warning>

### Retrieving localized items

To get localized items, use the [List Items](/data/reference/cms/collection-items/staged-items/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.

```ts title={"getLocalizedItems.ts"}
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 →](/data/docs/working-with-the-cms/publishing).

## Next steps

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

<CardGroup cols={2}>
  <Card title="Localize pages" href="/data/docs/working-with-localization/localize-pages" iconPosition="left" iconSize="12">
    Learn how to localize a site with the Pages and CMS APIs.
  </Card>

  <Card title="Localize components" href="/data/docs/working-with-localization/localize-components" iconPosition="left" iconSize="12">
    Review the CMS API endpoints for localization operations.
  </Card>
</CardGroup>