MF2 signDisplay, implicit locale-aware number formatting, and re-annotation on original values

Author: kipcole9

CHANGELOG.md

@@ -12,10 +12,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 * The MessageFormat working group's `:test:function`, `:test:format` and `:test:select` registry functions are implemented, so the WG conformance suite's selection-mechanics and fallback cases now run.
 
+* The MF2 numeric functions accept the `signDisplay` option (`auto`, `always`, `exceptZero`, `negative`, `never`), with the plus sign taken from the locale's number symbols.
+
+* An MF2 pattern expression that re-annotates a declared variable operates on the declaration's original value, and numeric functions inherit unset options from a numeric declaration — `.local $x = {41 :integer signDisplay=always}` rendered with `{$x :offset add=1}` produces "+42".
+
 * The locale download base URL can be overridden with `config :localize, locale_base_url: "..."` for deployments mirroring the locale files; downloads are verified against the bundled hash manifest regardless of source.
 
 ### Changed
 
+* An unannotated MF2 placeholder with a numeric operand formats with the locale-aware `:number` default (`{$pi}` renders "3.142" in en and "3,142" in fr), matching the MF2 implicit formatting rules; previously the value was stringified verbatim.
+
 * MessageFormat 2 follows the specification's error semantics: unknown functions are an error (`Localize.FormatError` reason `:unknown_function`) instead of formatting the operand, and data-model validation rejects duplicate declarations, duplicate option names, and duplicate variants (NFC-normalized keys) with dedicated error reasons.
 
 * MessageFormat 2 function validation is strict per TR35: the `select` option must be a literal set directly on the selector expression, digit-size options must be non-negative integers, string operands of numeric functions must match the `number-literal` production, and `:currency`, `:unit`, `:date`, `:time` and `:datetime` are rejected as selectors.

guides/conformance.md

@@ -460,7 +460,7 @@ Two areas are explicitly out of scope:
 | Feature | Status | Notes |
 |---------|--------|-------|
 | `:string` | Implemented | |
-| `:number` | Implemented | Delegates to `Localize.Number.to_string/2`. |
+| `:number` | Implemented | Delegates to `Localize.Number.to_string/2`. All numeric functions support `signDisplay`, and an unannotated numeric operand formats with the locale-aware `:number` default. |
 | `:integer` | Implemented | |
 | `:percent` | Implemented | |
 | `:currency` | Implemented | |
@@ -496,16 +496,10 @@ Two areas are explicitly out of scope:
 
 The MessageFormat working group conformance suite — including the WG `:test:function` / `:test:format` / `:test:select` registry functions it uses to exercise selection mechanics — runs against both the parser and the formatter (`test/localize/message/formatter_conformance_test.exs`). The few cases the implementation cannot yet satisfy are excluded there, each with a documented reason:
 
-* Declarations bind the formatted string, so re-annotating an already-annotated variable in a later declaration fails (one case each in the currency, date, time and percent suites).
-
 * The `u:dir` / `u:id` expression *options* are not implemented (the `@u:dir` attribute form is).
 
 * The `:isolate` bidi strategy isolates every placeholder where the WG default strategy leaves known-LTR placeholders unisolated (three cases).
 
-* The `:offset` function's `signDisplay` option is not implemented (two cases).
-
-* Unannotated number operands are not implicitly formatted with the locale-aware `:number` function (one case).
-
 ---
 
 ## Summary

lib/localize/message/interpreter.ex

@@ -156,6 +156,7 @@ defmodule Localize.Message.Interpreter do
         {:error, [], [], [var_name]}
 
       {bindings, bound, selector_meta} ->
+        options = Keyword.put(options, :declaration_meta, selector_meta)
         format_complex_body(body, bindings, options, bound, selector_meta)
     end
   end
@@ -403,6 +404,8 @@ defmodule Localize.Message.Interpreter do
         {:error, [], [], [var_name]}
 
       {bindings, bound, selector_meta} ->
+        options = Keyword.put(options, :declaration_meta, selector_meta)
+
         case body do
           {:quoted_pattern, parts} ->
             structured_pattern(parts, bindings, options, bound)
@@ -720,6 +723,8 @@ defmodule Localize.Message.Interpreter do
   defp format_expression(operand, func, bindings, options) do
     case resolve_operand(operand, bindings) do
       {:ok, value, bound_names} ->
+        {value, func} = reannotate_from_declaration(operand, value, func, options)
+
         case apply_function(value, func, Keyword.put(options, :bindings, bindings)) do
           {:ok, formatted} -> {:ok, formatted, bound_names}
           {:unbound, var_name} -> {:unbound, var_name}
@@ -732,6 +737,40 @@ defmodule Localize.Message.Interpreter do
     end
   end
 
