display_name + LocaleDisplay: validate via validate_locale, process via canonical_locale_id; fix -u-rg- subdivision override

Author: kipcole9

CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.41.3] — July 1st, 2026
+
+### Changed
+
+* `Localize.LanguageTag`'s `canonical_locale_id` field — and therefore `Localize.LanguageTag.to_string/1` — now holds the *canonical-syntax* form of the requested locale (aliases resolved and subtags ordered, but neither maximized nor minimized), so `"en"` stays `"en"` and `"en-US"` stays `"en-US"` instead of collapsing to the minimal identity form. Locale identity and data lookup are unaffected; they key off `cldr_locale_id`.
+
+* `Localize.Language.display_name/2` now follows the TR35 display-name algorithm, which canonicalizes rather than adds likely subtags: a bare language keeps its own name (`"en"` → `"English"`, `"es"` → `"Spanish"`), while an explicitly supplied region or script still resolves to the region-specific CLDR name (`"en-GB"` → `"British English"`, `"pt-BR"` → `"Brazilian Portuguese"`). A string and an equivalent `Localize.LanguageTag` return the same result.
+
+* `Localize.Language.display_name/2` and `Localize.Locale.LocaleDisplay.display_name/2` both now validate their input through `Localize.validate_locale/1` and drive the display off `canonical_locale_id`, so a string and an equivalent (maximized) `Localize.LanguageTag` render identically and no likely subtags leak into the output (a validated `"en"` tag is `"English"`, not `"English (United States)"`).
+
+### Fixed
+
+* `Localize.Language.display_name/2` and `Localize.Locale.LocaleDisplay.display_name/2` now break the two-subtag candidate tie toward the earlier subtag per TR35, trying `lang-script` before `lang-region`.
+
+* `Localize.validate_locale/1` now accepts a `-u-rg-` region override that uses a subdivision id (e.g. `"en-u-rg-gbeng"`). The subdivision value was being suffixed with the `"zzzz"` region filler and rejected as an unknown locale.
+
 ## [0.41.2] — July 1st, 2026
 
 ### Bug Fixes

lib/localize/language.ex

@@ -88,6 +88,16 @@ defmodule Localize.Language do
       iex> Localize.Language.display_name("ja")
       {:ok, "Japanese"}
 
+  A bare language keeps its own name; an explicit region resolves to
+  the region-specific name where CLDR defines one (per TR35 the display
+  lookup canonicalizes but does not add likely subtags):
+
+      iex> Localize.Language.display_name("en")
+      {:ok, "English"}
+
+      iex> Localize.Language.display_name("en-US")
+      {:ok, "American English"}
+
   """
   @spec display_name(String.t() | LanguageTag.t(), Keyword.t()) ::
           {:ok, String.t()} | {:error, Exception.t()}
@@ -240,19 +250,43 @@ defmodule Localize.Language do
   # Builds candidate CLDR language keys from the most specific subtag
   # combination to the least, mirroring the CLDR locale display name
   # fallback order used by `Localize.Locale.LocaleDisplay`:
-  # lang-script-territory → lang-territory → lang-script → lang. The
-  # subtags are taken from the maximized (likely-subtags) language tag,
-  # so `"pt"` resolves through `pt-BR` and `"en-GB"` through `en-GB`.
-  defp candidate_codes(%LanguageTag{language: language, script: script, territory: territory}) do
+  # lang-script-territory → lang-script → lang-territory → lang. Per
+  # TR35 the tie between the two-subtag forms is broken in favour of the
+  # subtag matching earlier in the identifier, so `lang-script` is tried
+  # before `lang-territory`.
+  #
+  # The subtags are taken from the canonical-syntax form carried in
+  # `canonical_locale_id` — the caller's request with aliases resolved
+  # but no likely-subtags added — rather than the maximized struct
+  # fields. Per TR35 the display algorithm canonicalizes but does not
+  # maximize, so bare `"en"` resolves to "English" (not "American
+  # English") while an explicit `"en-GB"` still resolves to "British
+  # English". Falls back to the maximized fields when no canonical id is
+  # present (e.g. a hand-built tag).
+  defp candidate_codes(%LanguageTag{} = tag) do
+    {language, script, territory} = display_subtags(tag)
+
     [
       code_from(language, script, territory),
-      code_from(language, nil, territory),
       code_from(language, script, nil),
+      code_from(language, nil, territory),
       code_from(language, nil, nil)
     ]
     |> Enum.uniq()
   end
 
+  defp display_subtags(%LanguageTag{canonical_locale_id: id} = tag) when is_binary(id) do
+    case LanguageTag.parse(id) do
+      {:ok, %LanguageTag{language: language, script: script, territory: territory}} ->
+        {language, script, territory}
+
+      _ ->
+        {tag.language, tag.script, tag.territory}
+    end
+  end
+
+  defp display_subtags(%LanguageTag{} = tag), do: {tag.language, tag.script, tag.territory}
+
   defp code_from(language, script, territory) do
     [language, script, territory]
     |> Enum.reject(&is_nil/1)

lib/localize/language_tag.ex

@@ -341,11 +341,14 @@ defmodule Localize.LanguageTag do
   @doc """
   Create a fully resolved language tag from a locale string.
 
