---
title: "Localization checklist: all 45 rules ยท Agent Wranglers"
url: https://agentwranglers.se/playbook/localization/checklist
updated: 2026-10-22
tokens: 4054
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---
# Localization checklist
For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Localization](https://agentwranglers.se/playbook/localization.md).
By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-22.
Every rule in the localization playbook, by chapter, required rules first. Each links to its own page with how we built it and how to check it. This is a lot to check. [An Expert can check it for you](https://agentwranglers.se/contact.md).
**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `Agent Wranglers localization playbook`. In code you write, add a comment next to it with the same link.
## Locales and preferences
- [ ] LOC-22 **Recommended** [Store language and time zone as two separate settings](https://agentwranglers.se/playbook/localization/locales-and-preferences/locale-and-time-zone-preferences.md): Store each user's locale as a BCP 47 tag and their time zone as an IANA zone name, in two separate fields. Use both for every date and time the app shows.
- [ ] LOC-23 **Recommended** [Fall back to the closest supported locale](https://agentwranglers.se/playbook/localization/locales-and-preferences/locale-fallback.md): Choose each request's locale from the user's saved choice first, then `Accept-Language`, then the default. Match against the supported list by removing subtags from the end and following CLDR parent locales.
- [ ] LOC-8 **Recommended** [Let people pick their language](https://agentwranglers.se/playbook/localization/locales-and-preferences/language-switcher.md): On sites with several languages, offer a switcher that names each language in that language and keeps people on the same page.
- [ ] LOC-5 **Avoid** [Never redirect by location](https://agentwranglers.se/playbook/localization/locales-and-preferences/avoid-auto-geo-redirects.md): Never send people to another language or country by IP address or `Accept-Language`. Suggest it and let them choose.
## Messages and translation
- [ ] LOC-25 **Required** [Ship a default text for every message](https://agentwranglers.se/playbook/localization/messages-and-translation/default-messages.md): Every message key has a text in the default language, and a missing translation falls back to it key by key at run time. A missing text never stops a screen from loading.
- [ ] LOC-13 **Recommended** [Translate whole sentences](https://agentwranglers.se/playbook/localization/messages-and-translation/whole-sentence-messages.md): On sites with several languages, or one planned, keep every visible text in a message file. Use one entry per whole sentence with named placeholders, and never build a sentence from translated pieces.
- [ ] LOC-12 **Recommended** [Get plurals right in every language](https://agentwranglers.se/playbook/localization/messages-and-translation/plural-rules.md): Choose plural forms from the language's plural rules instead of adding an "s".
- [ ] LOC-24 **Recommended** [Choose gender and other variants inside the message](https://agentwranglers.se/playbook/localization/messages-and-translation/select-messages.md): When a sentence changes with a person's gender, a role or another fixed choice, put every variant in one message with a `select` argument. Never pass a translated word into a placeholder.
- [ ] LOC-18 **Recommended** [Extract messages from the code with a tool](https://agentwranglers.se/playbook/localization/messages-and-translation/extract-messages.md): Build the source message file from the code with an extraction tool, never by hand. CI fails when the committed file differs from a fresh extraction.
- [ ] LOC-19 **Recommended** [Fail the build on missing or broken translations](https://agentwranglers.se/playbook/localization/messages-and-translation/translation-completeness.md): Before release, every key in the source exists in each published language, and every translation has the same placeholders as its source.
- [ ] LOC-20 **Recommended** [Mark translations stale when the source changes](https://agentwranglers.se/playbook/localization/messages-and-translation/stale-translations.md): When a source sentence changes, mark its translations as needing review in every language. A stale translation is never published as current.
- [ ] LOC-21 **Recommended** [Give translators context and a review step](https://agentwranglers.se/playbook/localization/messages-and-translation/translator-context.md): Every message carries a note for translators, and every translation, human or machine, is reviewed by a fluent speaker before release.
## Dates, numbers and text
- [ ] LOC-27 **Required** [Take the currency from the amount and not from the locale](https://agentwranglers.se/playbook/localization/dates-numbers-and-text/currency-from-the-amount.md): Format every price with the currency code stored with that amount. The reader's locale chooses only the separators and the symbol position.
- [ ] LOC-29 **Required** [Change the case of identifiers without a locale](https://agentwranglers.se/playbook/localization/dates-numbers-and-text/locale-independent-case.md): Lower-case and upper-case keys, protocol words, file extensions and identifiers with locale-independent functions. Use locale-aware case only for text shown to people.
- [ ] LOC-11 **Recommended** [Format dates and numbers for the reader](https://agentwranglers.se/playbook/localization/dates-numbers-and-text/locale-content.md): Format dates, numbers and money for the reader's locale with a formatting library. Show times with a named time zone.
- [ ] LOC-28 **Recommended** [Read the week start and units from locale data](https://agentwranglers.se/playbook/localization/dates-numbers-and-text/week-and-units-from-cldr.md): Read the first day of the week, the weekend, the 12 or 24 hour clock and the measurement system from CLDR locale data. Never hard-code them.
- [ ] LOC-15 **Recommended** [Sort and compare text by locale](https://agentwranglers.se/playbook/localization/dates-numbers-and-text/locale-collation.md): Sort and compare visible text with a collator for the reader's locale, and normalise Unicode before comparing or storing it.
- [ ] LOC-16 **Recommended** [Accept names and addresses from every country](https://agentwranglers.se/playbook/localization/dates-numbers-and-text/international-names-and-addresses.md): Let people enter names and addresses as they are written in their country. Never reject letters, word counts or field shapes your own country does not use.
- [ ] LOC-26 **Avoid** [Writing date formats by hand](https://agentwranglers.se/playbook/localization/dates-numbers-and-text/hand-written-date-patterns.md): Never build a date for people from a hand-written pattern such as `MM/dd/yyyy`. Ask the formatter for a style or a skeleton, and let the locale data order the fields.
## Layout and scripts
- [ ] LOC-30 **Recommended** [Let every layout grow with the longest translation](https://agentwranglers.se/playbook/localization/layout-and-scripts/text-expansion.md): Give text room to grow. No text container has a fixed width or height, and every screen is tested with the longest translation of each message.
- [ ] LOC-14 **Recommended** [Test with a pseudo-locale](https://agentwranglers.se/playbook/localization/layout-and-scripts/pseudo-localisation.md): When a site will be translated, build a pseudo-locale that makes every text longer and accented. Run the page tests in it before any translation exists.
- [ ] LOC-9 **Recommended** [Support right-to-left text](https://agentwranglers.se/playbook/localization/layout-and-scripts/rtl-support.md): Support right-to-left languages with `dir`, logical CSS properties and `dir="auto"` on user input.
- [ ] LOC-31 **Recommended** [Isolate inserted text from the text around it](https://agentwranglers.se/playbook/localization/layout-and-scripts/bidi-isolation.md): Wrap every inserted value whose direction you do not know, such as a user name or a product title, in a direction isolate. Use `` or `dir="auto"` in HTML, and the Unicode isolate characters in plain text.
- [ ] LOC-10 **Optional** [Support vertical and CJK text](https://agentwranglers.se/playbook/localization/layout-and-scripts/writing-modes.md): Where Chinese, Japanese or Korean (CJK) text appears, support vertical writing and their line breaking with `writing-mode` and the right line-break rules.
## Multilingual websites
- [ ] LOC-6 **Required** [Mark foreign words](https://agentwranglers.se/playbook/localization/multilingual-websites/lang-attribute.md): Mark every passage in another language with its own `lang` attribute.
- [ ] LOC-1 **Recommended** [Give each language its own path](https://agentwranglers.se/playbook/localization/multilingual-websites/international-url-structure.md): On sites with several languages, give each language one clear address pattern, such as `/en/` and `/sv/`, and keep it stable. A one-language site needs no prefix.
- [ ] LOC-2 **Recommended** [Link language versions together](https://agentwranglers.se/playbook/localization/multilingual-websites/hreflang.md): On sites with several languages, link each language version of a page to the others with `hreflang`. A one-language site should not use it.
- [ ] LOC-3 **Recommended** [Translate the metadata too](https://agentwranglers.se/playbook/localization/multilingual-websites/localised-metadata.md): Set the language in `lang`, `og:locale` and `inLanguage` in structured data, and write alt text in that language.
- [ ] LOC-4 **Optional** [List language versions in the sitemap](https://agentwranglers.se/playbook/localization/multilingual-websites/sitemap-hreflang.md): On sites with several languages, list each page's language versions in the sitemap with `hreflang`.
- [ ] LOC-7 **Optional** [Keep names out of machine translation](https://agentwranglers.se/playbook/localization/multilingual-websites/translate-attribute.md): Protect names, code and addresses from machine translation with `translate="no"`.
- [ ] LOC-17 **Optional** [Make non-ASCII domains work](https://agentwranglers.se/playbook/localization/multilingual-websites/idn-support.md): If you use a domain name with non-Latin or accented letters, make its punycode form work everywhere the name appears.
## APIs and data
- [ ] LOC-32 **Recommended** [Send raw values with standard codes instead of formatted text](https://agentwranglers.se/playbook/localization/apis-and-data/locale-neutral-api-values.md): API fields and stored data hold raw values in standard forms. Languages are BCP 47 tags, countries are ISO 3166-1 alpha-2 codes, and numbers are JSON numbers. Formatting for people happens only in the client.
- [ ] LOC-33 **Recommended** [Answer human-readable text in the language the client asked for](https://agentwranglers.se/playbook/localization/apis-and-data/response-language.md): When an API returns text for people, choose its language from an explicit setting or parameter first, then `Accept-Language`. Answer with `Content-Language`, and add `Accept-Language` to `Vary` when it chose the language.
- [ ] LOC-34 **Recommended** [Give every error a code that clients can translate](https://agentwranglers.se/playbook/localization/apis-and-data/error-codes-for-translation.md): Every error carries a stable code and the values a client needs to build its own message. The code never changes with the language, and only the human text is translated.
- [ ] LOC-35 **Recommended** [Store translated content per record and language](https://agentwranglers.se/playbook/localization/apis-and-data/translated-content-storage.md): Store translatable content, such as product names and descriptions, in rows keyed by the record and a BCP 47 tag. Never add one column per language.
## Apps and command-line tools
- [ ] LOC-36 **Recommended** [Keep app strings in the platform's resource files](https://agentwranglers.se/playbook/localization/apps-and-command-line-tools/platform-string-resources.md): Phone and desktop apps keep every visible text in the platform's resource format, with plural variants, and never as text in the code. A lint check fails on hard-coded text.
- [ ] LOC-37 **Recommended** [Support the system's per-app language setting](https://agentwranglers.se/playbook/localization/apps-and-command-line-tools/per-app-language.md): Declare every language the app ships so iOS and Android list it in the system's per-app language setting. An in-app language picker opens that setting or uses the platform API, instead of a separate home-made switch.
- [ ] LOC-38 **Recommended** [Translate the store listing for every language the app ships](https://agentwranglers.se/playbook/localization/apps-and-command-line-tools/localized-store-listings.md): Each language the app ships has a store listing in that language, with name, short description, full description, keywords and screenshots. The listing never claims a language the app does not have.
- [ ] LOC-39 **Recommended** [Make command-line tools read the locale or say they do not](https://agentwranglers.se/playbook/localization/apps-and-command-line-tools/cli-locale.md): A command-line tool that prints translated text picks its language from `LC_ALL`, then `LC_MESSAGES`, then `LANG`. A tool in one language says so in its help. Machine-readable output is the same in every locale.
## Email, notifications and AI
- [ ] LOC-40 **Recommended** [Translate every part of an email](https://agentwranglers.se/playbook/localization/email-notifications-and-ai/localized-email.md): Render the subject, preview text, sender name, HTML part, plain-text part and footer of each email in the recipient's stored language. The links in it open pages in that language.
- [ ] LOC-41 **Recommended** [Tell the model which language to answer in](https://agentwranglers.se/playbook/localization/email-notifications-and-ai/ai-reply-language.md): Name the user's language in the system prompt of every AI feature, and check that each answer is in that language before showing it.
- [ ] LOC-42 **Recommended** [Run the evals in every language you support](https://agentwranglers.se/playbook/localization/email-notifications-and-ai/ai-evals-per-language.md): Run the eval set for each AI feature in every supported language, and report the pass rate per language. A release fails when any language drops below its threshold.
## Language laws
- [ ] LOC-43 **Required** [Show product safety information in the buyer's language](https://agentwranglers.se/playbook/localization/language-laws/product-safety-language.md): When you sell physical products to EU consumers online, show each product's warnings and safety information in the language its country sets.
- [ ] LOC-45 **Required** [Offer French when you sell in Quebec](https://agentwranglers.se/playbook/localization/language-laws/quebec-french.md): When you sell to customers in Quebec, offer your commercial web pages, product information, software and standard contracts in French. The French version is at least as easy to reach and as complete as any other.
- [ ] LOC-44 **Recommended** [Check each country's language rules for consumer contracts](https://agentwranglers.se/playbook/localization/language-laws/consumer-contract-language.md): Before you sell to consumers in an EU country, write down whether its law sets a language for contract information and terms. Offer them in that language when it does.
## Show the badge on your project
When your project passes every Required rule, you can show this badge on your site or in your README. It links to this checklist, so anyone can run the same checks.
```html
```
```markdown
[](https://agentwranglers.se/playbook/localization/checklist.md)
```