Compact notation: Chinese “万” is not a 3-digit grouping#

This one is especially easy to overlook, because the English-speaking world’s intuition is “one unit every 3 digits”:

1
for (const loc of ["en-US", "zh-CN", "ja-JP", "de-DE"]) {
2
  const f = new Intl.NumberFormat(loc, { notation: "compact" });
3
  console.log(loc, f.format(9999), "|", f.format(1234567), "|", f.format(123456789));
4
}

1
en-US  10K        | 1.2M      | 123M
2
zh-CN  9999       | 1.23 million     | 120 million
3
ja-JP  9999       | 1.23 million     | 120 million
4
de-DE  9999       | 1.2 million  | 123 million

Chinese and Japanese counting units advance by 10⁴ (万, 亿), so zh-CN at 9999 is not abbreviated, and only at 10000 does it become 1万; English, by contrast, abbreviates at 9999 into 10K. In de-DE’s 1,2 Mio., even the decimal point becomes a comma.

In one sentence: for compact formatting in data display, the only correct approach is to hand it to notation: "compact". Any code that says “if > 10000, divide by 10000 and append ‘万’” is wrong for English users and German users alike.

Dates and time zones: the number one source of hydration mismatch#

The same instant 2026-09-28T14:30:00Z, six locale + time zone combinations:

1
en-US  America/New_York   9/28/26, 10:30 AM
2
en-GB  Europe/London      28/09/2026, 15:30
3
de-DE  Europe/Berlin      28.09.26, 16:30
4
zh-CN  Asia/Shanghai      2026/9/28 22:30
5
ja-JP  Asia/Tokyo         2026/09/28 23:30
6
ar-EG  Africa/Cairo       ٢٨‏/٩‏/٢٠٢٦، ٥:٣٠ م

en-US’s 9/28/26 and en-GB’s 28/09/2026 are the same instant—you cannot tell by eye alone which is the month and which is the day. This is why you should never hand-write MM/DD/YYYY concatenation for dates.

Time zones are even trickier. The same piece of code renders the same instant on the server (usually UTC) and in the browser (the user’s local time zone):

1
UTC                  2026年9月28日 14:30:00
2
Asia/Shanghai        2026年9月28日 22:30:00
3
America/Los_Angeles  2026年9月28日 07:30:00

These three literally different strings come from the same Date object. In SSR / SSG scenarios, the server renders 14:30:00, and when the client hydrates it computes 22:30:00, so React throws a classic hydration warning. The next section (Section 8) is dedicated to how to fix it.

Relative time, lists, duration: three things you shouldn’t hand-write#

Almost every project has hand-written these three features, and Intl has ready-made versions of all of them:

1
// Relative time
2
new Intl.RelativeTimeFormat("zh-CN", { numeric: "auto" }).format(-1, "day");  // "yesterday"
3
new Intl.RelativeTimeFormat("en",    { numeric: "auto" }).format(-1, "day");  // "yesterday"
4
new Intl.RelativeTimeFormat("ru",    { numeric: "auto" }).format(3, "hour");  // "через 3 часа"
5

6
// List joining (note that Chinese uses "、" and "and", English uses commas + and, Japanese adds no conjunction)
7
new Intl.ListFormat("zh-CN", { type: "conjunction" }).format(["A", "B", "C"]); // "A, B, and C"
8
new Intl.ListFormat("en",    { type: "conjunction" }).format(["A", "B", "C"]); // "A, B, and C"
9
new Intl.ListFormat("ja",    { type: "conjunction" }).format(["A", "B", "C"]); // "A, B, C"
10

11
// Duration (Intl.DurationFormat has landed in modern runtimes)
12
new Intl.DurationFormat("zh-CN", { style: "long" }).format({ hours: 2, minutes: 30, seconds: 5 });
13
// "2 hours 30 minutes 5 seconds"
14
new Intl.DurationFormat("en-US", { style: "narrow" }).format({ hours: 2, minutes: 30, seconds: 5 });
15
// "2h 30m 5s"

The ListFormat line illustrates the problem best: in Chinese A、B和C, the conjunction “和” appears only before the last item, and the preceding separator is ”、” rather than a comma. Hand-written items.join(", ") looks like “pidgin” in a Chinese interface.