+  # A pattern expression that re-annotates a declared variable
+  # operates on the declaration's original (unformatted) value —
+  # not the formatted string the declaration bound — and a numeric
+  # function inherits unset options from a numeric declaration, so
+  # `.local $x = {41 :integer signDisplay=always}` rendered with
+  # `{$x :offset add=1}` produces "+42".
+  defp reannotate_from_declaration({:variable, name}, value, {:function, _, _} = func, options) do
+    case options |> Keyword.get(:declaration_meta, %{}) |> Map.get(name) do
+      {original, declared_func} ->
+        {original, merge_declared_options(normalize_function(func), declared_func)}
+
+      nil ->
+        {value, func}
+    end
+  end
+
+  defp reannotate_from_declaration(_operand, value, func, _options) do
+    {value, func}
+  end
+
+  defp merge_declared_options(
+         {:function, name, options},
+         {:function, declared_name, declared_options}
+       )
+       when name in ["number", "integer", "offset", "percent", "currency"] and
+              declared_name in ["number", "integer", "offset", "percent", "currency"] do
+    merged = Enum.uniq_by(options ++ declared_options, fn {:option, key, _value} -> key end)
+    {:function, name, merged}
+  end
+
+  defp merge_declared_options(func, _declared_func) do
+    func
+  end
+
   defp resolve_operand(nil, _bindings) do
     {:ok, nil, []}
   end
@@ -753,6 +792,16 @@ defmodule Localize.Message.Interpreter do
 
   # ── Function dispatch ──────────────────────────────────────────
 
+  defp apply_function(value, nil, options) when is_number(value) do
+    # An unannotated placeholder with a numeric operand formats with
+    # the locale-aware default, as if annotated with `:number`.
+    Localize.Number.to_string(value, resolve_locale_options(options))
+  end
+
+  defp apply_function(%Decimal{} = value, nil, options) do
+    Localize.Number.to_string(value, resolve_locale_options(options))
+  end
+
   defp apply_function(value, nil, _options) do
     {:ok, to_string_value(value)}
   end
@@ -817,38 +866,36 @@ defmodule Localize.Message.Interpreter do
   defp format_with_function("number", value, func_opts, options) do
     with {:ok, number} <- ensure_number(value),
          {:ok, options_struct} <- build_number_options(options, func_opts) do
-      Localize.Number.to_string(number, set_number_pattern(options_struct, number))
+      format_number_result(number, options_struct, func_opts)
     end
   end
 
   defp format_with_function("integer", value, func_opts, options) do
     with {:ok, number} <- ensure_number(value),
          {:ok, options_struct} <- build_number_options(options, func_opts) do
-      integer = trunc(number)
-      Localize.Number.to_string(integer, set_number_pattern(options_struct, integer))
+      format_number_result(trunc(number), options_struct, func_opts)
     end
   end
 
   defp format_with_function("offset", value, func_opts, options) do
     with {:ok, number} <- ensure_number(value),
          {:ok, adjustment} <- offset_adjustment(func_opts),
          {:ok, options_struct} <- build_number_options(options, func_opts) do
-      adjusted = apply_offset(number, adjustment)
-      Localize.Number.to_string(adjusted, set_number_pattern(options_struct, adjusted))
+      format_number_result(apply_offset(number, adjustment), options_struct, func_opts)
     end
   end
 
   defp format_with_function("percent", value, func_opts, options) do
     with {:ok, number} <- ensure_number(value),
          {:ok, options_struct} <- build_number_options(options, func_opts, format: :percent) do
-      Localize.Number.to_string(number, set_number_pattern(options_struct, number))
+      format_number_result(number, options_struct, func_opts)
     end
   end
 
   defp format_with_function("currency", value, func_opts, options) do
     with {:ok, number} <- ensure_number(value),
          {:ok, options_struct} <- build_currency_options(options, func_opts) do
-      Localize.Number.to_string(number, set_number_pattern(options_struct, number))
+      format_number_result(number, options_struct, func_opts)
     end
   end
 
@@ -1037,6 +1084,76 @@ defmodule Localize.Message.Interpreter do
   defp to_float(%Decimal{} = number), do: Decimal.to_float(number)
   defp to_float(number) when is_number(number), do: number * 1.0
 
