Localizing components

Components are reusable design elements that can be instanced across your site.

Workflows

Webflow enables you to localize both a component definition and component instances via the Data API.

Localize component definitions

Localize the static content of a component definition across an entire locale

Localize component instances

Localize a component instance on a specific page by modifying its properties.

Key concepts

To understand how to localize components, you’ll need to understand the key concepts of components in Webflow.

Localizable content

To completely localize your site, you’ll need to localize all three types of component content.

Some key points to remember when localizing component content:

• Property overrides only affect a specific component instance on a page
• Default properties affect all instances that don’t have overrides
• Static content affects all instances across the site
• Only content bound to component properties can be overridden at the instance or per-page level

Component definitions

Component definitions contain two types of localizable content:

Static content

Text nodes, form elements, and nested component instances

Property defaults

Default values for component properties

Localize static content

To localize static content, you’ll first need to get the content of the selected component, and then update the content in a secondary locale.

List site components

Use the List Components endpoint to get a list of all components on your site.

Request

1
curl -G https://api.webflow.com/v2/sites/<SITE_ID>/components \
2
     -H "Authorization: Bearer <token>" \
3
     -d limit=100 \
4
     -d offset=0

Response

The endpoint returns a components array with the details of each component definition on your site. The response also includes a pagination object for pagination through results over the 100 item limit.

1
{
2
  "components": [
3
    {
4
      "id": "1fa6f97b-84f7-2db3-29cb-1275161e432f",
5
      "name": "Navbar"
6
    },
7
    {
8
      "id": "9fa3a9c4-87d4-19b0-95f7-1b0b099f82a0",
9
      "name": "Footer"
10
    },
11
    {
12
      "id": "db278ae3-20d1-6657-c0c9-083a38fbc2c4",
13
      "name": "Locale dropdown"
14
    },
15
    {
16
      "id": "d2de2e85-bab1-8dbb-1648-2bbedc5417dd",
17
      "name": "Hero"
18
    },
19
    {
20
      "id": "fd06c181-43b2-e1c0-9d7f-0b332cd9905b",
21
      "name": "Card"
22
    },
23
    {
24
      "id": "33666cc8-031a-c160-37ec-654c05d48750",
25
      "name": "Job Card"
26
    },
27
    {
28
      "id": "d2154999-bbdb-8145-1152-53511d5c3f70",
29
      "name": "Button"
30
    }
31
  ],
32
  "pagination": {
33
    "limit": 100,
34
    "offset": 0,
35
    "total": 7
36
  }
37
}

Get static content from the primary locale

Retrieve existing static content from the primary locale for a specific component. Send a GET request to the get component content endpoint, and include the component id in the request path.

Request

1
curl -G https://api.webflow.com/v2/sites/<SITE_ID>/components/<COMPONENT_ID>/dom \
2
     -H "Authorization: Bearer <token>" \
3
     -d limit=100 \
4
     -d offset=0

Response

The response contains a nodes array with the component’s static content. Each node includes a type property that defines its content type.

1
{
2
  "componentId": "33666cc8-031a-c160-37ec-654c05d48750",
3
  "nodes": [
4
    {
5
      "type": "text",
6
      "id": "dca4e42f-0d46-0c2a-420f-6496321fec8b",
7
      "text": {
8
        "html": "<div class=\"text-block-2\">NEW&nbsp;OPPORTUNITY</div>",
9
        "text": "NEW OPPORTUNITY"
10
      },
11
      "attributes": {}
12
    },
13
    {
14
      "type": "component-instance",
15
      "id": "d2154999-bbdb-8145-1152-53511d5c3f73",
16
      "componentId": "d2154999-bbdb-8145-1152-53511d5c3f70",
17
      "propertyOverrides": [
18
        {
19
          "propertyId": "d9e0fd5c-e7f7-d25a-fdc4-3741ec86fc43",
20
          "type": "Plain Text",
21
          "label": "Button Text",
22
          "text": {
23
            "text": "Apply Now"
24
          }
25
        }
26
      ]
27
    }
28
  ],
29
  "pagination": {
30
    "limit": 100,
31
    "offset": 0,
32
    "total": 2
33
  }
34
}

Node types

Node properties

Node properties by type

Each node type has a unique structure for accessing component content.

For example, a text node contains a text object, which includes html and text properties. These properties provide context for strings that can be localized. See the tabs below for the specific properties for each node type.