-  Parses the input, canonicalizes extensions, adds likely subtags
-  to populate missing fields, then computes the minimized
-  canonical locale name via remove likely subtags. The resulting
-  struct has all fields populated but the `canonical_locale_id`
-  is the shortest unambiguous form.
+  Parses the input, canonicalizes extensions, and adds likely
+  subtags to populate the `language`, `script`, and `territory`
+  fields with the maximized resolution. The `canonical_locale_id`
+  is set to the *canonical syntax* of the caller's request — the
+  input with aliases replaced and subtags ordered, but neither
+  maximized nor minimized — so `"en"` stays `"en"` and `"en-US"`
+  stays `"en-US"`. Locale identity and data lookup key off
+  `cldr_locale_id`, not `canonical_locale_id`.
 
   ### Arguments
 
@@ -368,15 +371,25 @@ defmodule Localize.LanguageTag do
       iex> tag.territory
       :TW
       iex> tag.canonical_locale_id
-      "zh-Hant"
+      "zh-TW"
 
   """
   @spec new(String.t()) :: {:ok, t()} | {:error, term()}
   def new(locale_id) when is_binary(locale_id) do
     with {:ok, parsed} <- parse(locale_id),
          {:ok, canonical} <- canonicalize(parsed),
          {:ok, resolved} <- remove_likely_subtags(canonical) do
-      tag = resolve_cldr_locale(resolved)
+      # `remove_likely_subtags/1` maximizes the subtag fields but leaves
+      # `canonical_locale_id` set to the minimized form. Restore the
+      # canonical-syntax id computed by `canonicalize/1` so the field
+      # faithfully reflects the caller's request (`en` stays `en`,
+      # `en-US` stays `en-US`) rather than collapsing to the minimal
+      # identity form. Locale identity/data lookup keys off
+      # `cldr_locale_id`, not this field.
+      tag =
+        %{resolved | canonical_locale_id: canonical.canonical_locale_id}
+        |> resolve_cldr_locale()
+
       {:ok, tag}
     end
   end

lib/localize/locale/locale_display.ex

@@ -63,17 +63,49 @@ defmodule Localize.Locale.LocaleDisplay do
   """
   @spec display_name(Localize.LanguageTag.t() | String.t() | atom(), display_options()) ::
           {:ok, String.t()} | {:error, Exception.t()}
-  def display_name(language_tag, options \\ [])
+  def display_name(locale, options \\ []) do
+    # Validate/normalize every input through the one canonical path
+    # (`Localize.validate_locale/1`), then drive the display off the
+    # canonical-syntax subtags carried in `canonical_locale_id`. This
+    # keeps a string and an equivalent (maximized) `%LanguageTag{}`
+    # rendering identically and prevents likely-subtags from leaking into
+    # the output — bare `"en"` is "English", not "English (United States)".
+    with {:ok, validated} <- Localize.validate_locale(locale) do
+      validated
+      |> canonical_display_tag()
+      |> do_display_name(options)
+    end
+  end
 
-  def display_name(language_tag, options)
-      when is_binary(language_tag) or is_atom(language_tag) do
-    with {:ok, parsed} <- Localize.LanguageTag.parse(to_string(language_tag)),
-         {:ok, canonical} <- Localize.LanguageTag.canonicalize(parsed) do
-      display_name(canonical, options)
+  # Reduce the maximized subtag fields to the canonical-syntax form held
+  # in `canonical_locale_id` (the caller's explicit request), keeping the
+  # validated tag's resolved `-u-`/`-t-` extensions and private use.
+  defp canonical_display_tag(%Localize.LanguageTag{canonical_locale_id: id} = validated)
+       when is_binary(id) do
+    case Localize.LanguageTag.parse(id) do
+      {:ok,
+       %Localize.LanguageTag{
+         language: language,
+         script: script,
+         territory: territory,
+         language_variants: variants
+       }} ->
+        %{
+          validated
+          | language: language,
+            script: script,
+            territory: territory,
+            language_variants: variants
+        }
+
+      _ ->
+        validated
     end
   end
 