+  # Formats a resolved numeric value honouring the MF2 `signDisplay`
+  # option (auto | always | exceptZero | negative | never). The plus
+  # sign comes from the locale's number symbols.
+  defp format_number_result(number, options_struct, func_opts) do
+    with {:ok, sign_display} <- sign_display_option(func_opts) do
+      format_with_sign_display(number, options_struct, sign_display)
+    end
+  end
+
+  defp format_with_sign_display(number, options_struct, "auto") do
+    Localize.Number.to_string(number, set_number_pattern(options_struct, number))
+  end
+
+  defp format_with_sign_display(number, options_struct, "never") do
+    magnitude = number_abs(number)
+    Localize.Number.to_string(magnitude, set_number_pattern(options_struct, magnitude))
+  end
+
+  defp format_with_sign_display(number, options_struct, "always") do
+    if number_negative?(number) do
+      format_with_sign_display(number, options_struct, "auto")
+    else
+      with {:ok, formatted} <- format_with_sign_display(number, options_struct, "auto") do
+        {:ok, plus_sign(options_struct) <> formatted}
+      end
+    end
+  end
+
+  defp format_with_sign_display(number, options_struct, "exceptZero") do
+    cond do
+      number_zero?(number) -> format_with_sign_display(number, options_struct, "never")
+      number_negative?(number) -> format_with_sign_display(number, options_struct, "auto")
+      true -> format_with_sign_display(number, options_struct, "always")
+    end
+  end
+
+  defp format_with_sign_display(number, options_struct, "negative") do
+    if number_zero?(number) do
+      format_with_sign_display(number, options_struct, "never")
+    else
+      format_with_sign_display(number, options_struct, "auto")
+    end
+  end
+
+  defp sign_display_option(func_opts) do
+    case func_opts[:signDisplay] || func_opts["signDisplay"] do
+      nil ->
+        {:ok, "auto"}
+
+      value when value in ["auto", "always", "exceptZero", "negative", "never"] ->
+        {:ok, value}
+
+      value ->
+        {:error,
+         "the signDisplay option must be one of auto, always, exceptZero, negative " <>
+           "or never, got #{inspect(value)}"}
+    end
+  end
+
+  defp plus_sign(%{symbols: %{plus_sign: plus}}), do: plus
+
+  defp number_negative?(%Decimal{sign: sign}), do: sign < 0
+  defp number_negative?(number), do: number < 0
+
+  defp number_zero?(%Decimal{} = decimal), do: Decimal.equal?(decimal, 0)
+  defp number_zero?(number), do: number == 0
+
+  defp number_abs(%Decimal{} = decimal), do: Decimal.abs(decimal)
+  defp number_abs(number), do: abs(number)
+
   defp resolve_custom_function(name, options) do
     per_call = Keyword.get(options, :functions, %{})
 

plans/RELEASE_1.0_READINESS_2026-07-15.md

@@ -87,7 +87,7 @@ The July 4 plan is almost entirely executed. Milestones 1–3 are done and verif
 Updated July 15 (second pass): items 1, 2, 4, 5, 6, 7, 8, and 10–13 are all done as annotated above. Remaining:
 
 1. Item 3 — delegate removal timing: decide whether 1.0 removes all deprecated delegates (the known_/available_ set, Duration `:style`, and the new Currency positional forms) in one sweep or carries them to a later release. All messages promise removal by 1.0 and no later than December 2026.
-2. The MF2 additive bucket (post-1.0 candidates or pre-1.0 polish): re-annotation of annotated variables (declarations bind formatted strings — an interpreter design change), `u:dir`/`u:id` expression options, WG-default bidi strategy, `:offset` `signDisplay`, implicit locale-aware number formatting of unannotated operands.
+2. The MF2 additive bucket — mostly CLOSED July 15 (third pass): `signDisplay` on all numeric functions, implicit locale-aware `:number` formatting of unannotated numeric operands, and re-annotation of declared variables (pattern expressions operate on the declaration's original value with numeric option inheritance). Remaining: `u:dir`/`u:id` expression options and the WG-default bidi strategy (five excluded suite cases in total).
 3. Item 9 — `localize_mcp` release (repo, review, hex publish); README MCP section.
 4. Full house release review; 1.0.0-rc.1; soak; 1.0.0.
 

test/localize/message/formatter_conformance_test.exs

@@ -77,35 +77,12 @@ defmodule Localize.Message.FormatterConformanceTest do
   # Every exclusion is a real, documented implementation gap; the
   # remaining cases in each file are asserted.
   @exclusion_groups %{
-    "syntax.json" => %{
-      "known gap: unannotated number operands are not implicitly formatted with the locale-aware :number function" =>
-        [90]
-    },
     "bidi.json" => %{
       "WG default bidi strategy leaves known-LTR placeholders unisolated; :isolate wraps all placeholders" =>
         [16, 19, 20]
     },
     "u-options.json" => %{
       "u:dir/u:id expression options not implemented" => [1, 2, 3, 5, 6, 8]
-    },
-    "functions/currency.json" => %{
-      "known gap: declarations bind the formatted string, so re-annotating an annotated variable fails" =>
-        [7]
-    },
-    "functions/date.json" => %{
-      "known gap: declarations bind the formatted string, so re-annotating an annotated variable fails" =>
-        [6]
-    },
-    "functions/offset.json" => %{
-      "known gap: signDisplay option not implemented" => [10, 11]
-    },
-    "functions/percent.json" => %{
-      "known gap: declarations bind the formatted string, so re-annotating an annotated variable fails" =>
-        [5]
-    },
-    "functions/time.json" => %{
-      "known gap: declarations bind the formatted string, so re-annotating an annotated variable fails" =>
-        [5]
     }
   }
 

test/localize/message/sigils_test.exs

@@ -239,7 +239,10 @@ defmodule Localize.Message.SigilsTest do
     end
 
     test "remote call on an atom module derives mod_fun" do
-      assert AssignsFixture.atom_module_call() =~ "Pi is 3.14159"
+      # An unannotated numeric operand formats with the locale-aware
+      # :number default (at most three fraction digits, matching the
+      # MF2 implicit formatting behaviour and Intl.NumberFormat).
+      assert AssignsFixture.atom_module_call() =~ "Pi is 3.142"
     end
 
     test "nested dot access not rooted at assigns raises" do