1
{
2
  "id": "a245c12d-995b-55ee-5ec7-aa36a6cad623",
3
  "type": "text",
4
  "text": {
5
    "html": "<h1>Don't Panic!</h1>",
6
    "text": "Don't Panic!"
7
  },
8
  "attributes": {}
9
},
10
{
11
  "id": "a245c12d-995b-55ee-5ec7-aa36a6cad627",
12
  "type": "text",
13
  "text": {
14
    "html": "<span data-w-id=\"b3107...\">$9.99</span>",
15
    "text": "$9.99"
16
  },
17
  "attributes": {}
18
}

Update static content

After translating the content you received from your earlier request, update it with the update component content endpoint, passing the target localeId as a query parameter and the translated nodes in the request body.

You only need to include the nodeId and the content property for that specific node type.

Request

1
curl -X POST https://api.webflow.com/v2/sites/<SITE_ID>/components/<COMPONENT_ID>/dom?localeId=<SECONDARY_LOCALE_ID> \
2
     -H "Authorization: Bearer <token>" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
       "nodes": [
6
        {
7
          "nodeId": "dca4e42f-0d46-0c2a-420f-6496321fec8b",
8
          "text": "<div class=\"text-block-2\">NUEVA&nbsp;OPORTUNIDAD</div>"
9
        },
10
        {
11
          "nodeId": "d2154999-bbdb-8145-1152-53511d5c3f73",
12
          "propertyOverrides": [
13
            {
14
              "propertyId": "d9e0fd5c-e7f7-d25a-fdc4-3741ec86fc43",
15
              "text": "Aplicar ahora"
16
            }
17
          ]
18
        }
19
      ]
20
     }'

Response

A successful response will return an object with and error property with an empty array.

Localize default properties

Component properties are typed variables that make component content dynamic and customizable per instance. When content is bound to a property, each component instance can have different values for that property.

Component definitions can store default values for properties, which are used as fallbacks when instances don’t have property overrides. To localize the default values follow the steps below.

List site components

Use the List Components endpoint to get a list of all components on your site.

Request

1
curl -G https://api.webflow.com/v2/sites/<SITE_ID>/components \
2
     -H "Authorization: Bearer <token>" \
3
     -d limit=100 \
4
     -d offset=0

Response

The endpoint returns a components array with the details of each component definition on your site. The response also includes a pagination object for pagination through results over the 100 item limit.

1
{
2
  "components": [
3
    {
4
      "id": "1fa6f97b-84f7-2db3-29cb-1275161e432f",
5
      "name": "Navbar"
6
    },
7
    {
8
      "id": "9fa3a9c4-87d4-19b0-95f7-1b0b099f82a0",
9
      "name": "Footer"
10
    },
11
    {
12
      "id": "db278ae3-20d1-6657-c0c9-083a38fbc2c4",
13
      "name": "Locale dropdown"
14
    },
15
    {
16
      "id": "d2de2e85-bab1-8dbb-1648-2bbedc5417dd",
17
      "name": "Hero"
18
    },
19
    {
20
      "id": "fd06c181-43b2-e1c0-9d7f-0b332cd9905b",
21
      "name": "Card"
22
    },
23
    {
24
      "id": "33666cc8-031a-c160-37ec-654c05d48750",
25
      "name": "Job Card"
26
    },
27
    {
28
      "id": "d2154999-bbdb-8145-1152-53511d5c3f70",
29
      "name": "Button"
30
    }
31
  ],
32
  "pagination": {
33
    "limit": 100,
34
    "offset": 0,
35
    "total": 7
36
  }
37
}

Get component properties

Retrieve component property definitions and their default values using the Get Component Properties endpoint.

Request

1
curl -G https://api.webflow.com/v2/sites/<SITE_ID>/components/<COMPONENT_ID>/properties \
2
     -H "Authorization: Bearer <token>"

Response

The response will return an object with the componentId, properties, and pagination properties. Each property will have a type and text property, which contains the property’s default text value.

