Use CLDR exemplar cities for timezone display names

Author: kipcole9

CHANGELOG.md

@@ -16,6 +16,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ### Fixed
 
+* Timezone display names use the exemplar city CLDR ships rather than one derived from the IANA identifier. The lookup matched `%{city: _}` where the zone data keys `:exemplar_city`, so it never fired: 48 zones in `en` and 190 in `ja` were named from the identifier instead, losing renames (`America/Godthab` is `"Nuuk"`), accents (`"Córdoba"`), and in non-Latin locales the script entirely.
+
+* Timezone display names resolve three-part identifiers such as `America/Indiana/Knox`, whose leaf CLDR keys by string one level deeper. They were split into two parts, so the lookup sought a city named `"Indiana/Knox"` and fell back to `"Knox"` rather than CLDR's `"Knox, Indiana"`.
+
 * `Localize.Number.Parser.scan/2` finds a grouped number written with an ordinary keyboard space in a locale that formats with U+202F. Under `fr`, `scan("1 234,5")` was `[1, " ", 234.5]` and is now `[1234.5]`.
 
 * `Localize.Number.parse/2` treats every character in `[:Zs:]` as a grouping space, per TR35's loose matching for lenient parsing. It previously accepted only U+0020 and the locale's own separator, so a `fr` number carrying U+00A0 or U+2009 — as copied out of formatted output — failed to parse.
@@ -24,6 +28,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 * `Localize.Number.parse/2` applies CLDR's `parseLenients` character folds, which were generated into the locale data but never read. The minus, plus, comma and full-stop families now fold to their canonical form, so the 18 locales writing `minusSign` as U+2212 — `fa`, `fi`, `sv` and `no` among them — parse their own negative numbers back. Per TR35 the fold applies to the locale's own separators as well as the input, which is what lets `de-CH` accept both spellings of its apostrophe group separator.
 
+### Added
+
+* `Localize.DateTime.Timezone.exemplar_city/3` returns the localized exemplar city for an IANA timezone identifier. `derive: false` returns an error rather than deriving a name from the identifier, distinguishing a name CLDR vouches for from one this library invented.
+
 ## [1.1.1] — August 16th, 2026
 
 ### Fixed

lib/localize/datetime/timezone.ex

@@ -773,6 +773,139 @@ defmodule Localize.DateTime.Timezone do
     end
   end
 