-  def display_name(%Localize.LanguageTag{} = language_tag, options) do
+  defp canonical_display_tag(%Localize.LanguageTag{} = validated), do: validated
+
+  defp do_display_name(%Localize.LanguageTag{} = language_tag, options) do
     locale_id = resolve_locale_id(options)
     prefer = Keyword.get(options, :prefer, :standard)
     prefer = if prefer == :default, do: :standard, else: prefer
@@ -178,7 +210,9 @@ defmodule Localize.Locale.LocaleDisplay do
   # ── First Match (locale name specificity cascade) ────────────
 
   # Tries locale name combinations from most specific to least:
-  # lang-script-territory → lang-territory → lang-script → lang
+  # lang-script-territory → lang-script → lang-territory → lang
+  # Per TR35 the two-subtag tie is broken toward the subtag matching
+  # earlier in the identifier, so lang-script precedes lang-territory.
 
   defp first_match(language_tag, match_fun, :dialect) do
     do_first_match(language_tag, match_fun)
@@ -217,8 +251,8 @@ defmodule Localize.Locale.LocaleDisplay do
 
   defp try_matches(language, script, territory, fun) do
     locale_name_from(language, script, territory) |> fun.([:language, :script, :territory]) ||
-      locale_name_from(language, nil, territory) |> fun.([:language, :territory]) ||
       locale_name_from(language, script, nil) |> fun.([:language, :script]) ||
+      locale_name_from(language, nil, territory) |> fun.([:language, :territory]) ||
       locale_name_from(language, nil, nil) |> fun.([:language])
   end
 
@@ -227,10 +261,10 @@ defmodule Localize.Locale.LocaleDisplay do
 
     locale_name_from(language, script, territory, variant_str)
     |> fun.([:language, :script, :territory, :language_variants]) ||
-      locale_name_from(language, nil, territory, variant_str)
-      |> fun.([:language, :territory, :language_variants]) ||
       locale_name_from(language, script, nil, variant_str)
       |> fun.([:language, :script, :language_variants]) ||
+      locale_name_from(language, nil, territory, variant_str)
+      |> fun.([:language, :territory, :language_variants]) ||
       locale_name_from(language, nil, nil, variant_str)
       |> fun.([:language, :language_variants])
   end

lib/localize/validity/u.ex

@@ -97,11 +97,21 @@ defmodule Localize.Validity.U do
     |> String.downcase()
   end
 
+  # An `rg` region override is a 2-letter region suffixed with "zzzz"
+  # (e.g. `:US` → "uszzzz"). A subdivision override (e.g. `:gbeng` for
+  # GB-ENG) is emitted as-is — appending the filler would corrupt it into
+  # an unresolvable value like "gbengzzzz".
   defp encode_key("rg", value) when is_atom(value) do
-    value
-    |> Atom.to_string()
-    |> String.downcase()
-    |> Kernel.<>(@region_subtag_filler)
+    encoded =
+      value
+      |> Atom.to_string()
+      |> String.downcase()
+
+    if String.length(encoded) == 2 do
+      encoded <> @region_subtag_filler
+    else
+      encoded
+    end
   end
 
   defp encode_key("rg", value) do

mix.exs

@@ -1,7 +1,7 @@
 defmodule Localize.MixProject do
   use Mix.Project
 
-  @version "0.41.2"
+  @version "0.41.3"
   @cldr_version_path "priv/localize/version"
   @localize_patch_version_path "priv/localize/localize_patch_version"
 

test/localize/language_tag_test.exs

@@ -247,7 +247,9 @@ defmodule Localize.LanguageTagTest do
       assert tag.language == :zh
       assert tag.script == :Hant
       assert tag.territory == :TW
-      assert tag.canonical_locale_id == "zh-Hant"
+      # canonical_locale_id preserves the caller's explicit subtags in
+      # canonical syntax; the fields carry the maximized resolution.
+      assert tag.canonical_locale_id == "zh-TW"
       assert tag.cldr_locale_id != nil
     end
 
@@ -267,10 +269,21 @@ defmodule Localize.LanguageTagTest do
       assert tag.language == :en
       assert tag.script == :Latn
       assert tag.territory == :US
