# Instance Locale (env-driven) + Single-Language Content Authoring — Design

**Date:** 2026-06-05
**Status:** Approved (brainstorming) — ready for implementation planning.

## Context

The app is **Sweden-first** but the UI must stay translatable (English now; Danish/
Norwegian conceivable later). A question was raised: do we need the **content-level
multilingual machinery** (the `lang`-keyed label tables + `LocalizedText` field type), or
should we remove it to simplify the codebase?

### The content-translation decision (keep the schema; simplify only the inputs)

Two different things are both called "translation":
- **UI translation** — react-i18next app chrome (sv/en JSON, `LangSwitch`, localStorage
  persistence). Stays and grows.
- **Content multilingualism** — the *data*: `domain::LocalizedLabel { lang, label }`, the
  `FieldType::LocalizedText` flexible-field type, and three DB tables keyed by
  `(parent_id, lang)`: `term_label`, `authority_label`, `field_definition_label`.

**Decision: keep the content schema; simplify only the authoring UI** (brainstorm option
A + the migration-risk analysis). Rationale:
- The expensive, hard-to-reverse part is the **database schema**. Removing it and adding it
  back later means new migrations, backfilling every row with a language tag, rewriting
  every db read/write (`vocab`/`authority`/`fields`), changing API DTOs, swapping the
  frontend editor, and regenerating the typed client — a domain→db→api→web cross-cutting
  refactor. That is the exact pain to avoid.
- The cheap, reversible part is the **UI** (one input vs two). Keeping the schema is nearly
  free: a Sweden-only instance just stores `lang = <default>` rows; re-enabling multilingual
  authoring later is "show the second input again" — **zero migration**.
- The machinery is already built, tested, and merged (M2/M4). Removing it is *also* work +
  risk. Museum cataloguing commonly needs bilingual descriptive metadata
  (Spectrum/Europeana/loans), so "Sweden only" is the assumption most likely to change.

So this milestone **keeps all multilingual capacity dormant in the schema** and **collapses
the authoring inputs to a single language** (the instance default).

### Instance locale via environment variables (no settings table/page)

The app is **single-tenant** (no org/tenant table today — tables: object, audit_log,
field_definition[+label], vocabulary, term[+label], authority[+label], app_user). The
instance language and timezone are set-and-forget per deployment and never change at
runtime, so they are **environment variables**, not a database settings table or an admin
settings page. (If multi-org ever lands, this becomes per-org via a future migration — out
of scope now.)

### Timezone: always store UTC

