Data API: Ecommerce and Localization

{
  "name": "fernbrook-shop-and-i18n",
  "private": true,
  "type": "module",
  "engines": { "node": ">=22.13" },
  "dependencies": {
    "webflow-api": "3.3.4"
  },
  "devDependencies": {
    "tsx": "4.19.2",
    "typescript": "7.0.2",
    "@types/node": "22.9.0"
  }
}

webflow==2.0.0

export WEBFLOW_API_TOKEN="REPLACE_WITH_SITE_TOKEN"
export WEBFLOW_SITE_ID="REPLACE_WITH_SITE_ID"
export WEBFLOW_PLANTS_COLLECTION_ID="REPLACE_WITH_COLLECTION_ID"
npm install

// fernbrook-i18n.ts
import { WebflowClient } from "webflow-api";

const token = process.env.WEBFLOW_API_TOKEN!;
const siteId = process.env.WEBFLOW_SITE_ID!;
const plantsId = process.env.WEBFLOW_PLANTS_COLLECTION_ID!;
const homePageId = process.env.WEBFLOW_HOME_PAGE_ID!;
const API = "https://api.webflow.com/v2";

const client = new WebflowClient({ accessToken: token });

// --- a minimal fetch helper with 429 backoff (the SDK retries too, this covers typings gaps)
async function wf<T>(path: string, init: RequestInit = {}, attempt = 0): Promise<{ status: number; body: T }> {
  const res = await fetch(`${API}${path}`, {
    ...init,
    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", ...init.headers },
  });
  if (res.status === 429 && attempt < 5) {
    const wait = Number(res.headers.get("retry-after") ?? "60");
    await new Promise((r) => setTimeout(r, wait * 1000));
    return wf<T>(path, init, attempt + 1);
  }
  const text = await res.text();
  return { status: res.status, body: (text ? JSON.parse(text) : {}) as T };
}

// --- the source of translations; replace with a glossary file or a translation service
const glossary: Record<string, Record<string, string>> = {
  "es-ES": { "Welcome to Fernbrook Gardens": "Bienvenido a los Jardines Fernbrook", "Plan your visit": "Planifique su visita",
    "Japanese maple": "Arce japones", "A slow-growing tree with red autumn leaves.": "Un arbol de crecimiento lento con hojas rojas en otono." },
  "de-DE": { "Welcome to Fernbrook Gardens": "Willkommen in den Fernbrook Gardens", "Plan your visit": "Besuch planen",
    "Japanese maple": "Japanischer Faecherahorn", "A slow-growing tree with red autumn leaves.": "Ein langsam wachsender Baum mit roten Herbstblaettern." },
};
const translate = (tag: string, text: string) => glossary[tag]?.[text] ?? text;

// 1. locale identifiers: localeId for pages, cmsLocaleId for items
const site = await client.sites.get(siteId);
const secondary = (site.locales?.secondary ?? []).filter((l) => l.tag === "es-ES" || l.tag === "de-DE");
if (secondary.length !== 2) throw new Error("enable the es-ES and de-DE locales first");

// 2. CMS: one request creates the plant in every locale (primary + secondary), same item id
const created = await wf<{ items: { id: string; cmsLocaleId: string }[] }>(`/collections/${plantsId}/items/insert`, {
  method: "POST",
  body: JSON.stringify({
    items: [{ allCmsLocales: true, fieldData: {
      name: "Japanese maple", slug: "japanese-maple", "short-description": "A slow-growing tree with red autumn leaves.",
    } }],
  }),
});
if (created.status >= 300) throw new Error(`create failed: ${created.status}`);
const itemId = created.body.items[0].id;

// 3. write the translated field values per variant, with a localized slug
await wf(`/collections/${plantsId}/items`, {
  method: "PATCH",
  body: JSON.stringify({
    items: secondary.map((l) => ({
      id: itemId,
      cmsLocaleId: l.cmsLocaleId,
      fieldData: {
        name: translate(l.tag!, "Japanese maple"),
        slug: l.tag === "es-ES" ? "arce-japones" : "japanischer-faecherahorn",
        "short-description": translate(l.tag!, "A slow-growing tree with red autumn leaves."),
      },
    })),
  }),
});

// 4. publish each locale on its own
for (const l of secondary) {
  const r = await wf(`/collections/${plantsId}/items/publish`, {
    method: "POST",
    body: JSON.stringify({ items: [{ id: itemId, cmsLocaleIds: [l.cmsLocaleId] }] }),
  });
  console.log("published", l.tag, r.status);
}

// 5. pages: read the primary DOM, translate text nodes, write to each secondary locale
type Node = { id: string; type: string; text?: { html?: string | null; text?: string | null } };
const primaryLocaleId = site.locales!.primary!.id!;

for (const l of secondary) {
  let q = `?localeId=${primaryLocaleId}&translatable=${l.id}&limit=100`;
  let dom = await wf<{ nodes: Node[] }>(`/pages/${homePageId}/dom${q}`);
  if (dom.status === 403) {
    q = `?localeId=${primaryLocaleId}&limit=100`; // translation exclusions are not enabled
    dom = await wf<{ nodes: Node[] }>(`/pages/${homePageId}/dom${q}`);
  }

  const nodes = dom.body.nodes
    .filter((n) => n.type === "text" && n.text?.html)
    .map((n) => ({
      nodeId: n.id,
      // keep the tag structure and data-w-id attributes; swap only the words between the tags
      text: n.text!.html!.replace(/>([^<]+)</g, (_m, words: string) => `>${translate(l.tag!, words.trim())}<`),
    }));

  const r = await wf<{ errors?: unknown[] }>(`/pages/${homePageId}/dom?localeId=${l.id}`, {
    method: "POST",
    body: JSON.stringify({ nodes }),
  });
  console.log("page", l.tag, r.status, "errors:", r.body.errors?.length ?? 0);
}

export WEBFLOW_HOME_PAGE_ID="REPLACE_WITH_PAGE_ID"
npx tsx fernbrook-i18n.ts

# translate_page.py
import os
from webflow import Webflow, TextNodeWrite

client = Webflow(access_token=os.environ["WEBFLOW_API_TOKEN"])
page_id = os.environ["WEBFLOW_HOME_PAGE_ID"]
spanish_locale_id = "REPLACE_WITH_SPANISH_LOCALE_ID"

dom = client.pages.get_content(page_id, limit=100)  # primary locale
nodes = [
    TextNodeWrite(node_id=n.id, text=n.text.html.replace("Plan your visit", "Planifique su visita"))
    for n in dom.nodes or []
    if n.type == "text" and n.text and n.text.html
]
client.pages.update_static_content(page_id, locale_id=spanish_locale_id, nodes=nodes)