Internationalization and Localization Debt

Why Retrofitting Costs So Much More

Most technical debt is local. A bad module can be rewritten without touching the rest of the system. Internationalization debt is different because it is not a module, it is an assumption, and the assumption was made independently in every file anyone ever wrote. Externalizing strings is not a refactor, it is an archaeological survey of the entire codebase.

The classic worked example is the humble user-visible string. Here it is in the form it takes in almost every codebase that has never shipped a second language.

// Somewhere in a React component
if (cart.items.length === 0) {
    return <EmptyState title="Your cart is empty" cta="Start shopping" />;
}

// Somewhere in a service
throw new Error("Payment declined. Please try another card.");

// Somewhere in an email template
subject: "Your order has shipped!",

// Somewhere in a stored procedure
SET @status_label = 'Awaiting fulfilment';

// Somewhere in a CSV export header
writeHeader(["Order date", "Customer", "Total"]);

Five strings, five layers, five different people, five different eras of the codebase. A greenfield project with i18n in place from day one pays a small, constant tax: every string goes through a translation function instead of being typed inline. A retrofit pays that tax retroactively for every string that already exists, plus the cost of finding them, plus the cost of deciding which ones are actually user-visible, plus the cost of the ones you miss. And you will miss some, because a string in a database column, a string in an email subject, and a string in a chart legend do not look alike to a search tool.

That is only the first layer. Underneath the strings sit the structural assumptions: that a sentence can be assembled from parts, that a quantity is either one or not one, that a date looks like month-slash-day-slash-year, that text runs left to right, that a name has a first part and a last part, that a postal address has a state. Those assumptions are not in a resource file. They are in the logic, and the only way to find them is to go looking.

Concatenation Debt: The Most Damaging Mistake

Building a sentence by joining fragments is the single most common and most damaging i18n mistake, and it survives the first round of remediation because it looks like it has already been fixed. The strings are externalized. They go through the translation function. It is still broken.

// Externalized, and still unusable
const message = t("delete.prefix")      // "Delete "
    + count + " "
    + (count === 1 ? t("file.one") : t("file.many"))   // "file" / "files"
    + t("delete.suffix");                              // "?"

A translator sees four disconnected fragments and no sentence. They cannot reorder them, because the order is in your code, not in the resource file. They cannot decline the noun, because they do not know what precedes it. They cannot change the verb form, because the verb is in a different key. Languages with different word order, with grammatical case, or that place the number after the noun cannot be expressed at all in this structure. The output is not merely awkward, it is often ungrammatical in a way that reads as machine-generated.

The fix is to make the whole sentence one message with named placeholders, and let the message format handle the variation. ICU MessageFormat is the standard notation, supported by most modern i18n libraries.

// en.json - one key, one complete sentence, placeholders named
{
  "delete.confirm": "{count, plural, one {Delete # file?} other {Delete # files?}}",
  "greeting.welcome": "Welcome back, {name}. You last signed in on {lastSeen, date, long}."
}

Pluralization and Grammatical Gender

English has two plural forms, so English-speaking developers write two-branch logic, and that logic is wrong for most of the world.

// Correct for English. Wrong for the majority of locales.
const label = count === 1 ? "1 message" : `${count} messages`;

Unicode CLDR, in its Plural Rules specification, defines six plural categories that a language may use: zero, one, two, few, many, and other. Only other is required. Every language maps its numbers onto some subset of those six, and the category names are mnemonics rather than literal number sets, so you cannot reason about them from English intuition.

The CLDR Language Plural Rules chart makes the spread concrete. Arabic lists all six categories, with few covering numbers where n modulo 100 falls between 3 and 10, and many covering 11 to 99. Polish and Russian each list four categories: one, few, many, and other. A two-branch conditional cannot express any of that, and no amount of clever translation can rescue it after the fact, because the branch was decided in code before the translator ever saw the string.

// en.json
{ "inbox.count": "{count, plural, one {# message} other {# messages}}" }

// pl.json - four categories, supplied by the translator, not by your code
{ "inbox.count": "{count, plural, one {# wiadomosc} few {# wiadomosci} many {# wiadomosci} other {# wiadomosci}}" }

