feat(i18n): define UI localization catalog domain policy

backend/tests/test_ui_localization_bcp47_extension_singletons.py

@@ -0,0 +1,21 @@
+"""RFC 5646 extension-singleton regressions for explicit locale preferences."""
+
+import pytest
+
+from services.ui_localization_policy import (
+    UiLocalizationValidationError,
+    normalize_supported_locale,
+)
+
+
+@pytest.mark.parametrize("locale_tag", ("en-a-bbb-a-ccc", "EN-A-bbb-a-ccc"))
+def test_explicit_locale_rejects_repeated_extension_singleton(locale_tag):
+    """RFC 5646 forbids repeating an extension singleton outside private use."""
+    with pytest.raises(UiLocalizationValidationError) as caught:
+        normalize_supported_locale(locale_tag)
+    assert caught.value.error_code == "ui_locale_input_invalid"
+
+
+def test_private_use_may_repeat_extension_letter_after_x():
+    """Singleton-shaped private-use data is not a repeated extension singleton."""
+    assert normalize_supported_locale("en-a-bbb-x-a-ccc") == "en"

backend/tests/test_ui_localization_bcp47_well_formedness.py

@@ -0,0 +1,79 @@
+"""BCP 47 well-formedness regressions for explicit locale preferences."""
+
+import pytest
+
+from services.ui_localization_policy import (
+    UiLocalizationValidationError,
+    normalize_supported_locale,
+)
+
+
+@pytest.mark.parametrize("locale_tag", ("en-x", "en-u"))
+def test_explicit_locale_rejects_terminal_extension_or_private_use_singletons(locale_tag):
+    """A supported primary language does not make a malformed RFC 5646 suffix valid."""
+    with pytest.raises(UiLocalizationValidationError) as caught:
+        normalize_supported_locale(locale_tag)
+    assert caught.value.error_code == "ui_locale_input_invalid"
+
+
+@pytest.mark.parametrize("locale_tag", (" en-US", "en-US ", " en-US "))
+def test_explicit_locale_rejects_surrounding_spaces(locale_tag):
+    """RFC 5646 language-tag syntax does not permit SP around an explicit locale value."""
+    with pytest.raises(UiLocalizationValidationError) as caught:
+        normalize_supported_locale(locale_tag)
+    assert caught.value.error_code == "ui_locale_input_invalid"
+
+
+@pytest.mark.parametrize("locale_tag", ("en-x-private", "en-u-ca-gregory"))
+def test_explicit_locale_accepts_well_formed_private_use_and_extension_suffixes(locale_tag):
+    """Valid RFC 5646 suffixes remain compatible with release-level locale normalization."""
+    assert normalize_supported_locale(locale_tag) == "en"
+
+
+@pytest.mark.parametrize(
+    ("locale_tag", "expected_locale"),
+    (
+        ("en-GB-oed", "en"),
+        ("zh-min", "zh"),
+        ("zh-min-nan", "zh"),
+    ),
+)
+def test_explicit_locale_accepts_supported_primary_grandfathered_language_tags(
+    locale_tag,
+    expected_locale,
+):
+    """RFC 5646 grandfathered tags remain Language-Tag values even outside langtag ABNF."""
+    assert normalize_supported_locale(locale_tag) == expected_locale
+
+
+@pytest.mark.parametrize("locale_tag", ("x-private", "i-klingon", "sgn-BE-FR"))
+def test_well_formed_language_tags_without_supported_primary_are_unsupported(locale_tag):
+    """Well-formed private-use/irregular tags are unsupported, not syntactically invalid."""
+    with pytest.raises(UiLocalizationValidationError) as caught:
+        normalize_supported_locale(locale_tag)
+    assert caught.value.error_code == "ui_locale_unsupported"
+
+
+@pytest.mark.parametrize("locale_tag", ("en-1901-1901", "en-oxendict-OXENDICT"))
+def test_explicit_locale_rejects_duplicate_variant_subtags(locale_tag):
+    """RFC 5646 validity forbids duplicate variant subtags case-insensitively."""
+    with pytest.raises(UiLocalizationValidationError) as caught:
+        normalize_supported_locale(locale_tag)
+    assert caught.value.error_code == "ui_locale_input_invalid"
+
+
+def test_duplicate_variant_spelling_inside_private_use_is_not_a_variant_duplicate():
+    """Private-use subtags do not participate in the duplicate-variant validity rule."""
+    assert normalize_supported_locale("en-1901-x-1901") == "en"
+
+
+def test_explicit_locale_rejects_more_than_one_extlang_subtag():
+    """RFC 5646 reserves second and third extlang positions as permanently invalid."""
+    with pytest.raises(UiLocalizationValidationError) as caught:
+        normalize_supported_locale("zh-cmn-yue")
+    assert caught.value.error_code == "ui_locale_input_invalid"
+
+
+def test_explicit_locale_accepts_one_extlang_with_following_structural_subtags():
+    """One extlang remains valid before script and region subtags."""
+    assert normalize_supported_locale("zh-cmn-Hans-CN") == "zh"

