Internationalization: User behavior specification

Specifies locale selection, formatting, translation fallback, bidirectional layout, and persistence so users receive predictable language behavior without mixed or silently guessed interfaces.

Package status: reference context ready for human review. The contract and test scenarios are complete, but no claim is made that an adopting implementation has passed them.

Decision

Separate interface language from regional formatting. Resolve both from an explicit user preference first, then an application default; browser signals may seed a first visit but must not overwrite a saved choice.

Scope

• Language and region selection, persistence, fallback, formatting, and bidirectional layout.
• Missing-message and unsupported-locale behavior visible to users and operators.
• URL, account, and anonymous-session behavior for locale preferences.

Outside this block

• Machine translation or the editorial translation workflow.
• Legal decisions about which locales the product must support.

Contract

• Language uses a BCP 47 locale identifier and region-sensitive formatting uses a separately resolved locale when configured.
• A user-selected locale persists across sessions and devices for signed-in users.
• Fallback is deterministic: exact locale, configured parent, product default; raw message keys never appear to users.
• Dates, numbers, plural forms, and currencies use locale-aware formatters; stored values remain locale-neutral.
• Right-to-left locales set document direction and mirror directional layout without mirroring semantic media or numeric input.
• Changing language preserves the current task and announces the resulting language.

Implementation guidance

• Load message bundles by version and locale; atomically switch only after the target bundle validates.
• Log missing keys with locale, route, release, and key hash while showing the default-language value.
• Keep translation keys semantic and avoid concatenating sentence fragments.
• Test pseudo-locales for expansion and bidirectional markers before adding a production locale.

Failure handling and safeguards

• If a saved locale is no longer supported, retain the preference, use the configured fallback, and explain the temporary fallback in settings.
• If a bundle fails integrity checks, keep the previous active bundle.
• Never infer currency from language alone; require an explicit market or account setting.

Verification and operations

• Measure missing-key rate, fallback rate, bundle-load failures, and task abandonment after locale changes.
• Run visual regression tests for long text and RTL layouts.
• Review fallback graphs whenever locales are added or retired.

The executable-looking examples in this package are fixtures and acceptance contracts. Run python tools/validate.py from the collection root to check package structure and metadata; then implement and execute the scenarios in the target repository.

Adoption assumptions

• Names and numeric values in example.yaml are an adoption profile, not universal defaults.
• The adopting team must map actors, data classes, error vocabulary, and ownership to its system.

References

• No external normative source is required; this package defines a project decision.