Don't Panic — Software Internationalization and Localization

Internationalization is the engineering work that lets a product adapt to different languages, regions, and writing systems without being rebuilt each time. Localization is the later, locale-specific adaptation. They are related in the way a well-designed kitchen is related to cooking dinner: one makes the other possible, but neither automatically produces the other.

Translation matters, but it is not the whole caravan. People also read dates, amounts, names, addresses, sorted lists, and screens that may run right to left. A product can contain perfectly translated words and still behave as if everyone uses one date order, one family-name arrangement, and one convenient direction of travel. Computers are diligent about preserving assumptions. They are less diligent about announcing them.

The dependable idea is to keep a stable value separate from its presentation. Store an instant as an instant and an amount as an amount. Then use the selected locale, meaning the language, regional, cultural, and preference context, to format what a person sees. Passing a preformatted date through an API is like mailing somebody a clock already set to your wall. It has information, but not all the information they need.

Text brings its own small galaxy of trouble. Unicode lets systems represent text across writing systems, but it does not mean a visible symbol has one code point, or that a label has a predictable width. Collation, the language-sensitive rules for sorting and grouping text, is not the same thing as raw code-point order. A list may be sorted with great confidence and very little relevance to its readers.

Messages need their own shape too. Keep a message identifier and structured values rather than joining translated fragments around a variable. Another locale may need another word order, plural form, or message structure. The string concatenation is rarely malicious. It is merely a tiny English sentence wearing a false moustache.

Start with the Intro for the architecture and design choices. Use Slides for the relationships among data, locale, and presentation. Keep the Cheatsheet nearby while reviewing a feature, then use the practice exercise to turn hidden assumptions into an audit. The Reference tab leads into the W3C, Unicode, CLDR, and BCP 47 material when the broad map needs exact rules.