---
name: Internationalisation
type: architecture-map-page
slice: 01-frontend
last_verified: 2026/05/09
---

# Internationalisation

> **Where you are:** [Architecture map](../README.md) → [Frontend](README.md) → Internationalisation

**Plain English summary.** svelte-i18n is wired but coverage is intentionally minimal. The infrastructure (loader, persisted choice, Settings selector) is in place so strings can migrate incrementally. Three locales: English (source of truth), Spanish, German. Most strings still render hardcoded.

## At a glance

- **Path:** `src/lib/i18n/`
- **LOC:** 73 (`index.ts`) + 19 lines per locale JSON.
- **Key files:**
  - `src/lib/i18n/index.ts`. Setup, locale detection, public exports.
  - `src/lib/i18n/locales/en.json`. 19 lines.
  - `src/lib/i18n/locales/es.json`. 19 lines.
  - `src/lib/i18n/locales/de.json`. 19 lines.
- **Library:** `svelte-i18n` 4.0.1.

## What's in here

### `index.ts`

```ts
import { init, register, locale as svelteLocale } from "svelte-i18n";
import { derived, get } from "svelte/store";

export type Locale = "en" | "es" | "de";

export const SUPPORTED_LOCALES: { code: Locale; label: string }[] = [
  { code: "en", label: "English" },
  { code: "es", label: "Español" },
  { code: "de", label: "Deutsch" },
];

const STORAGE_KEY = "lumotia_locale";

register("en", () => import("./locales/en.json"));
register("es", () => import("./locales/es.json"));
register("de", () => import("./locales/de.json"));

function detectInitialLocale(): Locale { /* localStorage → navigator.language → "en" */ }
```

Public exports:
- `initI18n()`. Idempotent. Called from every layout's `onMount`-ish path (`+layout.svelte:38` and the float/viewer/preview break layouts).
- `setLocale(code)`. Writes to `lumotia_locale` and updates the svelte-i18n store.
- `currentLocale`. A derived store that components subscribe to via `$currentLocale`.
- `SUPPORTED_LOCALES` constant for the picker.

### Locale JSON shape

19 lines per file means roughly a dozen translated strings. Treat the locales as a stub. Most page text is still hardcoded.

## Where it is consumed

- `SettingsPage.svelte:22` imports `_` (the translation function) and `SUPPORTED_LOCALES`, `setLocale`, `currentLocale`. The locale picker UI lives in Settings.
- A handful of strings inside SettingsPage use `$_('key')`.

## Watch outs

- Adding a new locale is one `register("xx", () => import("./locales/xx.json"))` call plus a `SUPPORTED_LOCALES` entry.
- Cross window: each window initialises i18n independently via its layout. Locale change persists to `localStorage["lumotia_locale"]`. Float and viewer pick up the new locale on the next mount, not live. Worth wiring a Tauri event if live cross-window translation is needed.
- The "British English" toggle in `settings.britishEnglish` is a transcription post-processing flag (slice 04 territory), not a UI locale. Not wired through svelte-i18n.
- Default locale is detected from `navigator.language`. In Tauri, this is the OS locale.

## See also

- [Pages: settings](pages/settings.md). The locale picker UI.
- [Stores](stores.md). The `currentLocale` derived store.