Most localization bugs are found by translators or, worse, by customers: a button label cut off in German, a sentence assembled in English word order, a hardcoded string nobody extracted. Pseudo-localization finds all of them on day one, before you pay for a single translation. This guide shows how it works, how to build a pseudo-locale for an ICU-based project in about eighty lines of JavaScript, and how to turn it into an automated check in CI.
Pseudo-localization generates a fake locale from your source strings. Each string stays readable to you, but it is transformed to stress your UI the way real translations will:
"Save changes" -> "[Šáṽé çĥáñĝéš~~~~~]"
"Hello, {name}!" -> "[Ĥéļļö, {name}!~~]"
"{count, plural, one {# file} other {# files}}"
-> "[{count, plural, one {# ƒîļé} other {# ƒîļéš}}~~~~~~~]"Three transformations do the work:
It is not a new idea. Microsoft has shipped pseudo-locales (qps-ploc, qps-ploca, and the mirrored qps-plocm) in Windows for years, Android has built-in en-XA and ar-XB pseudo-locales, and Xcode offers accented, double-length, right-to-left, and bounded-string pseudolanguages. On the web, most teams simply never set it up.
| What you see | The bug |
|---|---|
Settings in plain English |
Hardcoded string, never extracted to a translation file |
[Šáṽé çĥá with no closing bracket |
Fixed-width container truncating text |
[Ŷöû ĥáṽé] 3 [ñéŵ ɱéššáĝéš] |
Concatenation: the sentence is built from fragments, so translators cannot reorder it |
| Text overlapping icons or wrapping badly | Layout assumes English string lengths |
Boxes or é instead of é |
Font missing glyphs, or an encoding bug somewhere in the pipeline |
{name} visible on screen |
Placeholder not interpolated, or broken during transformation |
Concatenation is the most valuable catch. It is invisible in English, impossible for a translator to fix, and expensive to refactor once many locales depend on the fragments. The fix is to move the whole sentence into one message with placeholders, which our ICU MessageFormat guide covers in detail.
Short strings expand the most, which is exactly where UI breaks: buttons, tabs, and badges. The commonly cited IBM globalization guideline for English source text, as reproduced by the W3C:
| English length | Typical expansion |
|---|---|
| Up to 10 characters | 100% to 200% |
| 11 to 20 characters | 80% to 100% |
| 21 to 30 characters | 60% to 80% |
| 31 to 50 characters | 40% to 60% |
| 51 to 70 characters | 31% to 40% |
| Over 70 characters | About 30% |
"Save" becomes "Speichern" in German. "Share" becomes "Compartilhar" in Portuguese. A flat 40% padding is a reasonable everyday default; switch to a double-length mode before a release to stress your shortest labels.
Expansion is not only horizontal. Thai, Hindi, and Arabic scripts need more vertical space for stacked marks, so a fixed height with overflow: hidden clips them even when the width is fine. CJK languages are usually shorter in characters but wider per character.
The tricky part is not accenting letters. It is not accenting the things that must survive untouched: placeholder names, plural and select keywords, and rich-text tags. Transform {count, plural, one {# file}} naively and you get {çöûñţ, þļûŕáļ, ...}, which breaks every message at runtime.
This script walks each ICU message, transforms only literal text (including the text inside plural and select branches), and writes a new locale file:
// scripts/pseudo-localize.mjs
import { readFileSync, writeFileSync } from "node:fs";
const ACCENTS = {
a: "á", b: "ƀ", c: "ç", d: "ð", e: "é", f: "ƒ", g: "ĝ", h: "ĥ", i: "î",
j: "ĵ", k: "ķ", l: "ļ", m: "ɱ", n: "ñ", o: "ö", p: "þ", q: "ǫ", r: "ŕ",
s: "š", t: "ţ", u: "û", v: "ṽ", w: "ŵ", x: "ẋ", y: "ý", z: "ž",
A: "Å", B: "Ɓ", C: "Ç", D: "Ð", E: "É", F: "Ƒ", G: "Ĝ", H: "Ĥ", I: "Î",
J: "Ĵ", K: "Ķ", L: "Ļ", M: "Ṁ", N: "Ñ", O: "Ö", P: "Þ", Q: "Ǫ", R: "Ŕ",
S: "Š", T: "Ţ", U: "Û", V: "Ṽ", W: "Ŵ", X: "Ẋ", Y: "Ý", Z: "Ž",
};
const BRANCHING = new Set(["plural", "select", "selectordinal"]);
const transformText = (text) =>
Array.from(text, (ch) => ACCENTS[ch] ?? ch).join("");
// Index of the "}" that closes the "{" at `start`.
function matchingBrace(str, start) {
let depth = 0;
for (let i = start; i < str.length; i++) {
if (str[i] === "{") depth++;
else if (str[i] === "}" && --depth === 0) return i;
}
return str.length;
}
// Transforms literal text but never {placeholders}, keywords, or <tags>.
function transformMessage(msg) {
let out = "";
let i = 0;
while (i < msg.length) {
if (msg[i] === "<" && msg.indexOf(">", i) !== -1) {
const end = msg.indexOf(">", i);
out += msg.slice(i, end + 1);
i = end + 1;
} else if (msg[i] === "{") {
const end = matchingBrace(msg, i);
out += transformArgument(msg.slice(i + 1, end));
i = end + 1;
} else {
out += transformText(msg[i]);
i++;
}
}
return out;
}
// {name} stays as-is; {count, plural, one {...}} recurses into each branch.
function transformArgument(body) {
const [, type] = body.split(",").map((p) => p.trim());
if (!BRANCHING.has(type)) return "{" + body + "}";
const headerEnd = body.indexOf(",", body.indexOf(",") + 1) + 1;
let result = "{" + body.slice(0, headerEnd);
let rest = body.slice(headerEnd);
while (rest.includes("{")) {
const open = rest.indexOf("{");
const close = matchingBrace(rest, open);
result += rest.slice(0, open) + "{" + transformMessage(rest.slice(open + 1, close)) + "}";
rest = rest.slice(close + 1);
}
return result + rest + "}";
}
// Brackets expose truncation and concatenation; ~ padding adds about 40%.
export function pseudoLocalize(message) {
const body = transformMessage(message);
const accented = body.match(/[^\x00-\x7F]/g)?.length ?? 0;
return "[" + body + "~".repeat(Math.ceil(accented * 0.4)) + "]";
}
const walk = (obj) =>
Object.fromEntries(
Object.entries(obj).map(([k, v]) => [k, typeof v === "string" ? pseudoLocalize(v) : walk(v)])
);
const [input = "messages/en.json", output = "messages/en-XA.json"] = process.argv.slice(2);
writeFileSync(output, JSON.stringify(walk(JSON.parse(readFileSync(input, "utf8"))), null, 2) + "\n");Run it against your source file:
node scripts/pseudo-localize.mjs messages/en.json messages/en-XA.jsonGiven this input:
{
"nav": { "settings": "Settings" },
"greeting": "Hello, {name}!",
"files": "{count, plural, =0 {No files} one {# file} other {# files}}",
"invite": "{inviter} invited you to <b>{team}</b>."
}You get a file every ICU library will still parse:
{
"nav": { "settings": "[Šéţţîñĝš~~~~]" },
"greeting": "[Ĥéļļö, {name}!~~]",
"files": "[{count, plural, =0 {Ñö ƒîļéš} one {# ƒîļé} other {# ƒîļéš}}~~~~~~~]",
"invite": "[{inviter} îñṽîţéð ýöû ţö <b>{team}</b>.~~~~~]"
}
The script deliberately ignores ICU apostrophe escaping ('{') to stay short. If your messages use it, or you want more modes, the FormatJS CLI can generate pseudo-locales from its full ICU parser with formatjs compile --ast --pseudo-locale en-XA.
XA through XZ are private-use region codes in ISO 3166, so en-XA is a valid BCP 47 tag that will never collide with a real market. Intl formatters fall back to en for it, so dates and numbers still render. It also matches Android's convention. Our locale codes guide explains how tags and fallback work.
Register the pseudo-locale only outside production. With next-intl, for example:
// i18n/routing.ts
import { defineRouting } from "next-intl/routing";
const locales = ["en", "de", "ja"];
if (process.env.NODE_ENV !== "production") locales.push("en-XA");
export const routing = defineRouting({ locales, defaultLocale: "en" });
Then visit /en-XA/ and click through your main flows. Ten minutes on the pricing page, onboarding, settings, and transactional emails usually surfaces more localization bugs than a full translation round. If you are setting up next-intl from scratch, our step-by-step Next.js i18n guide covers the routing setup.
Add a script so nobody has to remember the command:
{
"scripts": {
"i18n:pseudo": "node scripts/pseudo-localize.mjs messages/en.json messages/en-XA.json"
}
}Visual review finds layout problems. Hardcoded strings can be caught automatically: in the pseudo-locale, any visible text containing plain ASCII words outside a bracketed string was not translated. A Playwright test can scan the DOM for them:
// e2e/pseudo-locale.spec.ts
import { test, expect } from "@playwright/test";
const PAGES = ["/en-XA/", "/en-XA/pricing", "/en-XA/settings"];
for (const path of PAGES) {
test(`no untranslated text on ${path}`, async ({ page }) => {
await page.goto(path);
const leaks = await page.evaluate(() => {
const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
const found: string[] = [];
while (walker.nextNode()) {
const node = walker.currentNode;
if (node.parentElement?.closest("script, style, code, [data-i18n-ignore]")) continue;
// Remove bracketed strings, including ones split across elements.
const outside = (node.textContent ?? "").replace(/\[[^\]]*(\]|$)|^[^\[]*\]/g, "");
if (/[A-Za-z]{3,}/.test(outside)) found.push(outside.trim());
}
return found;
});
expect(leaks).toEqual([]);
});
}Two tips for keeping this check reliable:
data-i18n-ignore, which also documents the decision for the next developer.Add a screenshot test on the same pages with your existing visual regression tooling and you will see truncation and overflow in pull requests instead of in bug reports from Germany.
An accented pseudo-locale tests length and extraction. It does not test direction. For that, render a second pseudo-locale with dir="rtl" on the <html> element, or just run document.documentElement.dir = "rtl" in your browser console. Icons that point the wrong way and margins on the wrong side show up immediately. Our RTL and CSS logical properties guide covers the fixes.
Pseudo-localization is a testing technique that generates a fake locale from your source strings by adding accents, padding, and brackets. The text stays readable, but it exposes hardcoded strings, truncation, concatenation, and encoding problems before real translation begins.
As early as possible and continuously after that. Running it before your first translation round is the cheapest point to fix layout and extraction bugs, and running it in CI prevents new hardcoded strings from being merged.
It depends on string length. Short labels of up to ten characters can double or triple in length, while long paragraphs typically grow by about 30%. German, Finnish, and Portuguese commonly run longer than English.
No. It finds engineering problems such as extraction, layout, and concatenation, but it cannot judge translation quality, tone, or cultural fit. Use it to make the code ready, then review real translations in context.
Use a private-use region such as en-XA, the convention Android uses. Codes from XA to XZ are reserved for private use, so they will never conflict with a real country, and Intl formatters fall back to the base language.
Generate an accented, padded, bracketed copy of your source locale, add it to your app in development, and click through your key screens. Then make it a CI check so hardcoded strings never come back. It costs an afternoon and saves you from discovering layout bugs one language at a time.
Once your UI is ready for real languages, Babelize generates the translations directly in your repository and keeps every locale file in sync as your source strings change.
--- - [All articles](https://www.babelize.co/blogs)