Default is not download locales at runtime

Author: kipcole9

CHANGELOG.md

@@ -12,7 +12,7 @@ The format is based on
 
 * Runtime locale downloading is now **opt-in**. The new `:allow_runtime_locale_download` application config key (default `false`) gates whether the `PersistentTerm` provider may download locale ETF files from the CDN when a cache miss occurs. When disabled (the default), a missing locale returns `{:error, %Localize.LocaleNotFoundInCacheError{}}` with a message that tells the user how to fix it (either run `mix localize.download_locales` or enable the config key). The `Localize.Locale.Provider` behaviour gains an optional `allow_download?/0` callback so alternative providers can implement their own download-gating logic.
 
-* `mix localize.download_locales` — new Mix task (shipped with the hex package) that downloads locale ETF files from the Localize CDN and writes them to the configured cache directory. Three modes: `mix localize.download_locales en fr de` for specific locales, `--preload` to download the configured `:preload_locales`, and `--all` for all 766 CLDR locales. Intended for Dockerfiles, CI pipelines, and release builds.
+* `mix localize.download_locales` — new Mix task (shipped with the hex package) that downloads locale ETF files from the Localize CDN and writes them to the configured cache directory. With no arguments, downloads the configured `:supported_locales`. Also accepts explicit locale names (`mix localize.download_locales en fr de`) or `--all` for all CLDR locales. Intended for Dockerfiles, CI pipelines, and release builds.
 
 * `Localize.Locale.expand_locale_list/2` — extracted from `Localize.Application` as a public function so mix tasks and user code can expand wildcard locale lists (e.g. `"en-*"`) against the known CLDR locale set.
 
@@ -104,6 +104,8 @@ The format is based on
 
 * Configuration option `:data_dir` renamed to `:locale_cache_dir`. Defaults to `Path.join(:code.priv_dir(:localize), "localize/locales")`.
 
+* **`:preload_locales` is deprecated and ignored.** Use `:supported_locales` to declare your locale set and `mix localize.download_locales` to pre-populate the cache at build time. Locale data is loaded lazily into `:persistent_term` on first access. A deprecation warning is logged at application startup if `:preload_locales` is still configured.
+
 * `Localize.List.to_string/2` and `Localize.List.intersperse/2` option `:format` renamed to `:list_style`. The companion helpers `known_list_formats/0` and `list_formats_for/1` were renamed to `known_list_styles/0` and `list_styles_for/1` for consistency. Freeing `:format` from list-specific use means it now passes through to per-element formatters: `Localize.List.to_string([~D[2025-07-10], ~D[2025-08-15]], locale: :en, format: :long)` produces `"July 10, 2025 and August 15, 2025"` because `:format` reaches `Localize.Date.to_string/2` for each element while the list join uses the default `:standard` style. The `list_patterns_for/1` helper is unchanged — it returns the underlying CLDR pattern data, not the style names.
 
 ### Added exceptions

DEVELOPMENT.md

@@ -291,7 +291,7 @@ mix localize.upload_locale              # Generate one locale and upload to Clou
 
 # ── User tasks (lib/ tree, shipped with the hex package) ────────
 mix localize.download_locales en fr de  # Download specific locale ETFs from the CDN