backend/tests/test_ui_localization_content_resource_bounds.py

@@ -0,0 +1,67 @@
+"""Resource-bound regressions for translation text and placeholder metadata."""
+
+import pytest
+
+from services.ui_localization_policy import (
+    UiLocalizationValidationError,
+    extract_placeholder_names,
+    validate_translation_placeholders,
+)
+
+
+def assert_error(code, callable_):
+    """Assert one stable localization validation code from a failing call."""
+    with pytest.raises(UiLocalizationValidationError) as caught:
+        callable_()
+    assert caught.value.error_code == code
+
+
+def test_translation_text_character_budget_is_bounded_before_placeholder_work():
+    """UI copy accepts 16,384 characters and rejects the next character without truncation."""
+    assert extract_placeholder_names("가" * 16_384) == ()
+    assert_error(
+        "ui_translation_input_invalid",
+        lambda: extract_placeholder_names("가" * 16_385),
+    )
+
+
+def test_placeholder_name_character_budget_is_bounded():
+    """Versioned placeholder identities accept 64 characters and reject the 65th."""
+    accepted_name = "a" + ("b" * 63)
+    rejected_name = accepted_name + "c"
+
+    assert validate_translation_placeholders(
+        "{" + accepted_name + "}",
+        (accepted_name,),
+    ) == (accepted_name,)
+    assert_error(
+        "ui_placeholder_schema_invalid",
+        lambda: validate_translation_placeholders(
+            "{" + rejected_name + "}",
+            (rejected_name,),
+        ),
+    )
+
+
+def test_placeholder_schema_item_budget_is_bounded_before_collection_copy():
+    """A catalog message accepts 32 unique placeholders and rejects the 33rd."""
+    accepted_schema = tuple(f"field_{index}" for index in range(32))
+    accepted_message = " ".join(f"{{{name}}}" for name in accepted_schema)
+    rejected_schema = (*accepted_schema, "field_32")
+    rejected_message = accepted_message + " {field_32}"
+
+    assert validate_translation_placeholders(
+        accepted_message,
+        accepted_schema,
+    ) == accepted_schema
+    assert_error(
+        "ui_placeholder_schema_invalid",
+        lambda: validate_translation_placeholders(
+            rejected_message,
+            rejected_schema,
+        ),
+    )
+    assert_error(
+        "ui_placeholder_schema_invalid",
+        lambda: extract_placeholder_names(rejected_message),
+    )

backend/tests/test_ui_localization_http_whitespace.py

