DEV Community: Sergei Ivantsov

Four layers of defense for a multilingual site

Sergei Ivantsov — Wed, 23 Sep 2026 13:25:25 +0000

I keep building multilingual sites. Restaurants, shops, now apartment listings on Northern Cyprus. People assume the hard part is translation. It isn't. The hard part is keeping four languages in sync after you ship, when nobody is looking.

Here is what actually holds a multilingual site together. Not one trick. Four layers, and each one catches a different kind of failure.

Layer 1: the generator

Text used to live copy-pasted across twenty HTML files: five page types, four languages. On September 7 that broke. The title, the og:title, and the JSON-LD name for one listing were out of sync on all four languages, because someone (me, with an AI agent) copied the string by hand one too many times. The Polish version used a different phrase entirely.

The fix wasn't "be more careful next time." It was build/generate-seo.js: one data file, one generator, twenty files written from it. A --check flag fails the build if a file drifted from the source instead of silently overwriting it. This is the layer that makes structural drift physically impossible, not just unlikely.

$ node build/generate-seo.js --check
SEO head blocks are up to date.
Body blocks are up to date.

That's the whole contract: the generator either confirms the twenty files still match the source, or it fails the build. No middle state where a file is quietly out of sync.

Layer 2: the linter

The generator can't see style. It writes what the data file says, correctly, forever. If the data file itself is inconsistent, the generator faithfully ships that inconsistency four times.

So I wrote build/lint-text.js. It caught British spelling mixed with American in my own English copy. It caught the same empty hedge word duplicated across languages by the same translation habit: "actually" in English, "на самом деле" in Russian, "gerçekte" in Turkish, "naprawdę" in Polish — one language picks up a verbal tic, and if you don't check, it rides along into every translation.

Dash frequency needed per-language thresholds, not one global number. English prose runs light on em dashes. Russian carries more. Turkish and Polish sit somewhere in between. A linter tuned for one language would either flag good Russian prose as robotic or miss actual robotic English.

$ node build/lint-text.js
...
· listing reciaoglu    en  empty evaluative adjective   2
...
Notes: 0 warnings, 1 flag.

(trimmed; the real run checks every listing in all four languages and prints a full table even when it finds nothing — that flag above was a real one, not staged for this article.)

Layer 3: the trained eye

Neither tool catches meaning. A flyer said "~50 km to both airports." True for Ercan. Off by 20 km for Larnaca. Grammatically fine, technically consistent, and wrong, because nobody checked the number against the actual reader driving to the actual airport. That's not a generator problem or a linter problem. That's a person who reads the sentence and asks "is this true for the person landing at Larnaca," and my background is translation, so noticing when a sentence says one thing in one language and something slightly different in another is close to the whole job.

-           <li>About 50 km to Ercan and Larnaca airports</li>
+           <li>About 50 minutes by car to Ercan airport</li>
+           <li>About 70 minutes to Larnaca — the route crosses the checkpoint</li>

One commit, same change repeated across all four language blocks in the same file — because the flawed number wasn't a typo in one place, it was the same inherited assumption translated four times.

The same instinct works before anything is written, not just after. Nobody asked for a disclaimer page or an "about" page on a private listing site. I added both on day two: the site is not an agency, takes no prepayment, and the deal is between the two sides. No checklist told me to. It's the same trained eye, pointed at trust instead of at a sentence — noticing what a reader needs to see before they'll believe the rest of the page.

Layer 4: going back and looking

The three layers above run at build time. None of them catch a section that's simply missing from the template. data-reading, the "worth reading before you buy" block linking to the climate article, was absent from three of four homepage templates entirely. Not empty. Not there. The generator can't fill a slot that doesn't exist, and no linter checks for missing HTML structure.

I found it by doing the unglamorous thing: opening the live site periodically and reading it like a stranger would. Same pass caught the language button order drifting out of sync with the default language, and a footer note still describing two listings after two more had been added.

Why all four, and not just the best one

Each layer catches what the others structurally cannot. The generator kills copy-paste drift. The linter kills style drift the generator inherits from bad source data. The eye kills meaning-level errors no automated check understands. And periodic re-reading kills the class of bug where something simply isn't there to check.

Skip any one layer and a specific kind of mistake gets through, quietly, in all four languages at once.

This whole habit started with the same thought as the first post in this series: "let's just do it right." Turns out doing it right on a multilingual site means doing it right four times, once per language, every single time.

The site is still here and growing: girne-apartment-sale.com. The layer 1 generator is open source: seo-generator on GitHub.