+  @doc """
+  Returns the exemplar city for an IANA timezone identifier.
+
+  CLDR names a representative city for most timezones — the city a
+  reader would recognise the zone by — localized, and sometimes
+  differing from the city in the identifier: `"America/Godthab"` is
+  `"Nuuk"`, which is what the place is now called.
+
+  ### Arguments
+
+  * `iana_id` is an IANA timezone identifier such as
+    `"America/Los_Angeles"` or `"America/Indiana/Knox"`.
+
+  * `locale` is a locale identifier or a `t:Localize.LanguageTag.t/0`.
+    The default is `Localize.get_locale/0`.
+
+  * `options` is a keyword list of options.
+
+  ### Options
+
+  * `:derive` determines what happens when CLDR names no exemplar city
+    for the zone. `true`, the default, derives one from the identifier,
+    so `"Pacific/Wallis"` yields `"Wallis"`. `false` returns an error
+    instead, which distinguishes a name CLDR vouches for from one this
+    library invented.
+
+  ### Returns
+
+  * `{:ok, city}`, or
+
+  * `{:error, exception}` if the locale is unknown, or if the zone has
+    no exemplar city and `derive: false` was given.
+
+  ### Examples
+
+      iex> Localize.DateTime.Timezone.exemplar_city("America/Los_Angeles", :en)
+      {:ok, "Los Angeles"}
+
+      iex> Localize.DateTime.Timezone.exemplar_city("America/Godthab", :en)
+      {:ok, "Nuuk"}
+
+      iex> Localize.DateTime.Timezone.exemplar_city("America/Indiana/Knox", :en)
+      {:ok, "Knox, Indiana"}
+
+      iex> Localize.DateTime.Timezone.exemplar_city("Atlantic/Azores", :de)
+      {:ok, "Azoren"}
+
+      iex> {:error, exception} =
+      ...>   Localize.DateTime.Timezone.exemplar_city("Neverwhere/Nowhere", :en, derive: false)
+      iex> exception.__struct__
+      Localize.UnknownTimezoneError
+
+  """
+  @spec exemplar_city(String.t(), Localize.locale(), Keyword.t()) ::
+          {:ok, String.t()} | {:error, Exception.t()}
+  def exemplar_city(iana_id, locale \\ Localize.get_locale(), options \\ [])
+
+  def exemplar_city(iana_id, locale, options) when is_binary(iana_id) do
+    with {:ok, language_tag} <- Localize.validate_locale(locale) do
+      zone =
+        case Localize.Locale.get(language_tag, [:dates, :time_zone_names]) do
+          {:ok, tz_data} -> Map.get(tz_data, :zone, %{})
+          {:error, _reason} -> %{}
+        end
+
+      case find_exemplar_city(iana_id, zone) do
+        nil -> derived_exemplar_city(iana_id, options)
+        city -> {:ok, city}
+      end
+    end
+  end
+
+  defp derived_exemplar_city(iana_id, options) do
+    with true <- Keyword.get(options, :derive, true),
+         city when is_binary(city) <- derive_city_from_id(iana_id) do
+      {:ok, city}
+    else
+      _no_city -> {:error, Localize.UnknownTimezoneError.exception(timezone: iana_id)}
+    end
+  end
+
+  # The zone data is structured as
+  # %{america: %{los_angeles: %{type: :zone, exemplar_city: "Los Angeles"}}}.
+  # A three-part identifier — "America/Indiana/Knox" — nests one level deeper,
+  # and CLDR keys that leaf by string rather than by atom.
+  defp find_exemplar_city(iana_id, zone) do
+    case String.split(iana_id, "/") do
+      [region, city] ->
+        exemplar_city_name(zone, [zone_key(region), zone_key(city)])
+
+      [region, group, city] ->
+        exemplar_city_name(zone, [zone_key(region), zone_key(group), leaf_key(city)])
+
+      _other ->
+        nil
+    end
+  end
+
+  defp exemplar_city_name(zone, keys) do
+    if Enum.all?(keys, & &1) do
+      case get_in(zone, keys) do
+        # A zone CLDR gives no exemplar city for carries only its long and
+        # short names.
+        %{exemplar_city: city_name} -> city_name
+        _other -> nil
+      end
+    end
+  end
+
+  # Gate atomisation on existing-atom membership. The zone data has
+  # pre-atomised keys for legitimate IANA components; an attacker-controlled
+  # `-u-tz-` extension value with an unknown region or city must not be allowed
+  # to grow the atom table.
+  defp zone_key(component) do
+    component
+    |> leaf_key()
+    |> Localize.Utils.Helpers.existing_atom()
+  end
+
+  defp leaf_key(component) do
+    component
+    |> String.downcase()
+    |> String.replace(" ", "_")
+  end
+
+  # "America/Los_Angeles" -> "Los Angeles", "America/Argentina/Salta" -> "Salta"
+  defp derive_city_from_id(iana_id) do
+    case String.split(iana_id, "/") do
+      [_single_component] -> nil
+      parts -> parts |> List.last() |> String.replace("_", " ")
+    end
+  end
+
   defp pad(integer, n) when is_integer(integer) do
     str = Integer.to_string(integer)
     padding = n - String.length(str)

lib/localize/locale/locale_display/u.ex

@@ -4,6 +4,8 @@ defmodule Localize.Locale.LocaleDisplay.U do
   import Localize.Locale.LocaleDisplay,
     only: [get_display_preference: 2, join_field_values: 2, replace_nested_brackets: 2]
 
+  alias Localize.DateTime.Timezone
+
   # Mapping from BCP47 U extension struct field atoms to the
   # CLDR key names used in locale_display_names[:keys] and [:types].
   # Fields not in this map use the field atom directly.
@@ -321,21 +323,12 @@ defmodule Localize.Locale.LocaleDisplay.U do
   # 4. Format using the locale's regionFormat pattern
   #    (e.g., "{0} Time").
   defp get_timezone_display_name(iana_id, locale_id) when is_binary(iana_id) do
-    alias Localize.DateTime.Timezone
-
     case Localize.Locale.get(locale_id, [:dates, :time_zone_names]) do
       {:ok, tz_data} ->
         region_format = get_in(tz_data, [:region_format, :generic])
         territory = Map.get(Timezone.territories_by_timezone(), iana_id)
 
-        location =
-          if territory && Timezone.timezone_count_for_territory(territory) == {:ok, 1} do
-            # If the territory has a single timezone, use the country name
-            get_territory_name(territory, locale_id)
-          else
-            # Otherwise use the exemplar city
-            find_exemplar_city(iana_id, tz_data) || derive_city_from_id(iana_id)
-          end
+        location = timezone_location(iana_id, territory, locale_id)
 
         if location && region_format do
           Localize.Substitution.substitute(location, region_format)
@@ -349,6 +342,20 @@ defmodule Localize.Locale.LocaleDisplay.U do
     end
   end
 