-mix localize.download_locales --preload # Download the :preload_locales from config
+mix localize.download_locales            # Download configured :supported_locales (default)
 mix localize.download_locales --all     # Download all 766 CLDR locales
 ```
 

README.md

@@ -117,7 +117,6 @@ Localize requires no compile-time configuration. All options are set in your app
 config :localize,
   default_locale: :fr,
   supported_locales: [:en, :fr, :de, :ja, :es, "zh-*"],
-  preload_locales: [:en, :de, :ja, "fr-*"],
   locale_provider: MyApp.LocaleProvider,
   locale_cache_max_entries: 2_000,
   format_cache_max_entries: 5_000,
@@ -130,8 +129,8 @@ config :localize,
 | Option | Default | Description |
 |--------|---------|-------------|
 | `:default_locale` | Derived from `LOCALIZE_DEFAULT_LOCALE` env var, then `LANG` env var, then `:en`. | The application-wide default locale. Can also be set at runtime with `Localize.put_default_locale/1`. |
-| `:supported_locales` | `nil` | A list of locale identifiers that your application supports. Each entry is an atom matching a known CLDR locale (e.g., `:en`, `:"fr-CA"`) or a wildcard string (e.g., `"en-*"`) that expands to all matching CLDR locales. Invalid entries log a warning and are skipped. When set, `validate_locale/1` resolves locale identifiers against this list rather than all ~766 CLDR locales. Accessible at runtime via `Localize.supported_locales/0`. See below for how this interacts with `:preload_locales`. |
-| `:preload_locales` | `nil` | A list of locale identifiers to load at application startup. Accepts atoms and wildcard strings like `:supported_locales`. Locale data is fetched and cached in `:persistent_term` before any formatting calls. Invalid entries log a warning and are skipped. See below for how this interacts with `:supported_locales`. |
+| `:supported_locales` | `nil` | A list of locale identifiers that your application supports. Each entry is an atom matching a known CLDR locale (e.g., `:en`, `:"fr-CA"`), a wildcard string (e.g., `"en-*"`), a coverage-level keyword (`:modern`, `:moderate`, `:basic`), or a Gettext-style string (e.g., `"pt_BR"`, `"zh_Hans"`). POSIX-style underscores are normalised to hyphens and entries are resolved to their CLDR canonical form via likely-subtag resolution (e.g. `"pt_BR"` → `:pt`). Only exact matches (score 0) are accepted — entries that cannot be resolved log a warning with `domain: :localize` and are skipped. When set, `validate_locale/1` resolves locale identifiers against this list rather than all ~766 CLDR locales. Accessible at runtime via `Localize.supported_locales/0`. |
+| `:preload_locales` | **deprecated** | Deprecated and ignored. Use `:supported_locales` to declare your locale set and `mix localize.download_locales` to pre-populate the cache at build time. |
 | `:locale_provider` | `Localize.Locale.Provider.PersistentTerm` | Module that implements the `Localize.Locale.Provider` behaviour for loading and caching per-locale data. |
 | `:locale_cache_max_entries` | `1_000` | Maximum number of validated locales to hold in the ETS cache. A background sweeper runs every 10 seconds and evicts excess entries to prevent unbounded growth. |
 | `:format_cache_max_entries` | `2_000` | Maximum number of compiled format patterns (number and date/time) to hold in the ETS cache. A background sweeper runs every 10 seconds and evicts excess entries to prevent unbounded growth. |
@@ -141,20 +140,30 @@ config :localize,
 | `:cacertfile` | System default | Path to a custom CA certificate file for HTTPS connections (used when downloading locale data). |
 | `:https_proxy` | `nil` | HTTPS proxy URL. Also reads the `HTTPS_PROXY` environment variable. |
 
-### Supported and preload locale interaction
+### Using Gettext locales
 
-When `:supported_locales` is configured, the effective supported locale list is the **union** of `:supported_locales` and `:preload_locales`. This means any locale you preload is automatically considered supported — you don't need to list it in both places.
+If your application uses Gettext, you can derive `:supported_locales` from your Gettext backend in `config/runtime.exs` (where the module is already compiled and available):
 
 ```elixir
+# config/runtime.exs
 config :localize,
-  supported_locales: [:en, :fr, :de],
-  preload_locales: [:ja]
+  supported_locales: Gettext.known_locales(MyApp.Gettext)
+```
+
+POSIX-style locale names returned by Gettext (e.g. `"pt_BR"`, `"zh_Hans"`) are automatically normalized to BCP 47 and resolved to their CLDR canonical form (`:pt`, `:zh`). No manual mapping is needed.
+
+### Pre-populating the locale cache
 
-# Effective supported locales: [:en, :fr, :de, :ja]
-# Locale data for :ja is preloaded at startup
+Use `mix localize.download_locales` at build time to download locale data into the on-disk cache. By default it downloads the configured `:supported_locales`:
+
+```bash
+# Dockerfile
+RUN mix localize.download_locales
 ```
 
-When `:supported_locales` is **not** configured (the default), `validate_locale/1` matches against all ~766 CLDR locales and `:preload_locales` simply controls which locale data is loaded eagerly.
+Specific locales can also be downloaded explicitly: `mix localize.download_locales en fr de`. Use `--all` for all CLDR locales. Locale data is loaded lazily into `:persistent_term` on first access from the cache.
+
+When `:supported_locales` is **not** configured (the default), `validate_locale/1` matches against all ~766 CLDR locales.
 
 ## Environment variables
 

guides/migration.md

@@ -24,25 +24,50 @@ Localize requires no compile-time configuration. All options are set in your app
 
 ### Recommended migration config
 
-Most ex_cldr projects configure a fixed set of locales in the backend module. The Localize equivalent is `:supported_locales` (constrains validation) and `:preload_locales` (eagerly loads locale data at startup):
+Most ex_cldr projects configure a fixed set of locales in the backend module. The Localize equivalent is `:supported_locales` (constrains validation) plus `mix localize.download_locales` (pre-populates the cache at build time):
 
 ```elixir
 # config/config.exs
 config :localize,
   default_locale: :en,