1
{
2
  "componentId": "33666cc8-031a-c160-37ec-654c05d48750",
3
  "properties": [
4
    {
5
      "propertyId": "ecce29ad-f890-3428-1e29-5232054f8932",
6
      "type": "Plain Text",
7
      "label": "Title",
8
      "text": {
9
        "text": "Job Title"
10
      }
11
    },
12
    {
13
      "propertyId": "b0e6e289-f003-51df-07c2-387775f9a267",
14
      "type": "Plain Text",
15
      "label": "Department",
16
      "text": {
17
        "text": "Department"
18
      }
19
    },
20
    {
21
      "propertyId": "a0c19de3-e501-89ae-0a69-45b95dbe1dd6",
22
      "type": "Plain Text",
23
      "label": "Description",
24
      "text": {
25
        "text": "Apply if you are an expert in delaying tasks, have perfected the art of avoiding work, and mastered the subtle skill of looking busy while accomplishing nothing."
26
      }
27
    },
28
    {
29
      "propertyId": "d0b64214-eb68-fa04-3c93-26f8be2df466",
30
      "type": "Plain Text",
31
      "label": "Location",
32
      "text": {
33
        "text": "Location"
34
      }
35
    },
36
    {
37
      "propertyId": "aaeb508c-75ad-c326-ff4d-c607620dc41a",
38
      "type": "Plain Text",
39
      "label": "Contract Type",
40
      "text": {
41
        "text": "Contract Type"
42
      }
43
    },
44
  ],
45
  "pagination": {
46
    "limit": 100,
47
    "offset": 0,
48
    "total": 5
49
  }
50
}

Property types

Component properties can be of different types:

• Plain Text - Single-line text without HTML formatting
• Rich Text - Multi-line text with HTML formatting support
• Alt Text - Alternative text for images

Update component properties

Localize component property default values using the Update Component Properties endpoint. Provide a properties array with each of the property IDs and the translated strings in the text field. You must pass the localeId of the secondary locale you want to update as a query parameter.

Request

1
curl -X POST https://api.webflow.com/v2/sites/<SITE_ID>/components/<COMPONENT_ID>/properties?localeId=<SECONDARY_LOCALE_ID> \
2
     -H "Authorization: Bearer <token>" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
       "properties": [
6
         {
7
           "propertyId": "a245c12d-995b-55ee-5ec7-aa36a6cad623",
8
           "text": "Guía del autoestopista galáctico"
9
         },
10
         {
11
           "propertyId": "a245c12d-995b-55ee-5ec7-aa36a6cad627",
12
           "text": "<div><h3>¡No entres en pánico!</h3><p>Siempre sabe dónde está tu toalla.</p></div>"
13
         }
14
       ]
15
     }'

Response

A successful response will return an object with and error property that contains an empty array.

Component instances

When you add a component to a page, you create an instance. To customize the content of an instance, you can override the default properties of that instance. Only overridden properties can be localized via the properties endpoints.

Identify component instances on pages

Component instances appear in the page content response as component-instance nodes. To get page content, use the Get Page Content endpoint.

Request

1
curl -G https://api.webflow.com/beta/pages/63c720f9347c2139b248e552/dom \
2
     -H "Authorization: Bearer <token>" \
3
     -d localeId=65427cf400e02b306eaa04a0 \
4
     -d limit=100 \
5
     -d offset=0

Response

The response will return a list of nodes. Any component-instance type nodes will have a propertyOverrides array with a list of available properties to localize. If a property hasn’t been overridden on the instance, it won’t be included in the propertyOverrides array.

Each object in the propertyOverrides array will have the following properties:

1
{
2
  "pageId": "658205daa3e8206a523b5ad4",
3
  "nodes": [
4
    {
5
      "id": "a245c12d-995b-55ee-5ec7-aa36a6cad631",
6
      "type": "component-instance",
7
      "componentId": "6258612d1ee792848f805dcf",
8
      "propertyOverrides": [
9
        {
10
          "propertyId": "a245c12d-995b-55ee-5ec7-aa36a6cad633",
11
          "type": "Plain Text",
12
          "label": "Title",
13
          "text": {
14
            "html": null,
15
            "text": "Custom Hero Title"
16
          }
17
        },
18
        {
19
          "propertyId": "a245c12d-995b-55ee-5ec7-aa36a6cad635",
20
          "type": "Rich Text",
21
          "label": "Description",
22
          "text": {
23
            "html": "<div><p>Page-specific description text</p></div>",
24
            "text": null
25
          }
26
        }
27
      ]
28
    }
29
  ]
30
}

In this example, the component instance has overridden two properties (“Title” and “Description”) with page-specific values. Any other properties defined in the component will use their default values from the component definition.

Update component instance

To localize a component instance, create a new nodes array, and include an object with the nodeId of the component instance and a propertyOverrides array. Each item in the array should have the propertyId and text of the property overrides for the secondary locale.