My AI agent copy-pasted SEO tags across 20 files instead of generating them

Sergei Ivantsov — Thu, 10 Sep 2026 16:01:55 +0000

I wrote a small generator to stop an AI coding agent from hand-duplicating SEO metadata across a multilingual static site. It has a --check flag that verifies the generated files still match their data source. The day after I shipped it, I found that when the generator silently corrupted all 20 pages, --check reported it as "out of date" — the exact same message it prints when you legitimately edit the data file and haven't regenerated yet.

That's the part worth writing down. A verification flag that can't distinguish "you changed something on purpose" from "the tool just wrote broken URLs into every page you have" isn't verifying much. Here's how I got there.

The site

A free, direct-from-owner property listing site for North Cyprus — girne-apartment-sale.com, no agency, no commission. Vanilla HTML/CSS/JS, zero npm dependencies, deployed to Cloudflare Pages. Four languages (EN/RU/TR/PL), each language a real indexable URL rather than a client-side toggle, so 5 page types × 4 languages = 20 HTML files. Written together with Claude Code.

I have a professional translation background, so my bar for "done" here was a genuinely correct multilingual site, not a page that renders. That bar is the only reason the rest of this happened — nothing below was surfaced by the agent on its own.

The first bug: no single source of truth

The agent put <title>, og:title, and the JSON-LD name into each of those 20 files by hand, as literal strings, rather than deriving them from one place. That works right up until you update 19 files and miss one.

I caught it by re-running the site against an old GEO/AEO audit checklist I had lying around, written for a completely unrelated niche (health, not real estate) and used purely as a generic methodology pass — hreflang, canonicals, structured data. The second listing's Polish version had different wording in its title and description than the other three languages. Not a typo: drift. Individually harmless, collectively the exact failure a site that advertises itself as multilingual cannot afford.

Worth noting what didn't happen: reference material of mine describing the practices I wanted — zero dependencies, one source of truth for data, structured data over keyword stuffing — was sitting in the working environment the whole time. None of it got applied unprompted. Every item had to be asked for explicitly, one at a time. Being available in context is not the same as being pulled forward.

The fix, and why it isn't Hugo

The obvious objection first: this is a solved problem, and Eleventy, Hugo, Jinja, or any templating layer solves it out of the box. True. I didn't use one, deliberately.

Adopting an SSG here means moving the entire page body — layout, listing copy, gallery markup, four languages of it — into a template system, to fix a problem that lives in roughly 15 lines of <head>. The migration is the whole site; the bug is the header. So instead: build/seo-data.js holds title, meta description, Open Graph, hreflang, and JSON-LD for every page in one place, and build/generate-seo.js injects it into each file between  /  markers. Everything outside those markers is never touched — the HTML stays hand-written HTML, editable without knowing the generator exists. Plain Node, no dependencies. --check verifies without writing, run before deploy.

That closed the drift class structurally. There's no second copy of the string left anywhere for me or the agent to forget.

Standalone, genericized version with an example data file, if you want the code rather than the description: https://github.com/sergei-swh/seo-generator

The second bug: the tool built to stop looking

Then I tested adding a fifth language — German — to see what the generator did with it.

Adding "de" to the language list without the matching paths / perLang / homeLabel data didn't error. The hreflang builder loops over every configured language for every page, found no path for German, and wrote href="https://girne-apartment-sale.comundefined" into all 20 existing pages. Pages that were correct a minute earlier. And --check dutifully reported: out of date. Same string as any ordinary pending edit.

The fix was a validateData() pass that runs before anything is written and fails loudly with an explicit list of what's missing. But the lesson generalizes past this one script: if your verification step reports "different from expected" without a notion of how different, it is a diff, not a check. Mine was a diff pretending to be a check from the moment I wrote it, and I only found out because I went poking at a tool I had specifically built so I could stop poking.

Limits

I didn't run this at max capability — Sonnet 5, reasoning effort medium, not higher — so none of this is a claim about what these agents do at their best, or in general. It's what happened in this setup, starting from an existing foundation rather than a cold start.

What I'd take from it: an AI agent will reliably produce something that works, and it optimizes hardest for the layer you can see. The failure modes live one layer down, in duplication it introduces because duplication is locally cheaper than structure, and they surface as drift rather than as errors. Nothing about that is exotic — it's the same failure mode as any copy-paste — but it arrives faster and across more files than a human would manage, and it doesn't get flagged, because from the inside every individual file looks fine.

The site is still here and growing: girne-apartment-sale.com. The generator from this post is open source: seo-generator on GitHub.