-  supported_locales: [:en, :fr, :de, :ja],
-  preload_locales: [:en, :fr, :de, :ja]
+  supported_locales: [:en, :fr, :de, :ja]
 ```
 
-In ex_cldr, these were declared inside `use Cldr, locales: [...]`. In Localize they are application environment keys, so no recompilation is needed when the list changes.
+```bash
+# At build time (Dockerfile, CI, or local)
+mix localize.download_locales
+```
+
+In ex_cldr, locales were declared inside `use Cldr, locales: [...]` and embedded at compile time. In Localize, `:supported_locales` is an application environment key (no recompilation needed), and locale data is downloaded once at build time and loaded lazily into `:persistent_term` on first access.
+
+### Using Gettext locales
+
+If your application uses Gettext, you can derive `:supported_locales` from your Gettext backend. Since the Gettext module must be compiled first, use `config/runtime.exs`:
+
+```elixir
+# config/runtime.exs
+config :localize,
+  supported_locales: Gettext.known_locales(MyApp.Gettext)
+```
+
+POSIX-style locale names returned by Gettext (e.g. `"pt_BR"`, `"zh_Hans"`) are automatically normalised to BCP 47 and resolved to their CLDR canonical form via likely-subtag resolution. For example, `"pt_BR"` resolves to `:pt` (CLDR treats bare `pt` as Brazilian Portuguese) and `"zh_Hans"` resolves to `:zh`. No manual mapping is needed.
+
+Only exact matches (distance score 0 in the CLDR matching algorithm) are accepted for `:supported_locales` — this ensures that misspelled or unrecognised locale names are caught at startup rather than silently mapping to a distant locale. Entries that cannot be resolved log a warning with `domain: :localize` and are skipped.
+
+Coverage-level keywords (`:modern`, `:moderate`, `:basic`) are also accepted and expand to all CLDR locales at or above that level:
+
+```elixir
+config :localize,
+  supported_locales: [:modern]  # ~104 locales with modern CLDR coverage
+```
 
 ### Full options reference
 
 | Option | Default | Description |
 |---|---|---|
 | `:default_locale` | Derived from `LOCALIZE_DEFAULT_LOCALE` env var → `LANG` env var → `:en` | Application-wide default locale. |
-| `:supported_locales` | `nil` (all 766 CLDR locales) | List of locale atoms and/or wildcard strings (e.g. `"en-*"`). When set, `validate_locale/1` resolves against this list instead of all CLDR locales. |
-| `:preload_locales` | `nil` | List of locales to load into `:persistent_term` at application startup. Anything in `:preload_locales` is automatically considered supported. |
+| `:supported_locales` | `nil` (all 766 CLDR locales) | List of locale atoms, wildcard strings (e.g. `"en-*"`), coverage-level keywords (`:modern`, `:moderate`, `:basic`), or Gettext-style strings (e.g. `"pt_BR"`). POSIX underscores are normalised and entries are resolved via likely-subtag resolution — only exact matches (score 0) are accepted. Invalid entries log a warning and are skipped. When set, `validate_locale/1` resolves against this list instead of all CLDR locales. |
+| `:preload_locales` | **deprecated** | Deprecated and ignored. Use `:supported_locales` and `mix localize.download_locales`. |
 | `:locale_cache_dir` | `Application.app_dir(:localize, "priv/localize/locales")` | Directory where downloaded locale ETF files are cached. |
 | `:allow_runtime_locale_download` | `false` | When `true`, locales not in the cache are downloaded from the CDN on first access. Default `false` — use `mix localize.download_locales` to pre-populate at build time. |
 | `:locale_provider` | `Localize.Locale.Provider.PersistentTerm` | Module implementing `Localize.Locale.Provider` for locale data loading. |
@@ -88,9 +113,9 @@ iex> Localize.with_locale(:ja, fn ->
 {:ok, "1,234"}
 ```
 
-### Supported and preload locale interaction
+### Pre-populating the locale cache
 
-When `:supported_locales` is configured, the effective supported locale list is the **union** of `:supported_locales` and `:preload_locales`. Any locale you preload is automatically considered supported — you don't need to list it in both places.
+Run `mix localize.download_locales` at build time to download locale data for all configured `:supported_locales`. Locale data is then loaded lazily into `:persistent_term` on first access — no runtime downloads needed.
 
 ## Dependency changes
 

lib/localize.ex

@@ -1205,7 +1205,10 @@ defmodule Localize do
   locale. When given a binary locale identifier, it is parsed into
   a `t:Localize.LanguageTag.t/0`. When given an existing language tag
   whose `:cldr_locale_id` is not yet populated, a best-match