Timestamps are already `TIMESTAMPTZ` (UTC); `recording_date` is a plain `DATE`. **Storage and
transmission stay UTC** — the API never localizes timestamps. The instance timezone is a
**display/formatting** concern only:
- **Interactive UI** → the frontend formats UTC → instance tz via `Intl.DateTimeFormat`.
- **Server-rendered artifacts** (PDF export #39, future reports/CLI) → the backend will need
  the tz to format without a browser. That server-side formatting is **owned by #39**; this
  milestone only *stores and exposes* the tz value.

## Scope

**In:**
1. Two backend config knobs: `default_language` (`DEFAULT_LANGUAGE`, default `sv`) and
   `default_timezone` (`DEFAULT_TIMEZONE`, default `Europe/Stockholm`), in `server::Config`
   and `AppState`.
2. A public `GET /api/config` endpoint exposing `{ app_name, default_language,
   default_timezone }`.
3. Frontend config provider: fetch `/api/config` on boot; apply `default_language` to
   i18n (when no stored preference); expose the values via context.
4. Single-language content authoring: collapse `LabelEditor` and the `LocalizedText` field
   input to one input writing at `default_language`. Schema/DTOs unchanged.

**Out (deferred / owned elsewhere):**
- **Per-account UI language** (cross-device persistence: a `language` column on `app_user`,
  returned at login, SPA inits from it) → file as a follow-up issue. (Per-*browser*
  persistence already exists via `LangSwitch` + localStorage.)
- Danish/Norwegian UI translations (just more i18n JSON when wanted).
- Server-side timezone formatting → PDF export (#39).
- A real org-settings page → only if multi-org lands.

## Backend

### Config (`crates/server/src/config.rs`)
Add to `Config` (clap derive, matching `app_name`):
```rust
/// Default UI + content-authoring language for this instance (BCP-47 / i18n key, e.g. "sv").
#[arg(long = "default-language", env = "DEFAULT_LANGUAGE", default_value = "sv")]
pub default_language: String,

/// Default display timezone (IANA name, e.g. "Europe/Stockholm"). Storage stays UTC;
/// this is a display hint surfaced to clients and (later) server-side renderers.
#[arg(long = "default-timezone", env = "DEFAULT_TIMEZONE", default_value = "Europe/Stockholm")]
pub default_timezone: String,
```
The timezone is treated as an opaque string (no backend tz library; validated client-side
by `Intl`). Thread both into `AppState` (alongside `app_name`).

### `AppState` (`crates/api/src/lib.rs`)
Add `pub default_language: String` and `pub default_timezone: String`. `server::run` populates
them from `Config`.

### Config endpoint (`crates/api/src/` — e.g. a small `config.rs` or in `health`/`public`)
```
GET /api/config   (unauthenticated)
→ 200 { "app_name": String, "default_language": String, "default_timezone": String }
```
`#[derive(Serialize, ToSchema)]` `ConfigView`, registered in `openapi.rs`. Unauthenticated
because the SPA needs it before login (so the login page renders in the instance language).
No secrets are exposed. Regenerate `web/src/api/schema.d.ts`.

## Frontend

### Config provider (`web/src/`)
- A `useConfig` query/hook fetching `GET /api/config` once on boot (TanStack Query, long
  `staleTime`), exposing `{ app_name, default_language, default_timezone }` via context.
- **Language:** i18n still inits synchronously with a safe fallback. After config loads, if
  there is **no** `localStorage[LOCALE_KEY]` preference, call
  `i18n.changeLanguage(config.default_language)`. The existing `LangSwitch` + localStorage
  override path is unchanged. (Net effect: a fresh browser defaults to the instance language;
  a user who has switched keeps their choice.)
- **Timezone:** add a small `formatTimestamp(utc, config.default_timezone, locale)` helper
  using `Intl.DateTimeFormat(locale, { timeZone })`. Use it wherever timestamps are rendered.
  (During planning, audit the current UI for timestamp surfaces; if there are none yet, the
  helper + config value are forward-ready for PDF #39 / a future audit screen — do not
  invent displays.)

### Single-language content authoring (`web/src/components/label-editor.tsx`, the `LocalizedText` field input in `web/src/objects/field-input.tsx`)
- **`LabelEditor`:** replace the EN+SV pair with a **single** labelled text input. `onChange`
  emits `[{ lang: config.default_language, label }]` (omit empty). The "EN required / SV
  optional" rule collapses to "the single label is required."
- **`LocalizedText` field input:** replace the per-language inputs with a single textbox;
  the value written is `{ [config.default_language]: text }`.
- **Reading:** `labelText` / `domain::pick_label` already pick a language with fallback; set
  the preferred lang to `config.default_language` (then English, then first) so existing
  multilingual data (e.g. seeded) still displays.
- **Unchanged:** `LabelInput`/`LabelView` DTOs, the three `*_label` tables, `LocalizedLabel`,
  `FieldType::LocalizedText`, and all db read/write paths. Only the input components change.

## Data flow

Boot → SPA fetches `/api/config` → context holds `{ app_name, default_language,
default_timezone }` → i18n language set to `default_language` (unless overridden in
localStorage) → content editors author one label at `default_language` (stored as a
single-entry `[{lang,label}]`) → timestamps render via `Intl` in `default_timezone`.

## Error handling
- `/api/config` is static, env-derived — it cannot fail at the DB level (no query). If the
  fetch fails (network), the SPA falls back to the synchronous i18n default and a sensible
  built-in timezone (`"Europe/Stockholm"`), and retries via TanStack Query.
- Empty/invalid timezone: the frontend `Intl` call throws for an invalid IANA name; the
  helper catches and falls back to UTC display rather than crashing.

## Testing
- **Backend:** `GET /api/config` returns the configured values; defaults applied when env
  unset; endpoint is reachable unauthenticated. `Config` parses `DEFAULT_LANGUAGE` /
  `DEFAULT_TIMEZONE` (+ `--default-language` / `--default-timezone`).
- **Frontend (Vitest + RTL + MSW):** with a config of `{ default_language: "sv" }` and no
  stored locale, i18n switches to `sv`; with a stored `en`, it stays `en`. `LabelEditor`
  renders one input and emits `[{ lang: "sv", label }]`. A `LocalizedText` field input
  emits `{ sv: text }`. Existing screens that read labels still render.
- en/sv i18n key parity; no `any`/`eslint-disable`; codename ban; bundle ≤150 KB gz.

## Acceptance criteria
1. `DEFAULT_LANGUAGE` / `DEFAULT_TIMEZONE` env vars (with CLI flags + defaults `sv` /
   `Europe/Stockholm`) drive instance locale; no settings table or admin page.
2. `GET /api/config` (public) returns `app_name` + `default_language` + `default_timezone`;
   in `schema.d.ts`.
3. The SPA defaults its UI language to the instance default (overridable per-browser via the
   existing `LangSwitch`/localStorage).
4. Content authoring is single-language: `LabelEditor` and `LocalizedText` inputs collapse to
   one field writing at the default language; **the content schema/DTOs/tables are unchanged**
   (multilingual capacity remains dormant, re-enabled by UI alone).
5. Timestamps render in the instance timezone via `Intl` where displayed; storage stays UTC.
6. CI green (cargo + web typecheck/lint/test/build, bundle ≤150 KB); en/sv parity.

## Out of scope / follow-ups
- Per-account UI language (cross-device) — separate issue (filed with this milestone).
- Danish/Norwegian UI locales; server-side tz formatting (#39); org-level settings page.