Eight languages, one developer: an i18n setup that stays correct

Design for a site in eight languages with one maintainer: next-intl routing, ICU plurals, CI checks for broken messages, stale-translation tracking, hreflang.

Published

Updated

Reading time

13 min

Take a product site that has to exist in English, Italian, German, French, Spanish, Polish, Arabic and Japanese, and has one developer to build and maintain it. The eight are a deliberate spread: a source language, two languages with simple plural rules, two with richer ones, a right-to-left script and a language written without spaces between words. The system below is a design chosen for that spread. My own site also ships eight languages, a different set with no right-to-left script, so where I describe what I did or got wrong, I say so. The design goes from requirements to the places where the design breaks under load, failure and change, because those are where an eight-language site goes wrong.

The code uses Next.js 16 with next-intl. The ideas hold for any framework; only the routing snippets are specific.

What the design has to guarantee#

Rendering a translated string is the easy part. With one maintainer, five properties carry the design:

  • One source of truth. English is written by hand. The other seven files are derived from it and can be regenerated or reviewed against it.
  • Structural errors fail the build. A missing key, a renamed placeholder or a broken tag is detectable without speaking the language, so a machine should detect it.
  • Staleness is visible. When the English text of a key changes, every translation of that key is now suspect, and the repository should say so.
  • A new locale is a configuration change. One list, read by routing, metadata and the sitemap.
  • Search engines can tell which page is for whom, and no locale looks broken to a human.

On a large-scale social platform I'm building, the rule underneath all five is that every new or changed user-visible string ships in every catalog in the same pull request, or it does not merge. Deferred translation is invisible work with no ticket and no failing test, and by the time a user meets a raw key the gap is many strings wide, each needing context I had loaded for free when I wrote the English. I also built the pipeline before launch rather than later, because the first non-English language is the real bill: extraction touches every component and collides with feature work in flight, while each further language is one more file. I preferred to pay it while the codebase was small.

Each stage can send a change back to review; the lock file is what notices that English moved on.

One URL prefix per language#

Every locale gets its own prefix (/it/..., /de/...). Separate URLs are what make hreflang possible and let each language be indexed, linked and shared on its own. With next-intl the locale list lives in one file:

src/i18n/routing.tsts
import { defineRouting } from "next-intl/routing";
 
export const routing = defineRouting({
  locales: ["en", "it", "de", "fr", "es", "pl", "ar", "ja"],
  defaultLocale: "en",
});

The code that negotiates the locale on the first visit is a request interceptor. In Next.js 16 the middleware file convention is deprecated and renamed proxy (the Next.js docs ship a codemod, npx @next/codemod@canary middleware-to-proxy .), and next-intl's routing documentation matches: on Next.js 16 the file is proxy.ts, and its default export is createMiddleware(routing) imported from next-intl/middleware. The rest of the request wiring changes between versions, so follow the next-intl routing setup for the version you install.

Do not redirect by IP address. Language is a browser preference, not a location, and an automatic redirect that cannot be undone traps both people and crawlers. The Accept-Language header on the first visit plus a visible language switcher is enough.

Messages that carry their own grammar#

Concatenating strings in code is the root of most translation bugs, because word order and grammar differ between languages. ICU message syntax moves the variation into the message where the translator can see and change it. The next-intl messages guide covers interpolation, plural, select and rich-text tags:

messages/en.jsonjson
{
  "cart": {
    "items": "{count, plural, =0 {Your cart is empty} one {# item} other {# items}}",
    "total": "Total: {amount}"
  },
  "home": {
    "terms": "Read the <link>terms</link> first.",
    "greet": "Hello {name}"
  }
}

The Polish version needs branches English does not have, and the translator is free to add them:

messages/pl.jsonjson
{
  "cart": {
    "items": "{count, plural, =0 {Koszyk jest pusty} one {# produkt} few {# produkty} many {# produktów} other {# produktu}}",
    "total": "Razem: {amount}"
  },
  "home": {
    "terms": "Przeczytaj <link>regulamin</link>.",
    "greet": "Cześć {name}"
  }
}