@@ -0,0 +1,125 @@
+"""HTTP/locale whitespace regressions for the UI Localization Catalog policy."""
+
+import pytest
+
+from services.ui_localization_policy import (
+    UiLocalizationValidationError,
+    normalize_supported_locale,
+    select_ui_locale,
+)
+
+
+def assert_error(code, callable_):
+    """Assert a stable localization validation code from one failing call."""
+    with pytest.raises(UiLocalizationValidationError) as caught:
+        callable_()
+    assert caught.value.error_code == code
+
+
+@pytest.mark.parametrize(
+    "locale_tag",
+    (
+        "\ten-US",
+        "en-US\v",
+        "\fen-US",
+        "\u00a0en-US",
+    ),
+)
+def test_explicit_locale_rejects_control_and_unicode_boundary_whitespace(locale_tag):
+    """HTAB, VT, FF, and NBSP cannot surround an explicit locale identity."""
+    assert_error("ui_locale_input_invalid", lambda: normalize_supported_locale(locale_tag))
+
+
+@pytest.mark.parametrize(
+    "header_value",
+    (
+        "\ven-US",
+        "en-US\f",
+        "en-US\v;q=0.8",
+        "en-US;\fq=0.8",
+        "\u00a0en-US",
+    ),
+)
+def test_accept_language_rejects_non_http_whitespace(header_value):
+    """VT, FF, and Unicode whitespace are not RFC 9110 OWS and fail closed."""
+    assert_error(
+        "ui_accept_language_invalid",
+        lambda: select_ui_locale(accept_language=header_value),
+    )
+
+
+def test_accept_language_allows_only_sp_and_htab_as_ows():
+    """RFC 9110 OWS remains accepted around list members and q-weights."""
+    selected = select_ui_locale(accept_language="\ten-US\t,\tfr ;\tq=0.5\t")
+    assert (selected.locale_code, selected.selection_source) == ("en", "accept_language")
+
+
+def test_accept_language_quality_parameter_name_is_case_insensitive():
+    """RFC 9110 defines the q parameter name as case-insensitive."""
+    selected = select_ui_locale(accept_language="fr;Q=0.4, en;q=0.8")
+    assert (selected.locale_code, selected.selection_source) == ("en", "accept_language")
+
+    selected = select_ui_locale(accept_language="fr;Q=0.9, en;q=0.8")
+    assert (selected.locale_code, selected.selection_source) == ("fr", "accept_language")
+
+
+def test_accept_language_ignores_reasonable_empty_list_elements():
+    """RFC 9110 recipients ignore empty members introduced while list values are merged."""
+    selected = select_ui_locale(accept_language=", fr;q=0.4, , en;q=0.8,")
+    assert (selected.locale_code, selected.selection_source) == ("en", "accept_language")
+
+    selected = select_ui_locale(accept_language=",")
+    assert (selected.locale_code, selected.selection_source) == ("ko", "product_default")
+
+
+def test_accept_language_bounds_empty_list_elements_against_dos():
+    """Only a bounded reasonable number of empty RFC 9110 list members is ignored."""
+    accepted = ",".join([""] * 32 + ["en"])
+    selected = select_ui_locale(accept_language=accepted)
+    assert (selected.locale_code, selected.selection_source) == ("en", "accept_language")
+
+    excessive = ",".join([""] * 33 + ["en"])
+    assert_error(
+        "ui_accept_language_invalid",
+        lambda: select_ui_locale(accept_language=excessive),
+    )
+
+
+def test_locale_and_accept_language_have_explicit_resource_bounds():
+    """Valid basic ranges cannot create unbounded parser work at product boundaries."""
+    locale_at_limit = "en-" + "-".join(f"var{index:05d}" for index in range(14))
+    assert len(locale_at_limit) == 128
+    assert normalize_supported_locale(locale_at_limit) == "en"
+
+    locale_over_limit = locale_at_limit + "-abcdefgh"
+    assert_error(
+        "ui_locale_input_invalid",
+        lambda: normalize_supported_locale(locale_over_limit),
+    )
+
+    accepted_members = ",".join(["pt"] * 64)
+    selected = select_ui_locale(accept_language=accepted_members)
+    assert (selected.locale_code, selected.selection_source) == ("ko", "product_default")
+
+    excessive_members = ",".join(["pt"] * 65)
+    assert_error(
+        "ui_accept_language_invalid",
+        lambda: select_ui_locale(accept_language=excessive_members),
+    )
+
+    header_at_limit = "en-" + "-".join(["abcdefgh"] * 910)
+    assert len(header_at_limit) == 8192
+    selected = select_ui_locale(accept_language=header_at_limit)
+    assert (selected.locale_code, selected.selection_source) == ("en", "accept_language")
+
+    header_over_limit = header_at_limit + "-abcdefgh"
+    assert_error(
+        "ui_accept_language_invalid",
+        lambda: select_ui_locale(accept_language=header_over_limit),
+    )
+
+
+def test_wildcard_before_unsupported_range_does_not_claim_negotiation_source():
+    """RFC 4647 lookup skips a wildcard when any later concrete range remains to try."""
+    selected = select_ui_locale(accept_language="*;q=0.9, pt-BR;q=0.8")
+    assert (selected.locale_code, selected.selection_source) == ("ko", "product_default")

backend/tests/test_ui_localization_identity_bounds.py

@@ -0,0 +1,41 @@
+"""Resource-bound regressions for UI Localization Catalog identities."""
+
+import pytest
+
+from services.ui_localization_policy import (
+    UiLocalizationValidationError,
+    validate_message_key,
+    validate_screen_key,
+)
+
+
+def assert_error(code, callable_):
+    """Assert a stable localization validation code from one failing call."""
+    with pytest.raises(UiLocalizationValidationError) as caught:
+        callable_()
+    assert caught.value.error_code == code
+
+
+def test_screen_key_has_explicit_product_length_bound():
+    """A syntactically valid screen identity cannot create unbounded catalog/index work."""
+    screen_key_at_limit = "a." + ("b" * 126)
+    assert len(screen_key_at_limit) == 128
+    assert validate_screen_key(screen_key_at_limit) == screen_key_at_limit
+
+    screen_key_over_limit = screen_key_at_limit + "b"
+    assert_error(
+        "ui_screen_key_invalid",
+        lambda: validate_screen_key(screen_key_over_limit),
+    )
+
+
+def test_message_key_has_explicit_product_length_bound():
+    """A syntactically valid message identity cannot grow without a product ceiling."""
+    message_key_at_limit = "m" * 128
+    assert validate_message_key(message_key_at_limit) == message_key_at_limit
+
+    message_key_over_limit = message_key_at_limit + "m"
+    assert_error(
+        "ui_message_key_invalid",
+        lambda: validate_message_key(message_key_over_limit),
+    )