Add usage_rules.md

Author: kipcole9

mix.exs

@@ -54,8 +54,9 @@ defmodule Localize.MixProject do
         "README*",
         "CHANGELOG*",
         "LICENSE*",
+        "usage-rules.md",
         "priv/localize/*.etf",
-        "priv/localize/verison",
+        "priv/localize/version",
         "priv/localize/localize_patch_version",
         "priv/localize/supplemental_data",
         "priv/localize/validity",

usage-rules.md

@@ -0,0 +1,127 @@
+# Localize usage rules
+
+Rules for LLM coding agents using `Localize` as a dependency. These are not exhaustive — see the HexDocs guides for full reference.
+
+## Core conventions
+
+* All public formatting and validation functions return `{:ok, result}` or `{:error, exception}`. Pattern match with `case`/`with`, never `try/rescue`. The exception is a struct (e.g. `%Localize.UnknownLocaleError{}`), not a string.
+
+* Bang variants (`to_string!/2`, `validate_locale!/1`, etc.) exist for the rare cases where raising is preferred.
+
+* Never construct locale identifiers by hand and pass them around as raw strings. Call `Localize.validate_locale/1` once and pass the resulting `%Localize.LanguageTag{}` struct, or use a validated atom (`:en`, `:"en-AU"`).
+
+* Locale identifiers are atoms in canonical form: `:en`, `:"en-AU"`, `:"zh-Hant"`. Strings (`"en-AU"`) are also accepted by every public function and validated on the way in. Do not mix `_` (POSIX) and `-` (BCP 47) — Localize accepts both but normalizes to `-`.
+
+* There is no compile-time backend module. Do not write `use Localize` or `defmodule MyApp.Localize`. All 766 CLDR locales are available immediately.
+
+## Module map
+
+| Task | Use |
+|---|---|
+| Numbers, decimals, percentages, currencies | `Localize.Number.to_string/2` |
+| Dates | `Localize.Date.to_string/2` |
+| Times | `Localize.Time.to_string/2` |
+| Datetimes | `Localize.DateTime.to_string/2` |
+| Date/time intervals | `Localize.Interval.to_string/3` |
+| Relative time ("in 3 days") | `Localize.DateTime.Relative.to_string/2` |
+| Units of measure | `Localize.Unit.new/2` + `Localize.Unit.to_string/2` |
+| Lists ("a, b, and c") | `Localize.List.to_string/2` |
+| Territory display names, flags | `Localize.Territory.display_name/2`, `Localize.Territory.unicode_flag/1` |
+| Language display names | `Localize.Language.display_name/2` |
+| Locale display names | `Localize.Locale.LocaleDisplay.display_name/2` |
+| Currency metadata | `Localize.Currency.*` |
+| String sorting / collation | `Localize.Collation.sort/2`, `Localize.Collation.compare/3` |
+| MessageFormat 2 / pluralization | `Localize.Message.format/3` |
+| Calendar names (months, days, eras) | `Localize.Calendar.display_name/3` |
+
+## Locale management
+
+* The current locale is per-process. Set it once at the start of a request (e.g. in a Plug) with `Localize.put_locale(:de)`. Every formatting function then defaults its `:locale` option to `Localize.get_locale()`.
+
+* For temporary locale changes inside a function, use `Localize.with_locale/2` rather than save/put/restore.
+
+* The application-wide default locale is resolved (in order) from: `LOCALIZE_DEFAULT_LOCALE` env var → `config :localize, default_locale: ...` → `LANG` env var → `:en`. Set this at deploy time, not in code.
+
+## Common idioms
+
+```elixir
+# Numbers
+{:ok, "1,234.5"}     = Localize.Number.to_string(1234.5)
+{:ok, "1.234,5"}     = Localize.Number.to_string(1234.5, locale: :de)
+{:ok, "$1,234.56"}   = Localize.Number.to_string(1234.56, currency: :USD)
+{:ok, "56%"}         = Localize.Number.to_string(0.56, format: :percent)
+
+# Dates and times
+{:ok, "Jul 10, 2025"}        = Localize.Date.to_string(~D[2025-07-10])
+{:ok, "10. Juli 2025"}       = Localize.Date.to_string(~D[2025-07-10], locale: :de, format: :long)
+
+# Units
+{:ok, unit} = Localize.Unit.new(42, "kilometer")
+{:ok, "42 km"}              = Localize.Unit.to_string(unit, format: :short)
+
+# Lists
+{:ok, "apple, banana, and cherry"} =
+  Localize.List.to_string(["apple", "banana", "cherry"])
+
+# Collation
+["apple", "banana", "Cherry"] =
+  Localize.Collation.sort(["banana", "apple", "Cherry"])
+
+# Pluralization via MessageFormat 2
+Localize.Message.format(
+  ~S".input {$count :integer}\n.match $count\n  one {{{$count} item}}\n  *   {{{$count} items}}",
+  %{"count" => 3}
+)
+#=> {:ok, "3 items"}
+
+# Validation
+{:ok, %Localize.LanguageTag{cldr_locale_id: :en}} = Localize.validate_locale("en-US")
+```
+
+## Performance rules
+
+* For hot loops formatting many numbers with the same locale and format, pre-validate options once via `Localize.Number.Format.Options.validate_options/2` and pass the resulting struct. This skips per-call locale resolution and currency lookup. Speedup is ~3x for plain decimals and ~50x for currency formatting.
+
+* Set the process locale once with `Localize.put_locale/1` rather than passing `:locale` as an option on every call.
+
+* `Localize.validate_locale/1` is cached in ETS — first call ~50µs, subsequent calls ~1µs. Pre-validate locales you know you will need at app startup.
+
+## Configuration
+
+```elixir
+# config/config.exs — minimum useful config
+config :localize,
+  default_locale: :en,
+  supported_locales: [:en, :fr, :de, :ja, "es-*"],
+  preload_locales: [:en, :fr, :de]
+```
+
+* `:supported_locales` constrains `validate_locale/1` to your declared subset. If unset (the default), all 766 CLDR locales are valid. Wildcard strings (`"es-*"`) expand to every matching locale.
+
+* `:preload_locales` loads locale data eagerly at app start instead of lazily on first use. Anything in `:preload_locales` is automatically considered supported.
+
+## Things not to do
+
+* Do not write `Localize.Number.to_string!(value)` and discard the locale — at least pass `locale: Localize.get_locale()` if you have not set the process locale, or accept the application default.
+
+* Do not pattern match on the old ex_cldr error shape `{:error, {Module, "string"}}`. Localize returns `{:error, %Exception{}}` — match on the struct or call `Exception.message/1`.
+
+* Do not call `String.to_atom/1` on user-supplied locale strings. Use `Localize.validate_locale/1`, which canonicalizes and validates without atom-table pollution.
+
+* Do not assume `Localize.Territory.territory_codes/0` returns a list of territories — it returns a *map* of ISO 3166 code mappings. Use `Localize.Territory.individual_territories/0` for the sorted list of leaf territory atoms.
+
+* Do not reach for `Cldr.*` modules or backend modules. Localize replaces the entire `ex_cldr_*` family with a single dependency and no compile-time configuration.
+
+* Do not use `Localize.Number.to_string` for currency parsing or `Localize.Number.parse` for formatting — they are separate functions in the same module.
+
+## Companion packages
+
+When the user needs functionality outside Localize's core CLDR scope:
+
+* `localize_person_names` — TR35 Part 8 person name formatting.
+
+* `localize_phonenumber` — phone number parsing and formatting.
+
+* `localize_address` — postal address formatting.
+
+* `intl` — higher-level ergonomic API modeled on the JavaScript `Intl` object.