Localizing components

Learn how to use the Data API to localize component content and properties across different locales.

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.

Key concepts

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

A component definition serves as the blueprint for a component. It contains the component’s static content, like text and images, and defines the component’s properties: customizable fields that allow for dynamic content. When you change a component definition, the updates apply to all instances of that component, unless an instance has a property override.

A component definition contains two types of localizable content:

  • Static content: Text nodes, form elements, and nested component instances

  • Property defaults: Default text values for component properties

    Component Definition

Localizable content

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

Content TypeScopeDescription
Property OverridesPage-specific
Instance
Custom values applied to a single component instance.
Property DefaultsSite-wide
Definition
Default values for properties, used by instances without an override.
Static ContentSite-wide
Definition
Fixed text content that’s part of the component’s structure.

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 Logo
Static content

Text nodes, form elements, and nested component instances

Property Defaults Logo
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.

1

List site components

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

2

Get static content of a component

Use the Get Component Content endpoint to get the static content of a selected component definition.

3

Update static content of a component

Use the Update Component Content endpoint to update the static content of the selected component definition in a secondary locale.

List site components

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

Request
1curl -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.

Response

componentslist of objectsOptional
paginationobjectOptional
Pagination object
Response
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
1curl -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.

Response

componentIdstringOptional
Component ID
nodeslist of objectsOptional
paginationobjectOptional
Pagination object
Get Component Content response example
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 typeDescription
textRepresents text content. Including headings, text blocks, rich text, form labels, and other text content on a page.
imageRepresents static images on a page. It contains alt text details for accessibility and the assetId for fetching the actual image resource.
text-inputRepresents a textinput and textarea fields on a form.
selectRepresents a select field and its options on a form.
submit-buttonRepresents a submit button on a form. It contains the button text and waiting text of the button.
search-buttonRepresents the button text of a search button on a site search element.
component-instanceRepresents a component instance on a page. Learn more about localizing components in the guide.

Node properties

Each node type has a specific structure and properties that define the content it contains. However, all nodes will have id, type, and attributes properties.

id
stringRequired

Node UUID

type
enumRequired

The type of the node.

attributes
map from strings to strings

The custom attributes of the node


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.


id
stringRequired

Node UUID

type
enumRequired

The type of the node. text

text
objectRequired

The text content of the node

html
stringRequired

The HTML content of the node

text
stringRequired

The text content of the node

attributes
map from strings to strings

The custom attributes of the node

Text node example
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}
Nested HTML tags

The text.html property may contain nested HTML tags with data-w-id attributes (e.g., data-w-id="some-unique-identifier"). Retain these identifiers when updating page content in secondary locales to preserve custom attributes and links on inner HTML elements.

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
1curl -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.

1

List site components

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

2

Get component properties

Use the Get Component Properties endpoint to get the default properties of the selected component definition.

3

Update component properties

Use the Update Component Properties endpoint to update the default properties of the selected component definition.

List site components

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

Request
1curl -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.

Response

componentslist of objectsOptional
paginationobjectOptional
Pagination object
Response
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
1curl -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.

Response

componentIdstringOptional
Component ID
propertieslist of objectsOptional
paginationobjectOptional
Pagination object
Response
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
1curl -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
GET
/beta/pages/:page_id/dom
1curl -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:

propertyId
stringRequired

The unique identifier for the property being overridden.

type
'Plain Text' | 'Rich Text'Required

The type of the property.

label
stringRequired

The user-defined label for the property.

text
objectRequired

An object containing the overridden text content.

html
string | null

The HTML content for “Rich Text” properties. This will be null for “Plain Text” properties.

text
string | null

The plain text content for “Plain Text” properties. This will be null for “Rich Text” properties.

Response
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
1curl -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:

Node.js
1const client = new WebflowClient({ accessToken: "YOUR_ACCESS_TOKEN" });
2
3// Example `translations` object holding the localized content for the secondary locale
4async 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
60async 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

Component definition localization affects all the base static content that lives in each instance of that component across your site, while instance localization only affects the specific component instance on a particular page through property overrides.

No, read-only components (like those from Workspace Libraries) can’t be updated via the APIs. These components are marked with readonly: true in the List Components response.

Yes, updating component definition property defaults affects all instances that don’t have property overrides for those specific properties. Instances with overrides maintain their custom values and won’t be affected by changes to the component definition.

In the primary locale, all component instances appear in the Get Page Content response. In secondary locales, only component instances with property overrides are included, providing a focused view of customized content that differs from the default component definition.

No, static content and properties require separate API calls. Use the Update Component Content endpoint for static content and Update Component Properties for property values.

If you omit data-w-id attributes when updating HTML content, you may lose custom attributes or links that were applied to those elements in Webflow. Always preserve these identifiers exactly as they appear in the original content.