Intl.RelativeTimeFormat’s numeric: "auto" is also worth noting: it turns “-1 day” into “昨天” rather than “1 天前,” and Russian will inflect accordingly (через 3 часа rather than через 3 час).

A Minimal Working Implementation#

Once you know the rules, the implementation isn’t complicated. This 40-line t() below supports interpolation and plurals, and you can run it directly:

1
const CATALOG = {
2
  "zh-CN": { "cart.items": { other: "There are {count} items in the shopping cart" } },
3
  "en-US": { "cart.items": { one:   "{count} item in your cart",
4
                             other: "{count} items in your cart" } },
5
  "ru-RU": { "cart.items": { one:   "В корзине {count} товар",
6
                             few:   "В корзине {count} товара",
7
                             many:  "В корзине {count} товаров",
8
                             other: "В корзине {count} товара" } },
9
};
10

11
function makeT(locale, { strict = true } = {}) {
12
  const pr = new Intl.PluralRules(locale);   // Plural rules: determined by the platform
13
  const nf = new Intl.NumberFormat(locale);  // Number formatting: determined by the platform
14
  const table = CATALOG[locale] ?? {};
15
  return function t(key, params = {}) {
16
    const entry = table[key];
17
    if (entry === undefined) {               // Missing key: fail explicitly, don't silently fall back
18
      if (strict) throw new Error(`[i18n] missing key "${key}" for locale "${locale}"`);
19
      return `⟦${key}⟧`;
20
    }
21
    // Translation: provided by the message catalog; which form to pick: decided by PluralRules
22
    const template = typeof entry === "string"
23
      ? entry
24
      : (entry[pr.select(params.count)] ?? entry.other);
25
    return template.replace(/\{(\w+)\}/g, (_, k) => {
26
      if (!(k in params)) throw new Error(`[i18n] key "${key}" requires parameter "${k}"`);
27
      return k === "count" ? nf.format(params[k]) : String(params[k]);
28
    });
29
  };
30
}

Running it, the actual output of the same sentence “the shopping cart has N items” in four languages:

1
zh-CN  0 items in the cart  |  1 item in the cart  |  2 items in the cart  |  5 items in the cart  |  21 items in the cart
2
en-US  0 items in your cart  |  1 item in your cart  |  2 items in your cart  |  5 items in your cart  |  21 items in your cart
3
ru-RU  В корзине 0 товаров  |  В корзине 1 товар  |  В корзине 2 товара  |  В корзине 5 товаров  |  В корзине 21 товар
4
ar-EG  السلة فارغة  |  عنصر واحد في السلة  |  عنصران في السلة  |  ٥ عناصر في السلة  |  ٢١ عنصرًا في السلة

Note the first two of ar-EG: 0 uses “the shopping cart is empty,” and 1 and 2 don’t show a number at all—Arabic has dedicated phrasings for zero / one / two. This is what “slots must be sufficient” means. Also, ٥ and ٢١ are Arabic’s own numeral glyphs, which nf.format() handles automatically.

Why Missing Parameters Must Throw an Exception#

In my first implementation, the parameter validation was written as params[k] ?? 0, and when a parameter was missing, it quietly rendered:

1
NaN items in your cart

A NaN mixed into the user interface is ten times harder to track down than an exception—it might go live for a long time before a user screenshots it and complains. So the last line of the version above is a hard validation if (!(k in params)) throw. In internationalization code, “silent degradation” is the most dangerous design choice:

1
Throw error -> [i18n] missing key "cart.total" for locale "zh-CN"
2
Throw error -> [i18n] key "cart.items" requires parameter "count"

As for “whether to throw in production,” the answer is throw in development, degrade + report in production: during development nobody wants to dig through logs looking for ⟦cart.total⟧, and in production it’s not worth a blank screen over a key with a missing translation. But this degradation must simultaneously trigger a monitoring alert, otherwise it’s just silent failure.

Array.prototype.sort() Can’t Sort Chinese#

When Array.prototype.sort() is not passed a comparison function, it sorts by UTF-16 code units. For Chinese, this is essentially random:

1
const cities = ["Chongqing", "Beijing", "Shanghai", "Xi'an", "Changsha", "Shenzhen"];
2
cities.sort();                                                 // Code point order
3
cities.sort(new Intl.Collator("zh-CN", { collation: "pinyin" }).compare);
4
cities.sort(new Intl.Collator("zh-CN", { collation: "stroke" }).compare);

Actual test:

1
Default (code point)      : 上海 北京 深圳 西安 重庆 长沙
2
Collator + pinyin : 北京 重庆 上海 深圳 西安 长沙     ← Pinyin order
3
Collator + stroke : 上海 北京 长沙 西安 重庆 深圳     ← Stroke order

The code point order result 上海 北京 深圳 西安 重庆 长沙 is meaningless to humans—it’s sorted by Unicode encoding values. Any user-facing Chinese list sorting must use Intl.Collator.

Collator also has two very practical options:

1
new Intl.Collator("en", { numeric: true }).compare;
2
// ["file10.txt","file2.txt","file1.txt","File3.txt"].sort(...)
3
// Default sort   : File3.txt file1.txt file10.txt file2.txt
4
// numeric    : file1.txt file2.txt File3.txt file10.txt    ← numbers compared by numeric value
5

6
new Intl.Collator("en", { sensitivity: "base" }).compare;
7
// "résumé" / "resume" / "RESUME" / "Résumé" treated as equal, usable for search highlight matching

numeric: true solves the classic problem of “file10 sorting before file2.” sensitivity: "base" is useful in search matching scenarios—when a user types resume, it should match résumé.

The Correct Way to Count Emoji: Intl.Segmenter#

For requirements like “limit to 100 characters,” using String.length is wrong. Because JS strings are UTF-16:

1
"👨‍👩‍👧‍👦🇨🇳👍🏽".length                                    // 19
2
[... "👨‍👩‍👧‍👦🇨🇳👍🏽"].length                                // 11   ← using spread doesn't work either
3
[... new Intl.Segmenter("zh-CN", { granularity: "grapheme" }).segment("👨‍👩‍👧‍👦🇨🇳👍🏽")].length  // 3

Three numbers, only 3 is correct. A family-of-four emoji is 7 code points, 11 UTF-16 code units, but in the user’s eyes it’s 1 character. The same applies to flags and skin-tone gestures. When a user counts “3 characters left” in an input field and gets truncated, this is where the miscalculation happens.

Segmenter can also do word segmentation, which is more valuable in Chinese than in English (because Chinese has no spaces):

1
const seg = new Intl.Segmenter("zh-CN", { granularity: "word" });
2
const words = [...seg.segment("Hello world! The graphemes of i18n also include emoji")]
3
  .filter(s => s.isWordLike).map(s => s.segment);
4
// 8 words: Hello / 世界 / i18n / 的 / grapheme / 里 / 还有 / emoji

Compare with the naive split(/\s+/):

1
["Hello","世界！i18n","的","grapheme","里还有","emoji"]

isWordLike automatically filters punctuation and correctly splits “世界！i18n” and “里还有”—splitting by spaces would treat “世界！i18n” as one word. Using it for “estimated reading time” and “keyword highlighting” is far more reliable than split(/\s+/).

Use “Semantics” for Keys, Not “Copy”#

A recurring multiple-choice question:

1
t("Save changes")     // ❌ Using source copy as key
2
t("common.actions.save")  // ✅ Using semantic paths as keys

The problem with using source copy as keys is: change the English copy once, and all keys across all languages become invalid, and you can’t get information like “which keys haven’t been translated yet.” The cost of semantic keys is that developers have to think one step further about naming, but what you get in return is enumerability, validatability, and measurability.

Two more practices to add:

• Don’t concatenate sentence fragments. t("you_have") + count + t("items") will inevitably be wrong in German—German word order (especially verb position in subordinate clauses) differs greatly from other languages, and concatenated word order won’t hold. Parameters must be placed inside the full-sentence template (just like {count} in the previous section).
• Don’t include grammatical information in keys (no item_singular / item_plural). Grammatical form is PluralRules’s responsibility; the key only needs to express the single semantic meaning of “this is the cart item count.”

The Current State of ICU MessageFormat and MF2#

The {count} above is a “simplified placeholder.” The industry standard is ICU MessageFormat, which writes plurals, selections, and nesting all into a single message:

1
{cartItems, plural,
2
  =0 {Your cart is empty}
3
  one {# item in your cart}
4
  other {# items in your cart}
5
}

=0’s exact-match syntax is crucial—it lets “0 items” be written as a completely different message without being squeezed into the other branch. This is something count === 1 ? A : B can never do.

Here we need to clarify a point that outdated articles often mislead about—the current state of MessageFormat 2 (MF2) (September 2026):

• The spec itself is already stable: MF2 is maintained by the Unicode CLDR Technical Committee, entered Final Candidate in March 2025, and after LDML 47/48 revisions, the spec has entered a stable state.
• But the native JS API is still far off: TC39’s Intl.MessageFormat proposal is stuck at Stage 2, blocked on the need for enough organizations to use MF2 in production to move forward; mainstream i18n libraries (FormatJS/react-intl, Lingui, Tolgee) are still on MF1.
• Tested on this machine’s Node 26.5.1: typeof Intl.MessageFormat === "undefined".

So the practical recommendation is: write message catalogs in MF1 (ICU MessageFormat), but delegate “parsing” to a library (@formatjs/intl-messageformat, intl-messageformat, etc.), and don’t couple the message format to your own runtime. When Intl.MessageFormat lands, what gets replaced is the library, not your message files. This also means don’t design your message catalog in a library’s proprietary format—use standard ICU syntax so migration costs stay manageable.

Pitfall 1: * is a valid Accept-Language, but not a valid BCP 47 tag#

RFC 9110’s language-range explicitly allows * (“any language”), but Intl.getCanonicalLocales("*") will directly throw RangeError:

1
getCanonicalLocales("*")   -> RangeError: Invalid language tag: *
2
getCanonicalLocales("en_us") -> RangeError: Invalid language tag: en_us
3
getCanonicalLocales("zh-hans-cn") -> ["zh-Hans-CN"]

Note the third line: case and canonical form are auto-corrected, but the separator must be a hyphen — underscores (very common in HTTP headers, e.g., some clients send en_us) will cause Intl to throw instead of being tolerant. So when parsing Accept-Language, you must sanitize the format first, then hand it to Intl, and the entire logic must be wrapped in try/catch. Feeding user-controllable headers directly into an API that throws exceptions is a DoS surface.

Pitfall 2: q=0 means “explicitly do not want”#

zh-CN,en;q=0 means “Chinese is fine, but English absolutely not.” The filter condition must be q > 0, not “use q if present, default if absent.” Miss this filter, and you’ll push English to users who explicitly rejected it.

Pitfall 3: Not distinguishing zh-Hans from zh-Hant#

Both zh-Hans-CN and zh-TW are Chinese, but Simplified and Traditional glyphs are completely different. The lookup logic above will resolve zh-Hans-CN to zh-CN (correct), but if SUPPORTED only contains zh-TW, zh-Hans-CN will also fall into it (incorrect) — users will see a Traditional Chinese interface. Simplified and Traditional must be handled as two independent entries in the supported list, not relying on language subtags as a fallback.

Negotiation results must include Vary#

This step is directly related to caching: if the same URL returns different content based on Accept-Language, CDNs and browsers must know this, otherwise a Chinese page will be cached and served to English users. The response header must include:

1
Vary: Accept-Language

The cost is a lower cache hit rate (one copy per language). The details of this trade-off were covered in The Complete Guide to HTTP Caching Strategies: From Browser to CDN — simply put: expressing language via separate URLs (/zh-CN/posts/) is easier to cache than the same URL + Vary, and is better for sharing and SEO, at the cost of needing an extra routing layer.

The lang Attribute Determines Glyphs, Not Just Accessibility#

1
<html lang="zh-CN">

This attribute directly affects the rendering result. The same Unicode code point may use different glyphs under ja and zh-CN—the differences in how characters like “直,” “骨,” and “今” are written in Chinese vs. Japanese fonts are visible to the naked eye (this kind of difference is called “same code point, different glyphs” in CJK). Browsers rely on lang to select glyph variants, and omitting lang results in “Japanese-style kanji on a Chinese page.”

On pages with mixed languages, you also need to annotate local content separately:

1
<p>This API is called <span lang="en">Server Components</span>, which is generally translated into Chinese as "Server Components".</p>

The accompanying CSS is the :lang() pseudo-class, which lets you specify different font stacks for different languages—this also relates to Web Font Loading Optimization: Chinese fonts are often several MB in size, so you must do subset splitting by unicode-range to prevent English pages from downloading Chinese font files.

RTL: Don’t Write margin-left#

Arabic, Hebrew, and Persian are right-to-left (RTL). Supporting RTL doesn’t require two sets of CSS—it just requires replacing physical properties with logical properties:

Then you only need one dir attribute, and the entire site’s direction flips:

1
<html lang="ar-EG" dir="rtl">

There are a few places that need extra attention:

• Icons should be mirrored, but not all icons should be mirrored. Back arrows and play directions should be mirrored; clocks, company logos, and checkboxes should not be mirrored (mirroring them would actually be wrong).
• Numbers and code blocks remain left-to-right in RTL. Browsers handle this with the bidirectional algorithm, but code blocks should explicitly use direction: ltr to avoid wording being reordered.
• flex-direction: row flips automatically (because it’s “inline direction”), so no manual changes are needed. This is the most effortless part of the logical property system.

Pseudo-Localization: Turn “Untranslated” into “Looks Weird”#

The idea behind pseudo-localization is: replace all source copy with an auto-generated “fake translation” by adding diacritics, lengthening, and adding brackets:

1
const MAP = { a:"á", b:"ƀ", c:"ç", d:"ð", e:"é", /* ... */ };
2
const pseudo = (s) => "⟦" + [...s].map((c) => MAP[c] ?? c).join("") + "⟧";
3

4
pseudo("Save changes");  // "⟦Šáṽé çĥáñĝéš⟧"
5
pseudo("Settings");      // "⟦Šéţţíñĝš⟧"

It solves three problems at once:

1. Hardcoded strings that haven’t been internationalized will display as-is as Save changes, making them easy to spot in a sea of ⟦Šáṽé...⟧;
2. Lengthened text will break layouts (note that Settings goes from 8 characters to 10 characters, and underscore testing usually adds another 30%–40%). Real German and Russian text is much longer than English, so layout problems surface early;
3. Brackets expose truncation—if you only see ⟦Šáṽé çĥá on the UI without the closing ⟧, it means it was truncated by overflow: hidden.

Running a pseudo-localized build once typically uncovers a dozen places where “this was never wired up for translation.”

Block Hardcoded Strings in CI#

Pseudo-localization relies on human eyes; a more reliable approach is adding a static check. The rule is simple: text nodes in JSX / templates that contain CJK characters or full English sentences and don’t come from t() should trigger a warning.

1
const CJK = /[一-鿿]/;
2
const TEXT_NODE = />\s*[^<>{}\s][^<>{}]*\s*</;   // simplified version: >text<
3

4
const samples = [
5
  `  <button>Save</button>`,
6
  `  const msg = t("post.save")`,
7
  `  <p>Showing {count} results</p>`,
8
  `  <title>My Blog</title>`,
9
];

Output:

1
SUSPECT <button>Save</button>
2
ok       const msg = t("post.save")
3
ok       <p>Showing {count} results</p>
4
SUSPECT  <title>My Blog</title>

The regex above is just a simplified demo version (a real implementation should use AST tools, such as a custom ESLint rule working with JSX’s JSXText nodes, or an off-the-shelf plugin like eslint-plugin-i18next). The key isn’t how accurate the regex is—it’s whether there’s an automated line of defense at all—relying purely on manual review will definitely miss things.

Three More Things to Check#

1. Key coverage: 源语言 key 集合 - 目标语言 key 集合—the difference set must be empty before merging. This should be a CI gate.
2. Parameter consistency: the cart.items in en uses {count}, but the {count} in the ru version misspells it as {coutn}—this won’t throw an error, it will just render {coutn}. Validate that each message’s placeholder set is consistent across languages—low cost, extremely high payoff.
3. Plural form completeness: use PluralRules(locale).resolvedOptions().pluralCategories to cross-check the catalog, and report an error for whichever form is missing. For example, if the Russian catalog only has one / other, that’s a clear bug (compare with the table in Section 4).