Request

1
curl -X POST https://api.webflow.com/v2/pages/<PAGE_ID>/dom?localeId=<SECONDARY_LOCALE_ID> \
2
     -H "Authorization: Bearer <token>" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
       "nodes": [
6
         {
7
           "nodeId": "a245c12d-995b-55ee-5ec7-aa36a6cad631",
8
           "propertyOverrides": [
9
             {
10
               "propertyId": "a245c12d-995b-55ee-5ec7-aa36a6cad633",
11
               "text": "Título personalizado del héroe"
12
             },
13
             {
14
               "propertyId": "a245c12d-995b-55ee-5ec7-aa36a6cad635",
15
               "text": "<div><p>Texto de descripción específico de la página</p></div>"
16
             }
17
           ]
18
         }
19
       ]
20
     }'

Response

A successful response will return an object with and error property with an empty array.

Complete component localization workflow

Here’s a complete example demonstrating component localization across definitions and instances:

1
const client = new WebflowClient({ accessToken: "YOUR_ACCESS_TOKEN" });
2
3
// Example `translations` object holding the localized content for the secondary locale
4
async function localizeComponentDefinition(
5
  siteId,
6
  componentId,
7
  secondaryLocaleId,
8
  translations
9
) {
10
  // 1. Get component content structure in primary locale
11
  const contentData = await client.components.getContent(siteId, componentId);
12
13
  // 2. Get component properties for a given component definition
14
  const propertiesData = await client.components.getProperties(
15
    siteId,
16
    componentId
17
  );
18
19
  // 3. Update static content in component definition
20
  if (translations.staticContent) {
21
    const staticUpdates = {
22
      nodes: contentData.nodes
23
        .filter((node) => translations.staticContent[node.id])
24
        .map((node) => {
25
          const update = { nodeId: node.id };
26
          if (node.type === "text") {
27
            update.text = translations.staticContent[node.id];
28
          } else if (node.type === "text-input") {
29
            update.placeholder = translations.staticContent[node.id];
30
          }
31
          return update;
32
        }),
33
    };
34
35
    await client.components.updateContent(siteId, componentId, {
36
      localeId: secondaryLocaleId,
37
      nodes: staticUpdates.nodes,
38
    });
39
  }
40
41
  // 4. Update component properties
42
  if (translations.properties) {
43
    const propertyUpdates = {
44
      properties: propertiesData.properties
45
        .filter((prop) => translations.properties[prop.propertyId])
46
        .map((prop) => ({
47
          propertyId: prop.propertyId,
48
          text: translations.properties[prop.propertyId],
49
        })),
50
    };
51
52
    await client.components.updateProperties(siteId, componentId, {
53
      localeId: secondaryLocaleId,
54
      properties: propertyUpdates.properties,
55
    });
56
  }
57
}
58
59
// Example `propertyTranslations` object holding the localized content for the secondary locale
60
async function localizeComponentInstance(
61
  pageId,
62
  instanceNodeId,
63
  secondaryLocaleId,
64
  propertyTranslations
65
) {
66
  // Update component instance property overrides on a specific page
67
  const instanceUpdates = {
68
    nodes: [
69
      {
70
        nodeId: instanceNodeId,
71
        propertyOverrides: Object.entries(propertyTranslations).map(
72
          ([propertyId, text]) => ({
73
            propertyId,
74
            text,
75
          })
76
        ),
77
      },
78
    ],
79
  };
80
81
  await client.pages.updateStaticContent(pageId, {
82
    localeId: secondaryLocaleId,
83
    nodes: instanceUpdates.nodes,
84
  });
85
}

Best practices

• Preserve HTML structure - Always maintain data-w-id attributes in HTML content. These identifiers preserve custom styling, animations, and links across locales. Example:

  1
  // Original: "<p>Price: <span data-w-id=\"b310743e-a1ac-8409-c039-d3b594afb816\">$10</span></p>"
  2
  // Localized: "<p>Precio: <span data-w-id=\"price-123\">$10</span></p>"

• Batch operations - Update multiple properties or nodes in single requests when possible (up to 1000 nodes per request)
• Pagination - Use limit and offset parameters in GET requests to retrieve all nodes/properties for components with extensive content
• Content inheritance - Only update content that needs localization; unchanged content inherits from the primary locale
• Test in Webflow - Verify localized content displays correctly across all component instances in Webflow. Refresh the canvas to see API changes reflected

FAQ