+  # Steps 2 and 3 of the non-location format algorithm: a territory with only
+  # one timezone is named by the country, and anything else by the zone's
+  # exemplar city.
+  defp timezone_location(iana_id, territory, locale_id) do
+    if territory && Timezone.timezone_count_for_territory(territory) == {:ok, 1} do
+      get_territory_name(territory, locale_id)
+    else
+      case Timezone.exemplar_city(iana_id, locale_id) do
+        {:ok, city} -> city
+        {:error, _reason} -> nil
+      end
+    end
+  end
+
   # Look up the display name for a territory.
   defp get_territory_name(territory, locale_id) do
     case Localize.Territory.display_name(territory, locale: locale_id) do
@@ -357,57 +364,6 @@ defmodule Localize.Locale.LocaleDisplay.U do
     end
   end
 
-  # Look up an explicit exemplar city in the zone data.
-  # The zone data is structured as %{america: %{los_angeles: %{city: "Los Angeles"}, ...}}
-  defp find_exemplar_city(iana_id, tz_data) do
-    zone = Map.get(tz_data, :zone, %{})
-
-    case String.split(iana_id, "/", parts: 2) do
-      [region, city] ->
-        # Gate atomisation on existing-atom membership. The zone data
-        # has pre-atomised keys for legitimate IANA components; an
-        # attacker-controlled `-u-tz-` extension value with unknown
-        # region or city must not be allowed to grow the atom table.
-        region_key = region |> String.downcase() |> Localize.Utils.Helpers.existing_atom()
-
-        city_key =
-          city
-          |> String.downcase()
-          |> String.replace(" ", "_")
-          |> Localize.Utils.Helpers.existing_atom()
-
-        exemplar_city_name(zone, region_key, city_key)
-
-      _ ->
-        nil
-    end
-  end
-
-  defp exemplar_city_name(zone, region_key, city_key) do
-    if region_key && city_key do
-      case get_in(zone, [region_key, city_key]) do
-        %{city: city_name} -> city_name
-        _ -> nil
-      end
-    end
-  end
-
-  # Derive city display name from IANA timezone ID.
-  # "America/Los_Angeles" → "Los Angeles"
-  # "Europe/London" → "London"
-  # "America/Argentina/Buenos_Aires" → "Buenos Aires"
-  defp derive_city_from_id(iana_id) do
-    case String.split(iana_id, "/") do
-      [_] ->
-        nil
-
-      parts ->
-        parts
-        |> List.last()
-        |> String.replace("_", " ")
-    end
-  end
-
   # Validity values for deprecated spellings are tagged
   # `{:deprecated, preferred}`; display always uses the preferred
   # form.

test/localize/locale/locale_display_u_test.exs

@@ -47,6 +47,43 @@ defmodule Localize.Locale.LocaleDisplayUTest do
     end
   end
 
+  # Step 3 of CLDR's non-location format algorithm uses the zone's exemplar
+  # city. The zone data keys that `:exemplar_city`, but the lookup matched
+  # `%{city: _}`, so it never fired and every zone fell through to a city name
+  # derived from the IANA id instead — 48 zones in `en` and 190 in `ja`.
+  describe "display_name/2 -u-tz- exemplar cities" do
+    test "uses CLDR's exemplar city rather than one derived from the IANA id" do
+      # CLDR renamed this city; the IANA id still says Godthab.
+      assert {:ok, "English (Time Zone: Nuuk Time)"} =
+               LocaleDisplay.display_name("en-u-tz-glgoh")
+
+      assert {:ok, "Deutsch (Zeitzone: Nuuk [Ortszeit])"} =
+               LocaleDisplay.display_name("de-u-tz-glgoh", locale: :de)
+    end
+
+    test "keeps the accents that deriving from the id would drop" do
+      assert {:ok, "Deutsch (Zeitzone: Azoren [Ortszeit])"} =
+               LocaleDisplay.display_name("de-u-tz-ptpdl", locale: :de)
+    end
+
+    test "descends into a three-part zone id, whose leaf CLDR keys by string" do
+      # "America/Indiana/Knox" — splitting into two parts looked for a city
+      # named "Indiana/Knox", so the qualifier CLDR adds was lost.
+      assert {:ok, "English (Time Zone: Knox, Indiana Time)"} =
+               LocaleDisplay.display_name("en-u-tz-usknx")
+
+      assert {:ok, "Deutsch (Zeitzone: R\u00edo Gallegos [Ortszeit])"} =
+               LocaleDisplay.display_name("de-u-tz-arrgl", locale: :de)
+    end
+
+    test "an unknown zone still falls back to a name derived from the id" do
+      # A zone CLDR has no exemplar city for, and an unknown one, must both
+      # degrade rather than raise — and must not grow the atom table.
+      assert {:ok, "English (Time Zone: UTC Time)"} =
+               LocaleDisplay.display_name("en-u-tz-utc")
+    end
+  end
+
   describe "display_name/2 -u- key ordering and composition" do
     test "multiple keys are displayed sorted by BCP47 key, not input order" do
       # Input order is ca, nu, hc but display order is ca, hc, nu.