Which branches a language uses comes from the runtime, via new Intl.PluralRules(locale).resolvedOptions().pluralCategories. Running it for the eight locales gives:

LocalePlural categories reported by Node
en, deone, other
it, fr, esone, many, other
plone, few, many, other
arzero, one, two, few, many, other
jaother

Arabic uses all six, which is why a message written for English plurals is wrong there and not merely awkward. Italian, French and Spanish also report many; in the CLDR data that category applies to large compact numbers such as millions, so a message about ordinary counts does not need a many branch in those languages. other is required everywhere. A missing branch does not error: it falls back to other and produces grammatically wrong text, so the reviewer's rule for Polish and Arabic is to read the category list and confirm each branch exists.

Numbers, currencies, dates and lists go through Intl, never hand-built strings. In Node, new Intl.NumberFormat("de", { style: "currency", currency: "EUR" }).format(1234.5) gives 1.234,50 €, new Intl.NumberFormat("ar-EG").format(1234.5) gives Arabic-Indic digits, and a long ja date comes out as 2026年10月17日. Passing a locale is cheaper than reasoning about any of these rules.

Catching structural errors without speaking the language#

A plain Node script compares every locale file to English for missing keys, unused keys and placeholder or tag mismatches, and exits non-zero on any of them:

scripts/check-messages.mjsjs
import { readdirSync, readFileSync } from "node:fs";
import { join } from "node:path";
 
const dir = process.argv[2] ?? "messages";
const source = "en";
 
const flatten = (obj, prefix = "") =>
  Object.entries(obj).flatMap(([k, v]) =>
    typeof v === "string" ? [[prefix + k, v]] : flatten(v, `${prefix}${k}.`),
  );
 
// Argument names ({name}, {count, plural, ...}) and rich-text tags (<link>), as a sorted set.
// This is a regex, not an ICU parser. The lookbehind skips branch bodies of plural
// selectors ("other {Items}", "=0 {...}"), which would otherwise look like arguments.
// It does NOT skip `select` branches ("male {Mr}"): if you use select with bare-word
// branches, switch to @formatjs/icu-messageformat-parser.
const ARG = /(?<!(?:=\d+|zero|one|two|few|many|other)\s*)\{\s*([A-Za-z0-9_]+)\s*[,}]/g;
const placeholders = (msg) => {
  const args = [...msg.matchAll(ARG)].map((m) => m[1]);
  const tags = [...msg.matchAll(/<([A-Za-z0-9_]+)>/g)].map((m) => `<${m[1]}>`);
  return [...new Set([...args, ...tags])].sort().join(" ");
};
 
const load = (loc) =>
  new Map(flatten(JSON.parse(readFileSync(join(dir, `${loc}.json`), "utf8"))));
const locales = readdirSync(dir)
  .filter((f) => f.endsWith(".json") && !f.includes("lock"))
  .map((f) => f.slice(0, -5));
const base = load(source);
let problems = 0;
 
for (const loc of locales.filter((l) => l !== source)) {
  const target = load(loc);
  for (const [key, msg] of base) {
    if (!target.has(key)) {
      console.error(`${loc}: missing ${key}`);
      problems++;
      continue;
    }
    if (placeholders(msg) !== placeholders(target.get(key))) {
      console.error(
        `${loc}: placeholder mismatch in ${key}: [${placeholders(msg)}] vs [${placeholders(target.get(key))}]`,
      );
      problems++;
    }
  }
  for (const key of target.keys()) {
    if (!base.has(key)) {
      console.error(`${loc}: unused ${key}`);
      problems++;
    }
  }
}
process.exit(problems ? 1 : 0);

Given a German file in which {amount} was renamed to {sum}, one key is absent and one is left over after a rename, it prints exactly those three problems:

