For frequently used components or those whose content remains consistent, localizing the component definition is the most effective approach. This method ensures that any changes made to the component's properties will automatically propagate to all instances, maintaining uniformity across your site while streamlining localization efforts.

Step 1: Identify Components to Localize

Start by identifying the main components you want to localize. You can obtain a comprehensive list of all components available on your site by calling the List Components endpoint. This endpoint provides details about each component, including its ID, name, group, and description.

Example Response

{
  "components": [
    {
      "id": "6596da6045e56dee495bcbba",
      "name": "Primary Button",
      "group": "Buttons",
      "description": "A default button component that can be used across the site"
    },
    {
      "id": "658205daa3e8206a523b5ad4",
      "name": "Secondary Button",
      "group": "Buttons",
      "description": "A secondary button component that can be used across the site"
    },
    {
      "id": "6258612d1ee792848f805dcf",
      "name": "Card",
      "group": null,
      "description": null
    },
    {
      "id": "68a2b1d1ee792848f805dcf",
      "name": "Nav",
      "group": null,
      "description": null,
      "readonly": true
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 4
  }
}

Understanding the component objec

Each component object contains the following properties:

• id: A unique identifier for the component.
• name: The name of the component.
• group: The category to which the component belongs, which may be null.
• description: A user-defined explanation of the component's purpose, which may be null.
• readonly: Indicates whether the component can be updated within the site. For example, components in Workspace Libraries are set to read-only.

Step 2: Localizing Component Properties

To localize a component definition, you’ll primarily work with its properties. With the ID of your selected component, use the Get Component Properties endpoint to get a list of the different properties that can be localized.

Example Response

{
  "componentId": "658205daa3e8206a523b5ad4",
  "properties": [
    {
      "id": "a245c12d-995b-55ee-5ec7-aa36a6cad623",
      "label": "Title",
      "type": "Plain Text",
      "text": {
        "html": null,
        "text": "The Hitchhiker's Guide to the Galaxy"
      }
    },
    {
      "id": "a245c12d-995b-55ee-5ec7-aa36a6cad627",
      "label": "Content",
      "type": "Rich Text",
      "text": {
        "html": "<div><h3>Don't Panic!</h3><p>Always know where your towel is.</p></div>",
        "text": null
      }
    }
  ],
  "pagination": {
    "limit": 2,
    "offset": 0,
    "total": 2
  }
}

Understanding the property object

Each property object consists of the following fields:

• id: The unique identifier for the property.
• label: The display name of the property.
• type: The type of data.
• text: An object containing the text values:
  • html: The HTML representation of the content.
  • text: Plain text representation.

📘

Viewing Component DOM

If you’d like to see the component's DOM structure, you can use the Get Component Content endpoint to fetch the static content of the component, that cannot be localized through properties.

Step 3: Updating Component property values in a secondary locale

Now that you have the properties of the component you wish to localize, you can translate the property values and use them as default values in your localized component definition.

To localize component property values in a secondary locale, we'll need to make a post request to the Update Component Properties endpoint. Our request should include the following:

xxxxxxxxxx
13
1
curl --request POST \
2
     --url 'https://api.webflow.com/beta/sites/65427cf400e02b306eaa049c/components/1fa6f97b-84f7-2db3-29cb-1275161e432f/properties?locale_id=65427cf400e02b306eaa04a0' \
3
     --header 'accept: application/json' \
4
     --header 'content-type: application/json' \
5
     --data '
6
{
7
  "properties": [
8
    {
9
      "propertyId": "a245c12d-995b-55ee-5ec7-aa36a6cad623",
10
      "text": "La guía del autoestopista galáctico"
11
    },
12
    {
13
      "propertyId": "a245c12d-995b-55ee-5ec7-aa36a6cad627",
14
      "text": "¡No entres en pánico!<p>Siempre sabe dónde está tu toalla.</p>"
15
    }
16
  ]
17
}
18
'

For components that are repurposed to fit the specific needs of a page—such as custom landing pages, campaigns, or time-sensitive promotions—localizing a component instance is the right approach. This method allows you to overwrite default text and tailor the content to resonate with local audiences.

When localizing a component instance, you'll make updates directly on the specific page where the instance appears, rather than modifying the component definition itself. It's important to note that while you're managing the localized component properties, the default property values must have been overwritten in the primary locale to ensure consistency and relevance.

Step 1: Get Page Content of the Primary Locale

To begin localizing a component instance, you need to retrieve the page content of the primary locale using the Get Page Content endpoint. This endpoint returns details about every element that can be localized, now including component instances.

📘

Overridden Properties

A component instance will only appear in the Get Page Content response if its property values have been overridden from the default settings in the primary locale. The API response will include only these overridden properties, and will not return static content of a component.

Example Response:

{
  "id": "34a7a7db-656d-7f88-167b-408785df039f",
  "type": "component-instance",
  "componentId": "1fa6f97b-84f7-2db3-29cb-1275161e432f",
  "properties": [
    {
      "id": "ea72bc3f-05ad-603b-1c91-6c6d875d1379",
      "text": {
        "html": null,
        "text": "Features"
      }
    },
    {
      "id": "c231a00f-3df8-ec07-15b7-86a4795541c4",
      "type": "Plain Text",
      "label": "Navbar link - Products",
      "text": {
        "html": null,
        "text": "Products"
      }
    },
    {
      "id": "52be38f0-169b-8da1-63f8-951da106280a",
      "type": "Plain Text",
      "label": "Navbar link - Resources",
      "text": {
        "html": null,
        "text": "Resources"
      }
    },
    {
      "id": "68924720-efbe-730d-eccf-47118e486009",
      "type": "Plain Text",
      "label": "Navbar link - Contact",
      "text": {
        "html": null,
        "text": "Contact"
      }
    },
    {
      "id": "6644d791-c4b3-a065-35c5-053d194a759b",
      "type": "Plain Text",
      "label": "Button Text - Get Started",
      "text": {
        "html": null,
        "text": "Get Started"
      }
    }
  ]
}

Component Instance Structure
A component instance has a different structure compared to regular elements. Here are the main fields you'll encounter:

• id: The element ID.
• type: The element type, which is component-instance.
• componentId: The ID of the component definition.
• properties: An array of all the overridden properties that can be localized. Each property object contains the following fields:
  • id: The property ID.
  • type: The property type (currently only text properties can be localized).
  • label: The property name as defined in the Component Definition.
  • text: An object containing the text and/or HTML of the property value. For now, the html value will always be null.

Step 2: Update Page Content of the Secondary Locale

With the IDs of the nodes and component properties you wish to update, you can create a payload for the Update Page Content endpoint to localize your content. This payload should include the nodeId of the component instance and an array of properties that need to be updated.

Example Payload

{
  "nodes": [
    {
      "nodeId": "1fa6f97b-84f7-2db3-29cb-1275161e432f",
      "properties": [
        {
          "propertyId": "ea72bc3f-05ad-603b-1c91-6c6d875d1379",
          "text": "Fonctionnalités"
        },
        {
          "propertyId": "c231a00f-3df8-ec07-15b7-86a4795541c4",
          "text": "Produits"
        },
        {
          "propertyId": "52be38f0-169b-8da1-63f8-951da106280a",
          "text": "Ressources"
        },
        {
          "propertyId": "68924720-efbe-730d-eccf-47118e486009",
          "text": "Contact"
        },
        {
          "propertyId": "6644d791-c4b3-a065-35c5-053d194a759b",
          "text": "Commencer"
        }
      ]
    }
  ]
}

In this example, we've only updated plain text properties. For other property types, ensure that the property value matches the expected type:

• Plain Text and Alt Text: text: Hello World!
• Rich Text: "text": <div><h1>Hello<em>World!</em></h1></div>

Step 3: Get Page Content of the Secondary Locale

Use the Get Page Content endpoint with the locale query parameter set to your secondary locale. This request will return the page content for that locale, including any localized changes to component instance properties.