-  resolution is attempted using `Localize.LanguageTag.best_match/2`.
+  resolution is attempted using `Localize.LanguageTag.best_match/3`.
+
+  POSIX-style locale names (e.g. `"pt_BR"`, `"zh_Hans"`) are
+  accepted — underscores are normalized to hyphens before parsing.
 
   ## Locale resolution
 
@@ -1215,16 +1218,31 @@ defmodule Localize do
 
   * If `config :localize, supported_locales: [...]` is
     configured, the candidate list is the resolved supported
-    locales (the union of `:supported_locales` and
-    `:preload_locales`). This restricts matching to only the
-    locales your application explicitly supports.
+    locales. This restricts matching to only the locales your
+    application explicitly supports.
 
   * If `:supported_locales` is not configured, the candidate
     list is all CLDR locale IDs.
 
   Validated locale results are cached in an ETS table so
   repeated calls with the same identifier are fast (~1µs).
 
+  > #### Always returns a result {: .warning}
+  >
+  > This function uses the CLDR locale matching algorithm, which
+  > is designed to **always return a result** when the candidate
+  > list is non-empty — even if the match is very distant. For
+  > example, `validate_locale("xyzzy")` will succeed and return
+  > some CLDR locale (typically the first candidate), not an error.
+  > This is the correct CLDR behaviour for user-facing locale
+  > negotiation (a distant match is better than no match), but it
+  > means the returned locale may not be what the caller expected.
+  >
+  > For strict validation (e.g. resolving configuration values),
+  > use `Localize.LanguageTag.best_match/3` with a threshold of
+  > `0` to accept only exact matches after likely-subtag
+  > resolution.
+
   ### Arguments
 
   * `locale` is a locale identifier binary, an atom, or a
@@ -1248,6 +1266,10 @@ defmodule Localize do
       iex> tag.cldr_locale_id
       :en
 
+      iex> {:ok, tag} = Localize.validate_locale("pt_BR")
+      iex> tag.cldr_locale_id
+      :pt
+
   """
   @spec validate_locale(Localize.LanguageTag.t() | String.t() | atom()) ::
           {:ok, Localize.LanguageTag.t()} | {:error, Exception.t()}

lib/localize/application.ex

@@ -42,50 +42,35 @@ defmodule Localize.Application do
     end
   end
 
-  # ── Supported and preload locales ─────────────────────────────
+  # ── Supported locales ───────────────────────────────────────────
 
   defp resolve_supported_locales do
-    supported = expand_config_locales(:supported_locales)
-    preload = expand_config_locales(:preload_locales)
+    maybe_warn_deprecated_preload()
 
-    # Store the union of supported and preload locales, but only
-    # if :supported_locales was explicitly configured.
     case Application.get_env(:localize, :supported_locales) do
       nil ->
         :ok
 
-      _configured ->
-        merged =
-          (supported ++ preload)
-          |> Enum.uniq()
-
-        :persistent_term.put({:localize, :supported_locales}, merged)
+      locales when is_list(locales) ->
+        expanded = Localize.Locale.expand_locale_list(locales, :supported_locales)
+        :persistent_term.put({:localize, :supported_locales}, expanded)
     end
-
-    # Preload locale data for the preload list. Failures are
-    # logged as warnings rather than crashing the supervisor —
-    # the locale will be loaded on first access (or the user
-    # will get a clear error if downloads are disabled and the
-    # locale is not in the cache).
-    Enum.each(preload, fn locale ->
-      case Localize.Locale.Loader.load_and_store(locale) do
-        :ok ->
-          :ok
-
-        {:error, exception} ->
-          Logger.warning(
-            "Failed to preload locale #{inspect(locale)}: #{Exception.message(exception)}",
-            domain: [:localize]
-          )
-      end
-    end)
   end
 
-  defp expand_config_locales(config_key) do
-    case Application.get_env(:localize, config_key) do
-      nil -> []
-      [] -> []
-      locales when is_list(locales) -> Localize.Locale.expand_locale_list(locales, config_key)
+  defp maybe_warn_deprecated_preload do
+    case Application.get_env(:localize, :preload_locales) do
+      nil ->
+        :ok
+
+      _configured ->
+        Logger.warning(
+          "The :preload_locales configuration key is deprecated and ignored. " <>
+            "Use :supported_locales to declare your locale set, and " <>
+            "`mix localize.download_locales` to pre-populate the cache " <>
+            "at build time. Locale data is loaded lazily into " <>
+            ":persistent_term on first access.",
+          domain: [:localize]
+        )
     end
   end
 end