texttext
de: placeholder mismatch in cart.total: [amount] vs [sum]
de: missing home.greet
de: unused home.extra

The same file is the place to add the rule from the previous section, that the Arabic and Polish plural messages contain few and many, if you want the reviewer's check enforced mechanically.

A limit I know about in my own setup: my parity tests only walk the locales wired into the language switcher. Catalogs that are translated and committed but not yet selectable are invisible to CI, so a missing key in one fails nothing, and the debt would arrive all at once on the day the switcher exposes that language. I treat staged catalogs exactly like live ones in every pull request. Green CI only tells me the tested subset is consistent.

Knowing which translations have gone stale#

The checker proves a translation has the right shape. It cannot know the English text changed after the German was written. A second small script closes that gap with a lock file that records, per locale and key, a hash of the English text that was reviewed:

scripts/i18n-status.mjsjs
import { createHash } from "node:crypto";
import { existsSync, readFileSync, writeFileSync } from "node:fs";
 
const dir = "messages";
const lockFile = `${dir}/reviewed.lock.json`;
const [cmd, loc] = process.argv.slice(2);
 
const flatten = (obj, prefix = "") =>
  Object.entries(obj).flatMap(([k, v]) =>
    typeof v === "string" ? [[prefix + k, v]] : flatten(v, `${prefix}${k}.`),
  );
const load = (l) => new Map(flatten(JSON.parse(readFileSync(`${dir}/${l}.json`, "utf8"))));
const hash = (text) => createHash("sha256").update(text).digest("hex").slice(0, 12);
const lock = existsSync(lockFile) ? JSON.parse(readFileSync(lockFile, "utf8")) : {};
 
const source = load("en");
 
if (cmd === "approve" && loc) {
  // Run after a reviewer signs off a locale: record the English each key was reviewed against.
  lock[loc] = Object.fromEntries([...source].map(([key, text]) => [key, hash(text)]));
  writeFileSync(lockFile, JSON.stringify(lock, null, 2) + "\n");
  console.log(`${loc}: ${source.size} keys marked as reviewed`);
} else {
  let stale = 0;
  for (const [l, reviewed] of Object.entries(lock)) {
    for (const [key, text] of source) {
      if (reviewed[key] !== hash(text)) {
        console.log(`${l}: needs review ${key}`);
        stale++;
      }
    }
  }
  console.log(stale ? `${stale} stale or new keys` : "all reviewed locales are current");
  process.exit(stale ? 1 : 0);
}

After node scripts/i18n-status.mjs approve de, editing cart.total in English and adding a new key makes the status run list both for de and exit 1. The workflow it supports is deliberately plain. English changes in a pull request. The status script lists what is now stale per locale. Someone produces new text for those keys only, by hand, with a translation tool or with a contractor, and a native speaker reviews the locale file's diff in a pull request. The reviewer runs approve, which updates the lock. Which tool produces the draft is a detail this design does not depend on, and re-translating only the stale keys matters more than the tool: translating everything on every run overwrites reviewed text.

Two cautions travel with any external draft service. Do not send personal data or unreleased confidential text to a service whose data-handling terms you have not read, and give translators context (the key path, a short description or a screenshot), because a bare "Post" is a noun in one place and a verb in another.

A locale that is not in the lock file is not reviewed, and the design treats that as a release rule: a locale is added to routing.locales and to the sitemap only once its core pages have been approved.

What search engines need from eight versions#

Google's guidance on localised versions is specific and easy to break:

  • Every version lists itself and every other version, and the links are reciprocal. One-way annotations are ignored.
  • Alternate URLs are fully qualified, including https://.
  • Language codes are ISO 639-1, optionally with an ISO 3166-1 Alpha 2 region. A region alone is not valid.
  • x-default covers visitors whose language matches none of your versions.
  • The annotations can live in HTML link tags, HTTP headers or the sitemap; Google treats them as equivalent, so pick the one that is easiest to maintain.

