> This page is for Data API, version v2 (default).
> For other versions, use one of these documentation indexes:
> - v2 (default): https://developers.webflow.com/data/v2.0.0/llms.txt
> - v2 Beta: https://developers.webflow.com/data/v2.0.0-beta/llms.txt
> - v1: https://developers.webflow.com/data/v1.0.0/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.webflow.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.webflow.com/_mcp/server.

# 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.

#### 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](/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/reference/cms/collection-items/staged-items/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.

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

   ```

   ```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!"
         }
       }
     ]
   }
   ```

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`.

   ```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!"
         }
       }
     ]
   }

   ```

> **Adding locales to an existing item**
>
> To add a secondary locale to an item that **already exists**, call [`Create Items`](/data/reference/cms/collection-items/staged-items/create-items) with the item's `id` and the new locale in `cmsLocaleIds`. The new variant shares the existing item's ID. To give the variant translated content in the same request, put it in that entry's `fieldData`.
>
> `allCmsLocales` applies only to new items and can't accompany `id` or `cmsLocaleIds`. See [Creating collection items](/data/docs/working-with-the-cms/create-items#create-a-new-item-in-all-locales) for the selector rules and an example.

### 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.

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](/data/reference/cms/collection-items/staged-items/get-item) returns a single item, so it accepts one locale. Use List Items for the multi-locale read.

```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.

#### [Localize pages](/data/docs/working-with-localization/localize-pages)

Learn how to localize a site with the Pages and CMS APIs.

#### [Localize components](/data/docs/working-with-localization/localize-components)

Review the CMS API endpoints for localization operations.