Localization playbook

A localization playbook for any product used in more than one language, region or time zone. It covers websites, web apps, phone apps, APIs, email, command-line tools and AI features.

The chapters start with each person's locale and time zone, and how to fall back when a language is missing. Then come messages and translation, dates, numbers and text, and layouts that survive long translations and right-to-left scripts. After that come multilingual websites, APIs and stored data, apps and command-line tools, and email, notifications and AI. The last chapter covers laws that set the language of what you sell.

Most rules pay off before the first translation. A product built with message files, locale formatting and room to grow takes a new language as data. A product with text in its code needs a rewrite first.

Chapters

1. Locales and preferences

   Store each person's language and time zone as two settings, pick the closest supported locale, and let people choose instead of guessing from location.

   • Recommended 3
   • Avoid 1

2. Messages and translation

   Keep all text in message files with plural and select rules. Fall back key by key, and check translations for gaps, stale text and context.

   • Required 1
   • Recommended 7

3. Dates, numbers and text

   Format dates, money and units from locale data, keep the currency with each amount, sort by locale, and change case of identifiers without a locale.

   • Required 2
   • Recommended 4
   • Avoid 1

4. Layout and scripts

   Build layouts that grow with the longest translation, test them in a pseudo-locale, and support right-to-left, mixed-direction and vertical text.

   • Recommended 4
   • Optional 1

5. Multilingual websites

   Give each language its own address, link the versions with hreflang, translate the metadata, mark foreign words and keep names out of machine translation.

   • Required 1
   • Recommended 3
   • Optional 3

6. APIs and data

   Send raw values with standard codes instead of formatted text, negotiate the language of messages, keep error codes stable, and store translations per locale.

   • Recommended 4

7. Apps and command-line tools

   Keep app strings in the platform's resource files, support per-app language settings, translate store listings, and make command-line tools read the locale.

   • Recommended 4

8. Email, notifications and AI

   Write every email part in the recipient's language, tell AI models which language to answer in, and test AI quality in each language you support.

   • Recommended 3

9. Language laws

   Some laws set the language of what you sell. Show EU product safety text in the buyer's language, check national contract rules, and offer French in Quebec.

   • Required 2
   • Recommended 1

All 45 rules on one page

This is a lot to check. An Expert can check it for you.

Related playbooks

• Dates and numbers

  In the Web app interface playbook. Show each time in the user's zone and read numbers the way people type them, on every screen.

• Requests and responses

  In the API design playbook. Send dates, money and IDs in one standard shape, so every client can format them for its reader.

• Channels and preferences

  In the Notifications playbook. Each notification goes out in the recipient's language, chosen at send time from their settings.

• Currencies and settlement

  In the Payments and billing playbook. Set a price per currency and refund in the one the customer paid, before you format it.

• Product and sector laws

  In the Compliance and governance playbook. Language laws sit next to other product laws. Check which ones cover what you sell.