feat(ui): locale persistence + i18n completeness guards (F3)

An audit found the client already i18n-first: one hard-coded UI string
(the battle-scene aria-label, now keyed) and en/ru already share an
identical 692-key set.

- Persist the locale: i18n.setLocale writes localStorage (galaxy-locale)
  and the store boots from stored > browser detection > default, so a
  language switch survives reloads.
- tests/i18n-completeness.test.ts: en/ru key-set parity, non-empty
  values, and locale persistence.
- Docs: ui/docs/i18n.md; mark F3 done in ui/PLAN-finalize.md.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

ui/frontend/src/lib/battle-player/battle-scene.svelte

@@ -23,6 +23,7 @@ combat filter, so a shot never collapses to a single visual node.
 <script lang="ts">
 	import { getContext } from "svelte";
 
+	import { i18n } from "$lib/i18n/index.svelte";
 	import type { BattleReport } from "../../api/battle-fetch";
 	import {
 		CORE_CONTEXT_KEY,
@@ -310,7 +311,7 @@ combat filter, so a shot never collapses to a single visual node.
 	viewBox="0 0 {VIEW_BOX} {VIEW_BOX}"
 	preserveAspectRatio="xMidYMid meet"
 	role="img"
-	aria-label="battle scene"
+	aria-label={i18n.t("game.battle.scene_label")}
 	data-testid="battle-scene"
 >
 	<circle

ui/frontend/src/lib/i18n/index.svelte.ts

@@ -106,15 +106,36 @@ function isLocale(value: string): value is Locale {
 	return SUPPORTED_LOCALES.some((entry) => entry.code === value);
 }
 
+/** `localStorage` key holding the user's explicit locale choice. */
+export const LOCALE_STORAGE_KEY = "galaxy-locale";
+
+function readStoredLocale(): Locale | null {
+	if (typeof localStorage === "undefined") return null;
+	const value = localStorage.getItem(LOCALE_STORAGE_KEY);
+	return value !== null && isLocale(value) ? value : null;
+}
+
+/**
+ * initialLocale resolves the boot locale: an explicit stored choice
+ * wins, otherwise the browser/system preference, otherwise the default.
+ */
+function initialLocale(): Locale {
+	return readStoredLocale() ?? detectInitialLocale();
+}
+
 class I18nStore {
-	locale: Locale = $state(detectInitialLocale());
+	locale: Locale = $state(initialLocale());
 
 	/**
-	 * setLocale changes the active locale. Components reading
+	 * setLocale changes the active locale and persists the choice to
+	 * `localStorage`, so it survives a reload. Components reading
 	 * `i18n.t(...)` re-render automatically through the rune.
 	 */
 	setLocale(next: Locale): void {
 		this.locale = next;
+		if (typeof localStorage !== "undefined") {
+			localStorage.setItem(LOCALE_STORAGE_KEY, next);
+		}
 	}
 
 	/**

ui/frontend/src/lib/i18n/locales/en.ts

@@ -617,6 +617,7 @@ const en = {
 	"game.battle.not_found": "battle not found",
 	"game.battle.back_to_report": "back to report",
 	"game.battle.back_to_map": "back to map",
+	"game.battle.scene_label": "battle scene",
 	"game.battle.controls.play": "play",
 	"game.battle.controls.pause": "pause",
 	"game.battle.controls.step_forward": "step forward",

ui/frontend/src/lib/i18n/locales/ru.ts

@@ -621,6 +621,7 @@ const ru: Record<keyof typeof en, string> = {
 	"game.battle.not_found": "сражение не найдено",
 	"game.battle.back_to_report": "к отчёту",
 	"game.battle.back_to_map": "к карте",
+	"game.battle.scene_label": "сцена боя",
 	"game.battle.controls.play": "запустить",
 	"game.battle.controls.pause": "пауза",
 	"game.battle.controls.step_forward": "шаг вперёд",

ui/frontend/tests/i18n-completeness.test.ts

@@ -0,0 +1,59 @@
+import "@testing-library/jest-dom/vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import en from "../src/lib/i18n/locales/en";
+import ru from "../src/lib/i18n/locales/ru";
+
+// Structural guard against translation drift: the en bundle defines the
+// TranslationKey type, so any key added to one locale but not the other
+// (or left blank) must fail here rather than silently fall back at
+// runtime.
+describe("i18n bundle completeness", () => {
+	it("en and ru expose identical key sets", () => {
+		const onlyEn = Object.keys(en).filter((k) => !(k in ru));
+		const onlyRu = Object.keys(ru).filter((k) => !(k in en));
+		expect({ onlyEn, onlyRu }).toEqual({ onlyEn: [], onlyRu: [] });
+	});
+
+	it("has no empty translation values", () => {
+		for (const [k, v] of Object.entries(en)) {
+			expect(v.length, `en.${k}`).toBeGreaterThan(0);
+		}
+		for (const [k, v] of Object.entries(ru)) {
+			expect(v.length, `ru.${k}`).toBeGreaterThan(0);
+		}
+	});
+});
+
+// The store is a module singleton constructed on first import (it reads
+// localStorage in its initialiser), so each case clears storage and
+// resets the module registry, then imports a freshly-built store.
+const LOCALE_KEY = "galaxy-locale";
+
+describe("locale persistence", () => {
+	beforeEach(() => {
+		localStorage.clear();
+		vi.resetModules();
+	});
+
+	it("persists an explicit choice and restores it on the next load", async () => {
+		const first = await import("../src/lib/i18n/index.svelte");
+		first.i18n.setLocale("ru");
+		expect(localStorage.getItem(LOCALE_KEY)).toBe("ru");
+
+		vi.resetModules();
+		const second = await import("../src/lib/i18n/index.svelte");
+		expect(second.i18n.locale).toBe("ru");
+	});
+
+	it("falls back to browser detection when nothing is stored", async () => {
+		const mod = await import("../src/lib/i18n/index.svelte");
+		expect(["en", "ru"]).toContain(mod.i18n.locale);
+	});
+
+	it("ignores an unrecognised stored value", async () => {
+		localStorage.setItem(LOCALE_KEY, "fr");
+		const mod = await import("../src/lib/i18n/index.svelte");
+		expect(["en", "ru"]).toContain(mod.i18n.locale);
+	});
+});