The message catalog is where all translatable text lives — one structured file per locale, managed by next-intl. It’s the backbone that makes the whole bilingual system maintainable.

TOOLnext-intl FORMATJSON catalog PERLocale STRUCTURENested

E01.1 · THE CATALOG

All text, one place.

Every user-facing string lives in the catalog, keyed and grouped. The English and Chinese catalogs mirror each other key-for-key, so any string can be found in both.

E01.2 · FORMAT

Structured JSON.

Catalogs are JSON, supporting interpolation, plurals and rich formatting via ICU syntax. The format is standard, so tooling and translators both understand it.

E01.3 · PER LOCALE

One per language.

Each locale has its own catalog file, loaded on demand. Adding a language means adding a file — not touching the components that consume the keys.

E01.4 · STRUCTURE

Nested, by feature.

Keys nest by feature and screen, matching the key-structure convention. The structure makes a large catalog navigable and gives translators context from the path.

A single hardcoded string is a hole in the localization system — text that ships in English no matter the locale. Externalization is the discipline, enforced by lint, that keeps every string in the catalog.

RULENo hardcode LINTEnforced ALLStrings FAILSThe build

E02.1 · THE RULE

Zero strings in code.

No user-facing text is written inline in a component — it’s always a key into the catalog. One hardcoded label is one piece of the UI that can never be Chinese.

E02.2 · LINT ENFORCEMENT

Caught by the machine.

A lint rule detects literal strings in JSX and fails them. Enforcement is automated because relying on reviewers to spot every hardcoded word is a losing game.

E02.3 · COVERAGE

Including the edges.

Externalization covers the easy strings and the forgotten ones — errors, alts, aria-labels, emails, metadata. The edges are exactly where hardcoded English usually hides.

E02.4 · BUILD GATE

Fails, not ships.

A hardcoded string fails the build rather than shipping silently. Making it a hard gate means the system can’t quietly regress one careless commit at a time.

If a Chinese translation is missing for a key, the user must never see a blank or a raw key name. The fallback chain ensures something sensible always renders — and the gap gets logged.

CHAINZH → EN MISSINGFalls back NEVERBlank LOGFlagged

E03.1 · THE CHAIN

A defined order.

The fallback chain is explicit: a missing Chinese string falls back to English, never to nothing. The chain is configured once and applied everywhere.

E03.2 · MISSING KEYS

Graceful, not broken.

A missing key renders the English text — imperfect, but readable — rather than a broken UI. Users get a working product even mid-translation.

E03.3 · NEVER BLANK

No raw keys, no gaps.

The one thing that must never happen is a raw key (home.hero.title) or an empty space showing to a user. The fallback guarantees real words always render.

E03.4 · LOGGING

Fallback is a flag.

Every fallback is logged as a missing-translation flag, so gaps surface in QA and get filled. A graceful fallback shouldn’t hide that work remains.

The same phrases recur across a product. Translation memory stores every approved translation and offers it back when the same or similar text appears — raising consistency and cutting cost.

TMDatabase REUSEMatches CONSISTENCYUp COSTDown

E04.1 · WHAT TM IS

A memory of every translation.

Translation memory is a database of source-target pairs from past work. When a string matches one already translated, the TM proposes the approved version automatically.

E04.2 · REUSE

Exact and fuzzy.

TM offers exact matches and fuzzy ones (similar but not identical), so even near-repeats start from a known-good translation rather than scratch.

E04.3 · CONSISTENCY

Same phrase, same words.

Because the same source reuses the same translation, recurring phrases stay consistent across the whole product — reinforcing the termbase at the sentence level.

E04.4 · COST

Less to translate.

Reuse means translators bill for fewer new words, and updates touch only what changed. TM turns translation from a recurring full cost into an incremental one.

Pseudo-localization replaces text with a longer, accented fake version before real translation exists. It surfaces hardcoded strings and layout overflow early — catching localization bugs in development, not production.

METHODPseudo-locale CATCHESHardcode · overflow WHENCI EARLYPre-translation

E05.1 · WHAT IT IS

A deliberately ugly locale.

Pseudo-localization generates a fake locale where text is accented and padded — “Settings” becomes “[Ŝeťťîńgş…]”. Still readable, but obviously transformed.

E05.2 · WHAT IT CATCHES

Two bugs at once.

Untransformed text in the pseudo-locale is hardcoded (a bug); text that overflows its container reveals a layout that won’t survive a longer language. Both surface instantly.

E05.3 · IN CI

Automated pass.

The pseudo-locale runs in CI and visual tests, so regressions are caught on every change — not discovered when the first real translation arrives.

E05.4 · EARLY

Before translators.

Because it needs no real translation, pseudo-localization tests readiness from day one. Layouts are proven localization-safe long before a translator is engaged.