ThothII/docs/adr/0022-separate-ui-locale-from-session-interaction-language.md

Separate UI locale from session interaction language

status: accepted

ThothII distinguishes three language concepts:

• workspace.language remains the language of workspace-owned documents, descriptions and Evidence;
• ui_locale controls deterministic ThothII chrome such as labels, form help, placeholders, errors, accessibility text and review-widget chrome;
• interaction_language is persisted in a session and controls model-generated questions, explanations and reviewer proposals.

The initial locale catalog supports Italian and English and uses extensible BCP-47 language tags. Missing deterministic translations fall back to English. The selected UI locale supplies the default interaction language when a new session is created. A resumed session always uses its persisted interaction language; changing the host or full-shell UI locale must not silently rewrite an existing session or make its model output switch language mid-workflow.

The distinction is required because the current workspace contract already uses language for content and the PSD workspace is Italian. Reusing that field for a browser preference would make a visual choice mutate domain content semantics. The model receives the session interaction language through the session/Pi workflow context. SQL, identifiers, database values and other technical artifacts remain governed by their existing contracts and are not translated as UI strings.

In full, the local shell owns ui_locale and supplies it when starting a new session. In embedded, the host adapter is authoritative for ui_locale; ThothII applies host changes to deterministic UI immediately while preserving the interaction language of any active session.

We considered using only workspace.language, using only a global browser locale, and translating the model output after generation. The first conflates domain content with UI preference; the second cannot preserve a session's language or follow the host portal; and the third would be unsafe for structured reviewer decisions and would not control the model's reasoning or proposal language.

Considered Options

• One mutable language field for workspace, UI and session was rejected because the fields have different owners and lifecycles.
• Client-only translation of reviewer choices was rejected because choices can be generated by the model and must be requested in the intended language.
• An English-only deterministic chrome was rejected because embedded and full installations must follow the selected host/user language.

Consequences

• Session creation and the persisted manifest gain an explicit interaction-language value.
• Legacy manifests without that value use the workspace language, pinned idempotently on first resume; the browser locale must not determine this compatibility value.
• Resume must read that value from the manifest and must not accept a new locale as an override.
• The workflow prompt contract and deterministic reviewer-widget builders need a locale-aware input.
• Frontend strings need a catalog and stable keys; backend events should expose stable codes where the frontend is responsible for localization.