Working with Localization

1. Clone the AstralFund site to your Webflow account, and add it to a Workspace used for testing.
2. Publish the site to set it live.
3. Navigate to the French locale to see the localized French homepage.
4. Navigate to the Contact page in French. Note the content that is not yet localized. We’ll fix this by localizing the navigation bar, contact content, form, footer, and SEO data.

1. Clone the Example Repository
   Clone the example repository and install dependencies.

   $
   git clone https://github.com/Webflow-Examples/Localization-Demo.git
   $
   cd localization-demo
   $
   npm install

2. Authenticate with your Bearer Key
   Make sure you have a valid Bearer Key that is authenticated for your new site. You can do this by authenticating through our API reference docs. Once you have your Bearer Key, store it in your .env file as WEBFLOW_API_TOKEN.

3. Create localization.js
   There’s a full example of all the steps below in index.js. However, if you’d like to follow along with this guide, create a new file called localization.js, and include the following imports of the translated content, as well as the Webflow Javascript SDK.

   localization.js

   1
     // Import the pre-prepared localized content
   2
     import localizedDOM from "./helpers/Contact Us - French.json" assert {type: "json"}; // Localized "Contact Us" DOM
   3
     import localizedMetadataBody from "./helpers/seoData.json" assert {type: "json"}; // Localized SEO Data
   4
     import frenchTestimonials from "./helpers/Testimonials - French.json" assert {type: "json"}; // Localized Testimonials
   5
     import newFrenchTestimonial from "./helpers/newTestimonial.json" assert {type: "json"}; // New French Testimonial
   6
   7
     // Import the Webflow Javascript SDK
   8
     import { WebflowClient } from "webflow-api";
   9
     import dotenv from "dotenv";

4. Initialize the API
   Create an asynchronous function, and initialize the API using the Webflow JavaScript SDK:

   localization.js

   1
   async function localizePage() {
   2
     try {
   3
   4
       // Initialize the API.
   5
       dotenv.config();
   6
       const token = process.env.WEBFLOW_API_TOKEN;
   7
       const webflow = new WebflowClient(\{ accessToken: token });
   8
   9
       /* ADD CODE FROM GUIDE HERE */
   10
   11
     } catch (error) {
   12
       console.error("An error occurred:", error);
   13
     }
   14
   }
   15
   localizePage();

   After each step, you can run the file by typing the command node localization to see your progress.

In this step we’ll retrieve the site and locale identifiers, so that we can make locale-specific requests to our site.

1. Call the List Sites endpoint to find your siteId and locale information.
   Replace the siteName variable with the name of your cloned site.

   JavaScript

   1
   // List sites and get the Astral Fund site's details
   2
   const siteName = "AstralFund" // Change the site name to the name of your cloned site
   3
   const sites = await webflow.sites.list();
   4
   const astralFundSite = sites.sites.find((site) =>
   5
     site.displayName.includes(siteName)
   6
   );
   7
   const siteId = astralFundSite.id;
   8
   const siteDetails = await webflow.sites.get(siteId); // Get site details for locale information

2. Extract the localeId for both English and French from the Site object:

   • Notice the locales parameter, which returns a primary locale, and an array of secondary locales.
   • Each locale has useful information like the language, location, and more.
   • In addition to a specific localeId, each locale also has a cmsLocaleId.
   localization.js

   1
   // Extract and store locale IDs
   2
   const locales = siteDetails.locales;
   3
   const secondaryLocaleId = locales.secondary[0].id; // French is the first secondary locale
   4
   const secondaryCmsLocaleId = locales.secondary[0].cmsLocaleId;
   5
   console.log([locales, secondaryLocaleId, secondaryCmsLocaleId]);

In this step, we’re getting the content from a static, primary page, and uploading a translated version to our locale-specific page.

1. Get the page_id of the Contact Us page using the List Pages endpoint.

   JavaScript

   1
     // Get the page information for "Contact Us"
   2
     const pages = await webflow.pages.list(siteId);
   3
     const contactPage = pages.pages.find((page) =>
   4
       page.title.includes("Contact")
   5
     );
   6
     const contactPageId = contactPage.id;