Grammatical gender is the same problem in a different coat. A sentence that refers to a person, or that describes an object, may need different articles, adjective endings, or verb forms depending on gender, and that information exists in your data model rather than in the string. ICU handles it with a select clause, which lets the translator decide how many branches their language needs.

{
  "invite.sent": "{gender, select, female {She has been invited} male {He has been invited} other {They have been invited}}"
}

The practical rule is that anything varying with a number or with an attribute of a person or object must be expressed as a single message with that variable declared, so that the translator controls the branching. The moment your code decides which branch to render, you have hardcoded English grammar into your application logic.

Text Expansion and the UI Debt It Creates

Translated text is usually longer than the English it came from, and the shorter the original, the worse the ratio. W3C's article Text size in translation reproduces IBM's published expansion table for English translated into European languages: a string of 10 characters or fewer can expand to 200-300% of its original length, 11 to 20 characters to 180-200%, and text over 70 characters to about 130%.

Read that distribution carefully, because it inverts the intuition. The worst case is not the paragraph, it is the button label. Buttons, menu items, table headers, tab labels, and form field labels are exactly the shortest strings in your product, and they are also the elements most likely to sit in a fixed-width container. German and Finnish are the usual cautionary examples in English-language products, both because compounding produces long single words that cannot be broken across lines and because the base expansion is substantial.

/* Debt: three assumptions, all of them about English */
.btn-primary {
    width: 120px;              /* the English label happened to fit */
    white-space: nowrap;       /* so a longer one cannot wrap */
    overflow: hidden;          /* so it silently disappears instead */
}

/* Resilient: intrinsic sizing, wrapping allowed, no clipping */
.btn-primary {
    min-width: 7.5rem;
    padding-inline: 1rem;
    white-space: normal;
    overflow-wrap: break-word;
    hyphens: auto;
}

The associated debt is not only visual. A layout that clips silently is a layout that hides its own failures, so the bug reaches production and gets reported by a customer in a market where nobody on the team reads the language. Pseudo-localization is the standard defence: build a locale that mechanically lengthens every string and wraps it in markers, then browse the product in it. Every truncated label and every layout break shows up before a translator is ever engaged, and it costs nothing per release.

// Pseudo-locale: catch expansion and hardcoded-string bugs with zero translators
function pseudo(s) {
    return "[!! " + s + " " + "x".repeat(Math.ceil(s.length * 0.4)) + " !!]";
}
// Any text on screen NOT wrapped in [!! !!] is a hardcoded string.
// Any text that is clipped or wraps badly is an expansion bug.

Bidirectional Text and LTR-Only Layouts

Supporting a right-to-left script such as Arabic or Hebrew is not a translation task, it is a layout task. The entire interface mirrors: navigation moves to the right, icons that imply direction flip, progress runs the other way, and the reading order of columns reverses. A stylesheet written entirely in physical directions - left, right, margin-left, text-align: left, border-left - encodes the assumption in every rule.

/* Physical properties: mirroring means duplicating every rule */
.card {
    margin-left: 1rem;
    border-left: 4px solid;
    text-align: left;
    padding-right: 2rem;
}

/* Logical properties: mirroring is automatic when dir="rtl" is set */
.card {
    margin-inline-start: 1rem;
    border-inline-start: 4px solid;
    text-align: start;
    padding-inline-end: 2rem;
}

The retrofit cost here is proportional to the size of your stylesheet, which is why the cheap moment to fix it is now, in a codebase that may never ship an RTL locale. Logical properties cost nothing extra in a left-to-right layout and are supported across current browsers; adopting them is a lint rule and a find-and-replace, not a project. Doing it after the fact means auditing every rule in a stylesheet that has already accumulated its own UX and design debt.

Bidirectional text has a second, subtler failure: mixed-direction content. A right-to-left sentence containing a Latin product code, a URL, or a number gets reordered by the Unicode bidirectional algorithm, and interpolating a user-supplied value into a translated string without isolating it can visibly scramble the surrounding text. Isolate interpolated values with the appropriate markup or formatting characters rather than assuming direction is uniform within a string.

Encoding, Sorting, and Collation Debt

Encoding debt is the oldest category here and the easiest to eliminate. The WHATWG Encoding Standard states that authors must use the UTF-8 encoding and must use its ASCII case-insensitive "utf-8" label to identify it. There is no remaining debate about the target; the debt is entirely in the systems that predate the decision.