In Next.js the metadata API produces the HTML form directly: alternates.languages in generateMetadata renders one rel="alternate" link per entry.

src/app/[locale]/page.tsxts
import type { Metadata } from "next";
import { routing } from "@/i18n/routing";
 
const SITE = "https://example.com";
 
export async function generateMetadata({
  params,
}: {
  params: Promise<{ locale: string }>;
}): Promise<Metadata> {
  const { locale } = await params;
  return {
    alternates: {
      canonical: `${SITE}/${locale}`,
      languages: {
        ...Object.fromEntries(routing.locales.map((l) => [l, `${SITE}/${l}`])),
        "x-default": `${SITE}/en`,
      },
    },
  };
}

Because the list comes from routing.locales, adding a ninth locale updates every page's annotations without touching the pages. The sitemap convention accepts the same alternates.languages structure per URL, which keeps the markup out of every page on a large site. A locale that is mostly English under a translated header is worse than no locale, which is one more reason for the release rule above.

Where the layout breaks first#

Two locales decide whether the layout survives, the longest and the right-to-left one, so every new component is checked in that pair.

  • Text expansion. German compounds are the classic stress. I now design every surface to survive roughly 1.5 times the English length: a button sized for "Save" strains at "Speichern" and breaks at "Zapisz zmiany". Buttons and navigation wrap or grow, and text containers never get fixed widths. A pseudo-locale that pads every English string by a fixed percentage lets you test expansion in development without waiting for translations.
  • Right-to-left. Set dir="rtl" on html for Arabic. Use CSS logical properties (margin-inline-start, padding-inline-end, inset-inline) instead of left and right, and mirror directional icons while leaving logos and numerals alone. Keep an explicit list of RTL locales rather than deriving direction at runtime: Intl.Locale exposes direction through getTextInfo() in current Node, but older runtimes used a different property, and an explicit list works everywhere.
  • Fonts. A font must cover every shipped script. Japanese and Arabic need fonts with the right glyphs, and a large CJK font sent to every visitor is expensive, so subset it or serve it only on the locale that needs it.
  • Line breaking. Japanese has no spaces between words, so truncation and wrapping logic that counts on spaces fails there.

A small end-to-end suite that opens the home page and the main form in the longest and the right-to-left locale and fails on horizontal overflow catches most regressions. It fits the staging gate described earlier, and the overflow helper in testing responsive layouts names the offending element.

What breaks as the site grows and changes#

A key is missing at runtime. The framework shows the key, shows nothing or falls back. Falling back to English for secondary text and failing the build for critical flows such as checkout, consent and legal text is the usual split: a mixed-language page is awkward but usable, while a key name on a button is not.

Plural and gender errors survive review. The category check covers structure. Where grammatical gender matters, use select and give the translator the cases rather than a default.

Terminology drifts. The same feature gets three names across screens. A glossary file in the repository, changed only through pull requests, limits it. Mine sits next to the conventions doc, so it is in context whenever strings are written. Register belongs in the same place: German, French, Italian, Spanish and Polish all split formal and informal address, and I chose the informal register once and documented it, since changing it later touches every string in the catalog.

Dates and money. A date formatted in the right language with the wrong time zone is still a bug. Store timestamps in UTC, format in the viewer's zone, and show currency as the amount actually charged.

A late-night copy fix goes straight to a non-English file. Eight locales mean eight places for a change to be forgotten. The design holds only if the English file, the status script and review are the single path, and CI refuses a merge when the status script reports stale keys for an approved locale.

When the whole design is too much#

If the audience is in one country and one language, none of this pays for itself, and one well-written language beats eight uneven ones. If no reviewer you trust exists for a language, leave that language out. And if most of the content is user-generated, translating the interface localises a tool, not the experience; that is a different project.

Share
All articles →

Register a denied Consent Mode v2 default ahead of the AdSense script in Next.js, let a certified CMP send the updates, and check the order in the browser.

12 min