
Internationalization (i18n) and localization (l10n) involve numerous intricate details. At the beginning I just want to draft a checklist for i18n & l10n design. This checklist serves as a reference for planning during the software design phase. However, it provides only a high-level overview. Since different countries and regions have unique requirements and standards, this document does not cover specific implementation details. Instead, it highlights key considerations to keep in mind when designing for international audiences.

> This document is a work in progress. And I have opensourced this draft on github: https://github.com/PrinOrange/i18n-l10n-checklist.git  

## Language & Translation  

### Character Sets and Encoding 

Although UTF-8 is widely adopted, some platforms may not support it by default and instead use their own encoding schemes, such as ISO 8859-1, GBK, JIS, or Big5.

Have you accounted for this in your application's character processing? Does your platform support displaying the required character sets, including Latin, CJK ideographic, Cyrillic, Thai, and others?

Here is the wikipedia page for [charset encoding](https://en.wikipedia.org/wiki/Character_encoding#Common_character_encodings). 

### Transcription Systems  

In cases where certain character sets are unsupported, do you need a transcription system? For example, some Unix-based systems only support the ASCII character set and cannot display Cyrillic characters, requiring transliteration into Latin script.  

### Dialects and Regional Variants  

+ **Multi Official Language:** A country or region may have multiple official languages or dialects. For example, Singapore recognizes English, Chinese, and Malay, while Hong Kong uses both Cantonese and English. Have you accounted for these linguistic variations?  
+ **Region dialects:** Additionally, a single language may have multiple regional variations. For instance, Arabic as spoken in Saudi Arabia differs significantly from that used in the United Arab Emirates. Likewise, spelling and pronunciation vary between British English, Australian English, and American English.

### Fonts

For some languages use same character set may have different font glyphs.

- Japanese Kanji and Chinese character has different glyph standard. For same character, Chinese font and Japanese font may has different displaying formals.
- Vietnamese and English share Latin characters, but Vietnamese has tone annotations, so the center of gravity in Vietnamese fonts is lower than that of English.

## UI, Layout & Typography  

### Right-to-Left (RTL) & Left-to-Right (LTR) Support  

Have you ensured that your UI properly supports RTL languages such as Arabic and Hebrew? 

+ In RTL layout, the position of default button, visual direction are reverse.
+ Some animation directions are reverse, for example, progress bar, switch button and carousel slides.
+ Sequence logic are reverse. For example, the `Next` button is on left while `Previous` button is on right. And the pagination buttons are reverse too.
+ Some icons should not be reverse, like clock, handwriting icons.
+ For mathematic formulas, some Arabic region use latin-form formula while other use traditional Arabic numeral notations form, this should be reverse written, like. [See formula directions in Arabic document.](https://en.wikipedia.org/wiki/Modern_Arabic_mathematical_notation)

### Line Breaking & Layout Adjustments  

Different languages have different line-breaking rules. For example, Chinese and Japanese do not use spaces to separate words, while Thai requires special segmentation rules. Does your layout handle these differences correctly without causing layout thrashing?  

## UX & Interaction Design  

### Keyboard Layouts

Keyboard layouts vary by region. Common layouts include QWERTY, QWERTZ, and AZERTY, and even within the same language, there may be differences. For example, the U.S. uses a standard QWERTY layout, while the U.K. has a slightly different variation. [See more details](https://en.wikipedia.org/wiki/Keyboard_layout).  

+ When designing shortcut keys, ensure they remain accessible and intuitive across different keyboard layouts.
+ Have your software been adopted for user's language Input Method Editor (IME). You need to ensure that the user's input method can be worked normally in your software.

## Content & Resources  

### Sorting Rules  

Sorting rules vary between regions, even though for one language. 

- Most of regions that uses alphabets-based language typically use alphabet-dictionary order based on item titles.
- In mainland China, sorting by Pinyin is common. Hong Kong sorts by stroke count, whereas Taiwan follows Bopomofo order.
- Note: some character sorting in UTF encoding are not equal to them in alphabets for some languages. For example, the Finnish letters `Å, Ä, Ö` are ranked last in the alphabet (after Z) in Swedish, Finnish, Estonian and other languages. However, the default sorting of computers (such as strcmp or JavaScript localeCompare in C) may be sorted by Unicode code points: `A, Å, Ä, B, C, ..., O, Ö, P, Q, ..., Z`

Moreover, alphabetical orders differ across languages, affecting sorting logic. Ensure your sorting algorithm accounts for these regional differences.  

### Date Formats, Time Zones & Daylight Saving Time  

+ **Date format:** Which date format is used in your target regions? Is it *DD/MM/YYYY*, *YYYY/MM/DD*, or *MM/DD/YYYY*? [See the distribution map of date formatting among different regions](https://en.wikipedia.org/wiki/List_of_date_formats_by_country).
+ **Time Zone:** Have you considered the time zone differences for each regions and countries? For example, the U.S. actually has six time zones, Eastern Time Zone, Central Time Zone, Mountain Time Zone, Pacific Time Zone, Alaska Time Zone, and Hawaii-Aleutian Time Zone. Here is the [details for time zone map](https://www.timeanddate.com/time/map/).
+ **Daylight saving time:** Are month names written as numbers or spelled out? Do you need to account for daylight saving time adjustments? For example, some European region and U.S. have daylight saving time.
+ **Special Calendar:** Some countries may not use the Gregorian calendar. For example, Japan uses the Era-Name Calendar(令和/平成/昭和), and Thailand uses the Thai Solar Calendar.

### Number Formats, Measurement Units & Mathematical Conventions  

Different regions have unique numerical formatting and measurement units.  

- The U.S. and U.K. use a comma (`1,000,000`) as a thousand separator and a dot (`1.5`) for decimals, whereas Germany, France and other European countries reverse this notation (`1.000.000` and `1,5`).  
- India groups numbers differently, using a **2-2-3** format: `10,00,000` instead of `1,000,000`.  
- Measurement units vary: the U.S. uses inches, feet, and pounds, while most of the world follows the metric system.  
- Not every regions only use Western Arabic numerals (like $0,1,2,3,...,9$), for middle eastern regions, they prefer using traditional eastern Arabic numerals(like 0-9, their written form are separately like $٠-0,١-1,٢-2,٣-3,٤-4,٥-5,٦-6,٧-7,٨-8,٩-9$)
- Numbering rules. For some situation the numbering rules depends on formatting rules, like chapter numbering, they prefer using Roman numerals like `Chapter Ⅰ`, `Chapter Ⅳ`.

Ensure your application can handle these variations dynamically.  

### Natural Language Processing (NLP) Considerations  

If your application involves NLP features such as search, spell checking, or text analysis, are these adapted for different languages?

+ Tokenizer design: for different language there are variant ways to process tokens and words during text indexing for search feature. Your should take intrinsic details of different languages into consideration, like stemmer, removing stopwords.
+ Declension. In i18n, it is necessary to deal with word inflection, because the same word may change depending on the context when expressing grammatical structures such as number, gender, tense, case, etc, especially in situation about string concat. If these inflections are not handled, the translated content may be grammatically incorrect, unnatural, or even difficult to understand, which will seriously affect the user experience and product professionalism.

### Audio, Video & Media Localization  

Have you prepared subtitles and translated resources for different languages? If your product supports live streaming or real-time interactions, do you provide interpretation services?  

### Cultural Sensitivities for Symbolism  

Have you accounted for cultural taboos and regional sensitivities?  

- In monarchies like Thailand and Iran, criticism of the royal family is strictly prohibited.  
- In Muslim-majority countries, certain animal symbols (e.g., pigs, donkeys) are considered inappropriate.  
- Some regions restrict religious imagery; for example, Christmas-related elements are not permitted in Saudi Arabia and Yemen.  
- Symbols can have vastly different meanings:  
  - The “OK” gesture (`👌`) is positive in the U.S. but offensive in France, Germany, and Brazil.  
  - The thumbs-up sign (`👍`) may be considered sarcastic in Greece and parts of Latin America.  

To avoid unintended offense, research regional interpretations before including symbols in your UI.  

## Monetization & Payments  

+ **Currency Unit:** What is the smallest currency unit in the target market? In China, it's 0.1 yuan, whereas in the U.S., it's 0.01 dollars.  
+ **Regulation:** Are currency exchange rates, transaction policies, and regional banking regulations accounted for?  
+ **Formal Written:** How are large amounts displayed? In China, Japan and Korea, amounts may be written in uppercase Chinese characters(壹/贰/叁/肆/伍), whereas English uses full word spelling, for example, the number `1,013,978.1` is written in form "One million thirteen thousand nine hundred seventy-eight and one tenth".

## Performance & Optimization  

### CDN & Network Zones  

Have you optimized content delivery networks (CDNs) for different regions to ensure low-latency performance? Is it optimized for local networks?

- Fallback Logic: Handle missing locales with graceful fallback, for example, the Mexico speaks spanish and it's supposed to load language resource `es-MX` but if there are missing such resource, you could make fallback logic, even fallback to default language: `es-MX → es → en`
- Avoid Query Strings for Locale: Query strings may break caching. Prefer path-based routing.
- Language-based URL Structure: Use paths like /i18n/en-US.json instead of query params for better caching.
- Lazy Load Translations: Only load the needed language file (e.g., fr-FR.json) at runtime.
- Font & Asset Localization: Split requests of fonts/images by language — especially for large scripts like Chinese, Japanese.

## Security & Access Control  

Are there specific compliance or data protection laws that need to be followed, such as GDPR in Europe or PIPL in China?

+ You should seek for user's permission according to the law the *ePrivacy Directive* by setting cookie acceptance button for websites in European and America.

## Legal & Compliance  

Have you considered regional legal requirements related to software distribution, content moderation, and user privacy? For example, 

+ The European Union has very strict privacy legislation. If you collect user's interactions and information without permission, you will be fined.
+ In China, your software and website must be verified with ICP and copyright license before publishing, and annotate the license notably in specified position.

## Accessibility & Inclusive Design  

Have you accounted for accessibility standards?  

- Different countries use different Braille systems and sign languages.  
- Screen readers and assistive technologies should be tested across various locales. 

## Cultural Factor

Certain expressions or phrases may have region-specific variations that need careful translation to avoid sounding unnatural or inappropriate. 

+ For example, in Arabic-speaking regions, formal texts often include religious phrases like "Allahu Akbar" ("Allah is great"). 
+ In Japan and South Korea, appropriate honorifics should be used based on social and contextual factors, like「です」「ます」, and「습니다」 

## References  

- [W3C Internationalization Best Practices](https://w3c.github.io/bp-i18n-specdev/)  


The Checklist for software i18n design. This checklist is intended to provide a checklist for planning reference during the software design phase. Of course, this is just an outline.

Drafts for I18n & L10n Mind Framework.


我们都应该为身边有这样的人，痛苦地活着，又痛苦地死去，而感到惭愧。🕯️

![](https://image-assets.dreams.plus/202507071733397.png)


我们都应该为身边有这样的人，痛苦地活着，又痛苦地死去，而感到惭愧。

心非木石岂无感


The **`WeakMap`** is a special type of collection in JavaScript. It was formally introduced in the ES6 standard and is similar to `Map`, but with several key differences:

- A `WeakMap` is a collection of **key-value pairs (key → value)**;
- **Keys can only be objects** (plain objects, arrays, functions, etc.), **not primitives** (numbers, strings, booleans, etc.);
- `WeakMap` holds **weak references** to its keys, meaning:
  If no other variables reference the object anymore, the garbage collector will automatically reclaim it, and the corresponding entry in the `WeakMap` will disappear.

| Feature       | `Map`                                                   | `WeakMap`                                           |
| ------------- | ------------------------------------------------------- | --------------------------------------------------- |
| Key Types     | Any value (objects or primitives)                       | Objects only                                        |
| Key Reference | Strong reference                                        | Weak reference                                      |
| Enumerable    | Enumerable (iterable via `map.keys()`, `map.entries()`) | Not enumerable (no iteration methods)               |
| Use Cases     | General key-value mapping storage                       | Data that needs to be tied to an object's lifecycle |

Why are weak references needed? Suppose we want to attach "extra information" to certain objects but don't want this information to prevent the objects from being garbage collected. For example:

```js
const wm = new WeakMap();

function createUser(name) {
  const user = { name };
  wm.set(user, { created: Date.now() });
  return user;
}

let alice = createUser("Alice");
console.log(wm.get(alice));
// { created: 1692624526805 }  // e.g., stores creation time

// When alice is no longer referenced, the object will be GC'd, and the entry in the WeakMap disappears
alice = null;
```

Here, the role of `WeakMap` is to store **additional metadata** without worrying about the object "living forever" because it's stored in a Map.

`WeakMap` acts like an **Object Additional Information Warehouse** —the keys inside it do not affect object reclamation. Its greatest value is: **following the object's lifecycle and avoiding memory leaks**.

Many people mistakenly think that the "weak" reference in **WeakMap is implemented via reference counting**, but that's not the case.

**Reference counting** is a garbage collection algorithm: an object's reference count drops to zero → memory is released. However, modern JavaScript engines (V8, SpiderMonkey, etc.) **do not rely solely on reference counting**. Instead, they use garbage collection centered around **reachability analysis**. Therefore, the "weak reference" in WeakMap is **not "delete when reference count = 0"**. Rather:
**The key in a WeakMap is not considered a "root of reachability"**.

In a regular `Map`, the key object is strongly referenced. Even if no external variables reference it anymore, it remains "reachable" and won't be GC'd.

In a `WeakMap`, the key is a **weak reference**. The garbage collector does not count it as part of the "live objects": if there are no other strong references from the outside, the key will be reclaimed by GC, and the corresponding key → value mapping will disappear.

Because the JS engine needs the freedom to remove entries during GC, if it allowed you to enumerate the WeakMap, you might see entries that "have been reclaimed but not yet cleaned up," making the semantics uncertain.
Therefore, WeakMap only supports `set/get/has/delete` and **cannot be iterated**.

The underlying mechanism of WeakMap is not "reference counting" but is based on the **reachability-based garbage collection mechanism**. Its "weak reference" essentially tells the GC: **Keys in the WeakMap do not count as active references**. Thus, WeakMap is very suitable for storing "additional data that disappears along with the object."

Below is a diagram illustrating the difference in garbage collection between a **regular Map and a WeakMap**.

For a strongly referencing Map:

```js
let map = new Map();
let obj = { name: "Alice" };

map.set(obj, "metadata");

// Now, even if obj = null,
// the map still "strongly references" this object
obj = null;
```

The memory relationship is:

```
[Global variable map] ──► [Map instance]
                               │
                               ▼
                         ┌───────────────┐
                         │ key: {Alice}  │──► "metadata"
                         └───────────────┘
```

Even after `obj = null`, the Map still holds `{Alice}`, which won't be GC'd. **This can easily cause memory leaks**.

For a weakly referencing WeakMap:

```js
let wm = new WeakMap();
let obj = { name: "Alice" };

wm.set(obj, "metadata");

// Remove the external reference to obj
obj = null;
```

Its memory relationship is as follows:

```
[Global variable wm] ──► [WeakMap instance]
                                 │
                                 ▼
                           ┌───────────────┐
                           │ key: {Alice}  │──► "metadata"
                           └───────────────┘
```

After `obj = null`, there are no strong references pointing to `{Alice}`: GC considers `{Alice}` "unreachable," reclaims the object, and the key-value pair in the WeakMap automatically disappears.

This **does not prevent garbage collection**.

In Node.js, directly observing garbage collection is difficult because **GC is automatic**.
However, starting from Node.js v14, `WeakRef` and `FinalizationRegistry` are available, allowing us to **simulate the WeakMap reclamation process**.

Here is some experimental code:

```js
// Save a WeakMap
const wm = new WeakMap();

// Register a FinalizationRegistry to notify when an object is reclaimed
const registry = new FinalizationRegistry((heldValue) => {
  console.log(`Object has been reclaimed, the corresponding metadata was: ${heldValue}`);
});

(function test() {
  let obj = { name: "Alice" };

  // Store a record in the WeakMap
  wm.set(obj, "metadata for Alice");

  // Register a reclamation callback for the object
  registry.register(obj, "metadata for Alice");

  console.log("Object created and stored in WeakMap");

  // Manually clear the strong reference to obj
  obj = null;
})();

// Prompt Node.js to perform garbage collection
// ⚠️ Requires running with the flag: node --expose-gc test.js
setTimeout(() => {
  console.log("Attempting to manually trigger garbage collection");
  if (global.gc) {
    global.gc();
  } else {
    console.log("Please run this script with node --expose-gc");
  }
}, 1000);
```

Next, save the code as `test.js` and run it with the GC flag:

```bash
node --expose-gc test.js
```
You will see output similar to:

```
Object created and stored in WeakMap
Attempting to manually trigger garbage collection
Object has been reclaimed, the corresponding metadata was: metadata for Alice
```

Thus, we can see:

* The key in `WeakMap` does not prevent object reclamation;
* `FinalizationRegistry` can trigger a callback after the object is GC'd, proving the WeakMap entry has disappeared;
* This shows the essence of WeakMap's "weak reference" is: **It does not treat the key as a root of reachability for GC**.

Below are several **typical use cases for WeakMap**. You'll find it's primarily used for "attaching extra information to objects without wanting to affect the object's lifecycle":

1.  **Private properties** (security + automatic release)
2.  **Caching** (automatically cleaned up when the object is released)
3.  **DOM/object metadata storage** (without polluting the original object)
4.  **Event listener management**
5.  **Implicit information attachment inside libraries**

**Private property storage** (simulating class private fields)

```js
const privateData = new WeakMap();

class User {
  constructor(name, password) {
    this.name = name;
    privateData.set(this, { password });
  }

  checkPassword(pw) {
    return privateData.get(this).password === pw;
  }
}

const u = new User("Alice", "123456");
console.log(u.checkPassword("123456")); // true
console.log(u.password); // undefined (cannot access directly)
```

Using WeakMap to save "private data"; when the object instance is reclaimed, the data is automatically released too.

**Caching (Memoization)**

```js
const cache = new WeakMap();

function heavyCompute(obj) {
  if (cache.has(obj)) {
    return cache.get(obj);
  }
  let result = expensiveCalculation(obj);
  cache.set(obj, result);
  return result;
}

function expensiveCalculation(o) {
  return JSON.stringify(o).length; // Assume it's computationally expensive
}

let data = { foo: "bar" };
console.log(heavyCompute(data)); // Compute and cache
console.log(heavyCompute(data)); // Read directly from cache
data = null; // Release the object, cache automatically cleans up
```

Ideal for "object → result" caching scenarios, prevents memory leaks.

**DOM metadata storage**

```js
const elementData = new WeakMap();

function bindInfo(el, info) {
  elementData.set(el, info);
}

function getInfo(el) {
  return elementData.get(el);
}

// Usage
const button = document.querySelector("button");
bindInfo(button, { clicked: 0 });

button.addEventListener("click", () => {
  const info = getInfo(button);
  info.clicked++;
  console.log(`Button click count: ${info.clicked}`);
});
```

When the `button` node is removed from the DOM and becomes unreachable, the WeakMap automatically clears the metadata, preventing memory leaks.

**Event listener state tracking**

```js
const listenerMap = new WeakMap();

function trackListener(obj, listener) {
  obj.addEventListener("click", listener);
  listenerMap.set(obj, listener);
}

function removeListener(obj) {
  const listener = listenerMap.get(obj);
  obj.removeEventListener("click", listener);
  listenerMap.delete(obj);
}
```

Tracks bound listeners and automatically releases them.

**Cross-library/cross-module additional information**

If you are writing a library and don't want to pollute user objects (avoid adding properties directly), WeakMap can "attach" data externally:

```js
// myLib.js
const meta = new WeakMap();

export function attach(obj, info) {
  meta.set(obj, info);
}

export function getInfo(obj) {
  return meta.get(obj);
}
```

Users won't see extra properties, and there's no risk of memory leaks.


The introduction and usage examples for Weakmap in ES6, with comparing to the Map.

MY BLOG