The failures are familiar. A database column declared with a legacy single-byte character set truncates or mangles anything outside it. A connection that negotiates a different encoding than the storage layer produces the classic double-encoded artifacts where one accented character becomes two nonsense ones. In MySQL specifically, the historical utf8 character set stores at most three bytes per character, so it cannot represent any character outside the Basic Multilingual Plane; utf8mb4 is the one that actually holds all of Unicode, including emoji and the less common CJK extension characters. Fixing this after the fact means a migration in which some data is already corrupted and unrecoverable, which is why the encoding audit belongs early.

Sorting is the part everyone forgets. A default sort on a list of names is almost always a sort by code point, which is not alphabetical order in any language, including English once accented characters appear.

// Sorts by UTF-16 code unit. Uppercase before lowercase.
// Accented characters land after "z". Not alphabetical anywhere.
names.sort();

// Locale-aware collation
const collator = new Intl.Collator(locale, {
    sensitivity: "base",       // treat accent and case differences as equal
    numeric: true,             // "item 2" sorts before "item 10"
});
names.sort(collator.compare);

Collation is genuinely locale-specific, not merely language-specific: the same character can sort differently in two languages that both use it, and some languages treat a two-character sequence as a single letter for sorting purposes. This matters most where sort order is load-bearing - paginated directories, alphabetical indexes, and anything a user scans to find a known entry. It also matters in the database, because sorting in the application and sorting in SQL will disagree unless the column collation matches, and a paginated list sorted inconsistently across layers will drop and duplicate rows between pages.

Translation-Management Debt

Once the strings are externalized, a second debt begins accumulating in the resource files themselves. Nobody notices it because resource files are not code and nobody reviews them.

All four of these are gateable, and the gate is cheap relative to what it prevents. Wire it into the same pipeline that runs your other build checks, and treat a failure the same way you treat a failing test rather than as a warning to be triaged later. Broader guidance on making checks like this stick lives in testing strategies.

// scripts/check-i18n.js - run in CI, fail the build
const used    = scanSourceForKeys("src/**/*.{js,jsx,ts,tsx}");  // t("...") call sites
const defined = loadCatalog("locales/en.json");
const locales = loadAllLocales("locales/*.json");

fail(diff(used, defined),      "keys used in code but missing from the base catalog");
fail(diff(defined, used),      "keys in the catalog that no code references (orphans)");

for (const [tag, catalog] of locales) {
    fail(diff(defined, catalog), `${tag}: untranslated keys`);
    fail(staleAgainstSource(catalog, defined),
                                 `${tag}: source string changed since this was translated`);
    fail(pluralCategoriesMissing(catalog, tag),
                                 `${tag}: plural message is missing a required CLDR category`);
}

// The gate that stops regression: no user-visible literal outside the catalog
fail(findHardcodedUserStrings("src/**/*.{jsx,tsx}"),
     "hardcoded user-visible strings - wrap them in t()");

Locale-Specific Business Logic in Presentation Code

The last structural debt is the one that is hardest to unpick, because it is not about language at all. Market-specific rules - tax treatment, required consent, retention periods, invoice fields, supported payment methods - get implemented where they were first noticed, which is usually the component that renders them.

// Presentation code making tax, legal, and shipping decisions
function CheckoutSummary({ locale, order }) {
    if (locale === "en-US") {
        return <Summary tax={order.subtotal * 0.0825} showState />;
    }
    if (locale.startsWith("de")) {
        return <Summary tax={order.subtotal * 0.19} showVatId showWithdrawalNotice />;
    }
    return <Summary tax={0} />;
}

Three separate mistakes are compounded here. Language is being used as a proxy for jurisdiction, which is wrong the moment someone in one country prefers a different interface language. Tax rates are hardcoded in a React component, where nothing tests them and nobody with tax knowledge will ever read them. And each new market means another branch in a function that renders a summary.

Separate the three concepts and the debt dissolves: language is what the interface is written in, region is what the formatting conventions follow, and jurisdiction is what the business rules follow. They correlate but they are not the same field, and conflating them is the reason so many products cannot serve a French speaker in Canada or an English speaker in Germany. Push jurisdiction rules into a configured, tested policy layer with an owner, and leave the component rendering whatever that layer returns. Where these rules are legally mandated, they are compliance debt as much as i18n debt.