-      assert tag.canonical_locale_id == "en-u-ca-gregory"
+      assert tag.canonical_locale_id == "en-US-u-ca-gregory"
       assert tag.cldr_locale_id != nil
     end
 
+    test "accepts a -u-rg- subdivision region override without corrupting it" do
+      # A subdivision override (gbeng = GB-ENG) must not have the region
+      # filler "zzzz" appended, which would produce an unresolvable value.
+      {:ok, tag} = LanguageTag.new("en-u-rg-gbeng")
+      assert tag.canonical_locale_id == "en-u-rg-gbeng"
+
+      # The 2-letter region override form still round-trips with the filler.
+      {:ok, region} = LanguageTag.new("en-u-rg-uszzzz")
+      assert region.canonical_locale_id == "en-u-rg-uszzzz"
+    end
+
     test "preserves requested_locale_id" do
       {:ok, tag} = LanguageTag.new("EN-us")
       assert tag.requested_locale_id == "EN-us"

test/localize/language_test.exs

@@ -61,6 +61,31 @@ defmodule Localize.LanguageTest do
       assert {:ok, "Arabic"} == Language.display_name("ar-SA")
     end
 
+    # Per TR35 the display lookup canonicalizes but does not add likely
+    # subtags: a bare language keeps its own name, and only an explicitly
+    # supplied region/script resolves to a region-specific CLDR name.
+    test "a bare language is not maximized to a region-specific name" do
+      assert {:ok, "English"} == Language.display_name("en")
+      assert {:ok, "Spanish"} == Language.display_name("es")
+      assert {:ok, "Chinese"} == Language.display_name("zh")
+      assert {:ok, "Portuguese"} == Language.display_name("pt")
+
+      assert {:ok, "American English"} == Language.display_name("en-US")
+      assert {:ok, "Simplified Chinese"} == Language.display_name("zh-Hans")
+    end
+
+    # Per TR35, the candidate cascade tries lang-script before lang-region
+    # (the two-subtag tie is broken toward the earlier subtag). No CLDR
+    # language currently has both a lang-script and lang-region name, so the
+    # tie itself is untriggerable — but the reordering must not shadow a
+    # region-specific name (`en-GB`) behind the always-present maximized
+    # script candidate (`en-Latn`), nor break a script-specific name.
+    test "candidate order does not shadow region- or script-specific names" do
+      assert {:ok, "British English"} == Language.display_name("en-GB")
+      assert {:ok, "Traditional Chinese"} == Language.display_name("zh-Hant")
+      assert {:ok, "English"} == Language.display_name("en-IN")
+    end
+
     test "falls back to default locale when fallback is true" do
       # "ccp" (Chakma) may not exist in all locales but should be in :en
       assert {:ok, _name} = Language.display_name("ccp", locale: :de, fallback: true)

test/localize/locale/locale_display_test.exs

@@ -95,6 +95,23 @@ defmodule Localize.Locale.LocaleDisplayTest do
       assert {:ok, "English"} = Localize.Locale.LocaleDisplay.display_name("en")
     end
 
+    test "a string and an equivalent (maximized) language tag are equivalent" do
+      # Both inputs are routed through Localize.validate_locale/1 and the
+      # display is driven off canonical_locale_id, so no likely subtags leak.
+      for locale <- ["en", "en-US", "pt", "pt-BR", "zh-Hant"] do
+        {:ok, tag} = Localize.validate_locale(locale)
+
+        assert Localize.Locale.LocaleDisplay.display_name(locale) ==
+                 Localize.Locale.LocaleDisplay.display_name(tag)
+      end
+    end
+
+    test "a bare language does not gain a likely region" do
+      assert {:ok, "English"} = Localize.Locale.LocaleDisplay.display_name("en")
+      {:ok, tag} = Localize.validate_locale("en")
+      assert {:ok, "English"} = Localize.Locale.LocaleDisplay.display_name(tag)
+    end
+
     test "language with territory in standard mode" do
       assert {:ok, "English (United States)"} =
                Localize.Locale.LocaleDisplay.display_name("en-US")
@@ -166,7 +183,7 @@ defmodule Localize.Locale.LocaleDisplayTest do
     end
 
     test "raises on invalid input" do
-      assert_raise Localize.ParseError, fn ->
+      assert_raise Localize.InvalidLocaleError, fn ->
         Localize.Locale.LocaleDisplay.display_name!("xyz-invalid-totally-bad")
       end
     end