2. Get the content of the Primary Locale using the Read DOM endpoint.
   This will return all content that can be localized from a static page, which we can then translate for our locale-specific page.

   📘 As of Sep 22, 2023, we only support writing to Text and Rich Text to the DOM. We do not support updating images via this API.

3. Modify the content to include localized versions of the nav bar, contact content, form, and footer.

   We’ve provided a localized DOM for you with ./helpers/Contact Us - French.json. From this example, create a DOM write object, with an array of DOM Nodes and the cmsLocaleId.
   

   ./helpers/Contact Us - French.json

   1
   {
   2
     "pageId": "65427cf400e02b306eaa0496",
   3
     "nodes": [
   4
         {
   5
           "nodeId": "8017772e-bc46-5c59-54c0-134cdfd4b03a",
   6
           "text": "<h2>Contactez-nous</h2>"
   7
         },
   8
         {
   9
           "nodeId": "8017772e-bc46-5c59-54c0-134cdfd4b03c",
   10
           "text": "<p>Notre équipe d'experts en finances n'est qu'à un appel téléphonique. Composez notre numéro sans frais, et discutons !<br /></p>"
   11
         },
   12
         {
   13
           "nodeId": "aa9e4de0-011e-ac64-cbc2-3ec4fa3a8bb8",
   14
           "text": "<a>hello@astralfunds.com</a>"
   15
         },
   16
         {
   17
           "nodeId": "aa9e4de0-011e-ac64-cbc2-3ec4fa3a8bbd",
   18
           "text": "<a>+1 (555) 000-0000</a>"
   19
         },
   20
         {
   21
           "nodeId": "aa9e4de0-011e-ac64-cbc2-3ec4fa3a8bc2",
   22
           "text": "<a>398 11th Street, 2ème étage, San Francisco, CA 94103</a>"
   23
         },
   24
         {
   25
           "nodeId": "8017772e-bc46-5c59-54c0-134cdfd4b0c4",
   26
           "text": "<p>Merci ! Votre message a été reçu.</p>"
   27
         },
   28
         {
   29
           "nodeId": "8017772e-bc46-5c59-54c0-134cdfd4b0c6",
   30
           "text": "<p>Notre équipe répondra à votre message dès que possible. Merci de votre patience.</p>"
   31
         },
   32
         {
   33
           "nodeId": "8017772e-bc46-5c59-54c0-134cdfd4b0c9",
   34
           "text": "<div>Oups ! Quelque chose s'est mal passé lors de l'envoi de votre message.</div>"
   35
         },
   36
         {
   37
           "nodeId": "36c1f507-a281-83c4-8222-873b4179b955",
   38
           "text": "<h1>Commencez à banquer maintenant</h1>"
   39
         },
   40
         {
   41
           "nodeId": "36c1f507-a281-83c4-8222-873b4179b957",
   42
           "text": "<div>Adoptez une nouvelle ère de gestion financière</div>"
   43
         },
   44
         {
   45
           "nodeId": "36c1f507-a281-83c4-8222-873b4179b95b",
   46
           "text": "<div>Commencez</div>"
   47
         },
   48
         {
   49
           "nodeId": "36c1f507-a281-83c4-8222-873b4179b95e",
   50
           "text": "<div>En savoir plus</div>"
   51
         }
   52
       ],
   53
       "pagination": { "limit": 100, "offset": 0, "total": 22 }
   54
     }

4. Update the content of the French locale by making a POST request to the Update DOM endpoint.
   Be sure to include the localeId in the locale query parameter.

   JavaScript

   1
   // Get the DOM for the Contact Us page in English and translate to French
   2
   const primaryContactPageDom = await webflow.pages.getContent(contactPageId);
   3
   4
   // Create the domWrite object with the nodes and cmsLocaleId
   5
   const domWrite = {
   6
     nodes: localizedDOM.nodes,
   7
     locale: secondaryLocaleId,
   8
   };
   9
   10
   // Update the Contact Us page DOM with French content
   11
   await webflow.pages.updateStaticContent(contactPageId, domWrite);

In this step, we’ll update the SEO metadata for the French version of the page.

