A static site is just HTML, CSS and a little JavaScript, which makes it easy to build and surprisingly awkward to translate. There is no framework to lean on, so you choose how the text gets swapped and how search engines find each language. This guide builds both pieces from scratch with tested code: a small runtime that translates the page in the browser, and a build step that writes a real page per language for SEO. Then it shows the same result generated automatically.
| Translate in the browser | One HTML file per language | |
|---|---|---|
| How it works | One page; a script swaps the text after load | /, /fr/, /ar/ are separate pages built from the same source |
| Language URL | Same URL, choice remembered in the browser | Each language has its own URL |
| Search engines | See the source language | Index every language, linked with hreflang |
| Best for | Tools, dashboards, pages behind a login | Marketing sites, docs, anything that should rank |
Both start the same way: mark the text, then move it into one JSON file per language. That is most of the work, and it is shared.
Give every piece of visible text a key. Text content gets data-i18n; attributes that users see, such as placeholder, alt and the meta description's content, get data-i18n-attr with an attribute:key pair. Keep the English text in the HTML so the page still works if JavaScript fails.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title data-i18n="meta.title">Acme Notes - Simple note-taking</title>
<meta name="description" data-i18n-attr="content:meta.description" content="Write, tag and find your notes in seconds.">
<script src="/i18n.js" defer></script>
</head>
<body>
<nav>
<select id="language-picker" aria-label="Language">
<option value="en">English</option>
<option value="fr">Français</option>
<option value="ar">العربية</option>
</select>
</nav>
<h1 data-i18n="hero.title">Your notes, finally organized</h1>
<p data-i18n="hero.subtitle">Write, tag and find your notes in seconds.</p>
<input type="email" data-i18n-attr="placeholder:signup.placeholder" placeholder="you@example.com">
<button data-i18n="signup.button">Start free</button>
<img src="/screenshot.png" data-i18n-attr="alt:hero.imageAlt" alt="The Acme Notes editor">
</body>
</html>
Do not forget the parts nobody sees while designing: the <title>, the meta description, alt text and aria-labels. They show up in search results, browser tabs and screen readers.
Put the strings in locales/en.json, locales/fr.json and so on, with the same keys in every file. Nested keys keep related strings together; hero.title in the HTML means hero → title in the JSON. The French file:
{
"meta": {
"title": "Acme Notes - Prise de notes simple",
"description": "Écrivez, étiquetez et retrouvez vos notes en quelques secondes."
},
"hero": {
"title": "Vos notes, enfin organisées",
"subtitle": "Écrivez, étiquetez et retrouvez vos notes en quelques secondes.",
"imageAlt": "L'éditeur d'Acme Notes"
},
"signup": {
"placeholder": "vous@exemple.com",
"button": "Commencer gratuitement"
}
}Translate only the values, never the keys. For the file format itself (nesting, placeholders, plurals), see JSON translation files explained.
This script picks a language, loads its JSON file and replaces the marked text and attributes. It checks, in order: a language the visitor chose before, then the browser's preferred languages, then English. Only an explicit choice is saved, so a language detected automatically never overrides a later change in the browser's settings. It also sets lang and, for Arabic, Hebrew, Persian and Urdu, dir="rtl" on the <html> element.
const SUPPORTED = ["en", "fr", "ar"];
const DEFAULT_LANG = "en";
const RTL = new Set(["ar", "he", "fa", "ur"]);
// "hero.title" -> messages.hero.title
function lookup(messages, key) {
return key.split(".").reduce((node, part) => node?.[part], messages);
}
function pickLanguage() {
const saved = localStorage.getItem("lang");
if (SUPPORTED.includes(saved)) return saved;
for (const tag of navigator.languages ?? [navigator.language]) {
const base = tag.toLowerCase().split("-")[0];
if (SUPPORTED.includes(base)) return base;
}
return DEFAULT_LANG;
}
async function setLanguage(lang, { remember = false } = {}) {
const response = await fetch(`/locales/${lang}.json`);
const messages = await response.json();
for (const el of document.querySelectorAll("[data-i18n]")) {
const text = lookup(messages, el.dataset.i18n);
if (typeof text === "string") el.textContent = text;
}
// data-i18n-attr="placeholder:signup.placeholder; title:signup.hint"
for (const el of document.querySelectorAll("[data-i18n-attr]")) {
for (const pair of el.dataset.i18nAttr.split(";")) {
const [attr, key] = pair.split(":").map((s) => s.trim());
const text = lookup(messages, key);
if (attr && typeof text === "string") el.setAttribute(attr, text);
}
}
document.documentElement.lang = lang;
document.documentElement.dir = RTL.has(lang) ? "rtl" : "ltr";
// Only an explicit choice is remembered, so a detected language never overrides a later browser setting.
if (remember) localStorage.setItem("lang", lang);
const picker = document.getElementById("language-picker");
if (picker) picker.value = lang;
}
document.addEventListener("DOMContentLoaded", () => {
document.getElementById("language-picker")
?.addEventListener("change", (event) => setLanguage(event.target.value, { remember: true }));
setLanguage(pickLanguage());
});
We ran it in a simulated browser (jsdom) with four visitors. A French-Canadian browser (fr-CA) got French, including the title, meta description, placeholder and image alt text. Picking Arabic switched the page to right-to-left and saved the choice. A German browser returning with Arabic saved got Arabic. A browser with only unsupported languages (de, ja) got English and saved nothing.
Two things this approach cannot avoid. The page renders in English for a moment before the translation arrives, and search engines index the English text. For a tool behind a login, that is fine. For pages that should rank in other languages, add step 4.
Search engines index each language best when it has its own URL with the translated text already in the HTML. The same data-i18n markup and JSON files can produce that at build time. This Node script (it needs jsdom: npm install jsdom) writes dist/index.html in English plus dist/fr/index.html and dist/ar/index.html, each with its own lang and dir, a canonical URL, hreflang links to every language and plain links for switching:
// Pre-render one HTML file per language so search engines see translated text.
// Usage: node build.mjs (reads site/, writes dist/)
import fs from "node:fs";
import path from "node:path";
import { JSDOM } from "jsdom";
const SITE_URL = "https://example.com";
const LANGS = ["en", "fr", "ar"];
const DEFAULT_LANG = "en";
const RTL = new Set(["ar", "he", "fa", "ur"]);
const LABELS = { en: "English", fr: "Français", ar: "العربية" };
const lookup = (messages, key) => key.split(".").reduce((node, part) => node?.[part], messages);
const urlFor = (lang) => (lang === DEFAULT_LANG ? `${SITE_URL}/` : `${SITE_URL}/${lang}/`);
const source = fs.readFileSync("site/index.html", "utf8");
for (const lang of LANGS) {
const messages = JSON.parse(fs.readFileSync(`site/locales/${lang}.json`, "utf8"));
const dom = new JSDOM(source);
const doc = dom.window.document;
for (const el of doc.querySelectorAll("[data-i18n]")) {
const text = lookup(messages, el.dataset.i18n);
if (typeof text !== "string") throw new Error(`${lang}: missing ${el.dataset.i18n}`);
el.textContent = text;
}
for (const el of doc.querySelectorAll("[data-i18n-attr]")) {
for (const pair of el.dataset.i18nAttr.split(";")) {
const [attr, key] = pair.split(":").map((s) => s.trim());
const text = lookup(messages, key);
if (typeof text !== "string") throw new Error(`${lang}: missing ${key}`);
el.setAttribute(attr, text);
}
}
doc.documentElement.lang = lang;
doc.documentElement.dir = RTL.has(lang) ? "rtl" : "ltr";
// The runtime loader isn't needed on pre-rendered pages.
doc.querySelector('script[src="/i18n.js"]')?.remove();
// Swap the <select> for plain links: each language is its own URL now.
const nav = doc.querySelector("nav");
nav.innerHTML = LANGS.map(
(l) => `<a href="${urlFor(l)}" hreflang="${l}" lang="${l}"${l === lang ? ' aria-current="page"' : ""}>${LABELS[l]}</a>`
).join(" ");
// Canonical + hreflang alternates, including x-default.
const head = doc.head;
head.insertAdjacentHTML("beforeend", `<link rel="canonical" href="${urlFor(lang)}">`);
for (const l of LANGS) head.insertAdjacentHTML("beforeend", `<link rel="alternate" hreflang="${l}" href="${urlFor(l)}">`);
head.insertAdjacentHTML("beforeend", `<link rel="alternate" hreflang="x-default" href="${urlFor(DEFAULT_LANG)}">`);
const outDir = lang === DEFAULT_LANG ? "dist" : path.join("dist", lang);
fs.mkdirSync(outDir, { recursive: true });
fs.writeFileSync(path.join(outDir, "index.html"), dom.serialize());
console.log(`wrote ${path.join(outDir, "index.html")}`);
}
The script stops with an error if any language is missing a key, for example fr: missing signup.button, rather than shipping a French page with an English button. Upload dist/ to any static host. The hreflang links tell search engines the pages are translations of each other; the hreflang guide covers the rules, and BCP 47 language codes explains which codes to use.
dir="rtl" flips the page, but margins and paddings written as left/right do not flip. Use logical properties such as margin-inline-start; see RTL support with CSS logical properties.Intl.DateTimeFormat and Intl.NumberFormat for the current language; see the Intl API guide.data-i18n never sees them. Look them up from the same JSON file instead of hardcoding English./i18n.js, /locales/) or paths relative to the page, so blog/post.html finds them too.Marking every string, inventing keys and keeping the JSON files in sync is the slow part, and it starts again whenever the copy changes. The Babelize CLI does steps 1 to 3 on an existing site. Run it at the root of a git repository with your HTML files and a clean working tree. It translates with your own LLM API key (Anthropic, OpenAI, Gemini, Groq or OpenRouter, read from the environment) or a Babelize API key:
npx @babelize/cli translate --to fr,de,ar
It finds the text in every HTML page (headings, paragraphs, buttons, links, alt, title, placeholder and aria-label attributes, the <title> and SEO meta tags), adds data-i18n keys, writes locales/en.json and translated files for each language, and adds an i18n.js runtime with no dependencies. Here is what it changed on the example page from step 1, before we added any markup by hand:
<title data-i18n="indexhtml.acmeNotesSimpleNoteTaking">Acme Notes - Simple note-taking</title>
<meta name="description" content="Write, tag and find your notes in seconds." data-i18n-content="indexhtml.writeTagAndFindYour">
<h1 data-i18n="indexhtml.yourNotesFinallyOrganized">Your notes, finally organized</h1>
<p data-i18n="indexhtml.writeTagAndFindYour">Write, tag and find your notes in seconds.</p>
<input type="email" placeholder="Your email address" data-i18n-placeholder="indexhtml.yourEmailAddress">
<button data-i18n="indexhtml.startFree">Start free</button>
<img src="screenshot.png" alt="The Acme Notes editor" data-i18n-alt="indexhtml.theAcmeNotesEditor">
<a href="blog/first-post.html" data-i18n="indexhtml.readOurBlog">Read our blog</a>
<script src="i18n.js"></script>The keys are generated from the page name and the text, and the English file looks like this (excerpt):
{
"_meta": {
"dir": "ltr",
"language": "en"
},
"indexhtml": {
"yourNotesFinallyOrganized": "Your notes, finally organized",
"startFree": "Start free",
"yourEmailAddress": "Your email address"
}
}
The runtime picks the language from a ?lang=fr URL parameter, then the visitor's earlier choice, then the browser, and falls back to the source language. Add <div data-babelize-switcher></div> where you want a language picker. Pages in subfolders get a script path that points back to the root, so the whole site translates.
Everything lands in your working tree as a normal git diff, so you review it before committing, and a lockfile means the next run only translates new or changed strings. To see the result on your own site without an API key, run it with --provider pseudo, which fills the files with obviously fake text such as ⟦Stárt fréé⟧ instead of calling a translation model (do not ship that output). babelize check then reports missing keys and broken placeholders in every language, locally and in CI.
The Babelize runtime translates in the browser, like step 3. If the pages need to rank in every language, keep the generated JSON files and run them through a build step like step 4.
Yes. Mark the text with data-i18n attributes, store the translations in one JSON file per language, and either swap the text in the browser with a small script or generate one HTML file per language at build time. No framework or npm package is needed for the browser version.
Not reliably. When the text is swapped in the browser, there is one URL per page and it serves the source language, so search engines mostly see that. For pages that should rank in other languages, generate a separate HTML file per language with its own URL and link them with hreflang.
Machine translation in the visitor's browser needs no setup, but you cannot review or edit the result, search engines do not index it as your pages, and it knows nothing about your product's terminology. Translating your own files gives you control over every string.
In the browser approach, use a <select> that calls your setLanguage function and saves the choice in localStorage. With one page per language, use plain links to each language's URL, so the switcher works without JavaScript and search engines can follow it.
Set dir="rtl" and the right lang on the <html> element for those languages, and write CSS with logical properties such as margin-inline-start so the layout mirrors correctly.