Localize Web usage rules

Copy Markdown View Source

Rules for LLM coding agents using localize_web as a dependency. Not exhaustive — see the HexDocs guides for full reference.

What this package is for

Connecting localize to Phoenix: resolving the locale from an incoming request, localized routes, and HTML helpers.

Core conventions

  • Resolve the locale in a plug, once, at the start of the request, and let everything downstream read Localize.get_locale/0. Do not thread a locale through function arguments.

  • Localize.AcceptLanguage.parse/1 and best_match/1 implement the header properly, including quality values and fallback. Use them rather than reading the header by hand.

Module map

TaskUse
Parse the accept-language headerLocalize.AcceptLanguage.parse/1, tokenize/1
Choose the best supported localeLocalize.AcceptLanguage.best_match/1
Set the locale for a requestLocalize.Plug.*, put_locale_from_session/2
Localized route pathsLocalize.Routes
Territory <select> and optionsLocalize.HTML.Territory.select/3, territory_options/1

Things not to do

  • Do not choose the content language from the visitor's IP geolocation. Location is not language, and it fails for travellers, expatriates, multilingual territories and VPN users. accept-language is the user's explicit statement of preference; honour it. Geolocation is at best a tiebreaker when the header offers nothing supported.

  • When you do vary on the header, send Vary: Accept-Language so caches and CDNs do not serve one visitor's language to another.

  • Do not parse accept-language with String.split(","). It carries quality values, ranges and ordering rules.

  • Do not persist a locale in the session without also offering a way to change it, and do not let a stale session locale override a fresh explicit choice.

  • Do not fall back to a hard-coded :en without trying the locale's parent chain first — Localize resolves :"de-AT" to :de before it gives up.