1. Retrieve the primary page’s SEO data via a GET request to the Get Page Metadata endpoint.

   Request

   Response

   JavaScript

   1
   // Get page metadata
   2
   const pageMetadata = await webflow.pages.getMetadata(contactPageId);

2. Translate the data so that it’s relevant for the French audience.

   We’ve provided localized information for you with ./helpers/seoData.json.

   ./helpers/seoData.json

   1
   {
   2
     "title": "Contactez-nous",
   3
     "slug": "contactez-nous",
   4
     "seo": {
   5
       "title": "Contactez-nous | AstralFund Financier",
   6
       "description": "Contactez AstralFund Financier pour des conseils financiers experts et un soutien. Notre équipe dédiée est là pour vous aider sur votre chemin vers le succès financier. Contactez-nous aujourd'hui."
   7
     },
   8
     "openGraph": {
   9
       "title": "AstralFund Financier - Votre partenaire pour la réussite financière",
   10
       "titleCopied": true,
   11
       "description": "Découvrez les services financiers personnalisés d'AstralFund et prenez le contrôle de votre avenir financier. Contactez-nous pour en savoir plus.",
   12
       "descriptionCopied": true
   13
     }
   14
   }

3. Update the SEO Data for the French locale via a POST request to the Update Page Metadata endpoint.

   Be sure to enter the localeId in the locale query parameter.

   JavaScript

   1
   // Get page metadata
   2
   const pageMetadata = await webflow.pages.getMetadata(contactPageId);
   3
   4
   // Create Localized Page Setting Request
   5
   const localizedMetadata = {};
   6
   localizedMetadata.locale = secondaryLocaleId;
   7
   localizedMetadata.body = localizedMetadataBody; // Use the localized SEO data
   8
   9
   // Update SEO Data
   10
   await webflow.pages.updatePageSettings(contactPageId, localizedMetadata);

To demonstrate AstralFund’s commitment to the French market, we’ll translate the existing testimonials, and create a French-specific testimonial from a French regulatory authority.

1. Get existing testimonials and translate them using our provided translation.

   Javascript

   1
   // Get Collections
   2
   const collectionsData = await webflow.collections.list(siteId);
   3
   const collections = collectionsData.collections;
   4
   5
   // Find Testimonials Collection
   6
   const testimonialsCollectionId = collections.find(
   7
     (collection) => collection.displayName === "Testimonials"
   8
   ).id;
   9
   10
   const itemsData = await webflow.collections.items.listItems(
   11
     testimonialsCollectionId
   12
   );
   13
   const items = itemsData.items; // Get item data from testimonial collection

2. For each translated testimonial, update the CMS item via the Update Collection Item endpoint. Be sure to include cmsLocaleId in the Item.

   JavaScript

   1
   try {
   2
     // For each CMS item
   3
     for (const [index, value] of items.entries()) {
   4
   5
       // Add the secondary `cmsLocaleId` to the item
   6
       frenchTestimonials[index].cmsLocaleId = secondaryCmsLocaleId;
   7
   8
       // Update the CMS item
   9
       const updatedItem = await webflow.collections.items.updateItemLive(
   10
         testimonialsCollectionId,
   11
         value.id,
   12
         frenchTestimonials[index]
   13
       );
   14
       console.log(`Item:`, updatedItem);
   15
     }
   16
   } catch (error) {
   17
     console.error(`Error updating CMS items:`, error);
   18
     throw error;
   19
   }

3. Create a French-only testimonial using our provided translation.

   1
   // Create new item
   2
   try {
   3
     // Set the `cmsLocaleId` of the new item
   4
     newFrenchTestimonial.cmsLocaleId = secondaryCmsLocaleId;
   5
   6
     const newTestimonial = await webflow.collections.items.createItem(
   7
       testimonialsCollectionId,
   8
       newFrenchTestimonial
   9
     );
   10
     console.log("Localization process completed successfully.");
   11
   } catch (error) {
   12
     console.error("Error Creating CMS Item:", error);
   13
   }

Congratulations! You’ve localized your AstralFund site! Take a look around the site and see what other opportunities you have to localize content.

Primary Locale

Secondary Locale

United States 🇺🇸

The site’s primary locale is set to the United States with content in English.