DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
Unify French and Ukrainian language settings across app
Bingxi Zhao (Frank)fc0e0a951037
diff --git a/deeptutor/agents/loop/pipeline.py b/deeptutor/agents/loop/pipeline.pyindex 2908e86e7..b5b5a9c52 100644--- a/deeptutor/agents/loop/pipeline.py+++ b/deeptutor/agents/loop/pipeline.py@@ -86,7 +86,7 @@ from deeptutor.services.llm import (supports_tools, # noqa: F401 (re-exported for tests))from deeptutor.services.llm.context_window import resolve_effective_context_window-from deeptutor.services.prompt import get_prompt_manager+from deeptutor.services.prompt import get_prompt_manager, normalize_languagefrom deeptutor.services.prompt.lookup import prompt_text as _prompt_textfrom deeptutor.tools.builtin import PARTNER_BUILTIN_TOOL_NAMES@@ -236,8 +236,9 @@ class AgenticLoopPipeline:event_stage: str = "responding",emit_result: bool = True,) -> None:- _lang = language.lower()- self.language = "zh" if _lang.startswith("zh") else "fr" if _lang.startswith("fr") else "en"+ # Prompt resources fall back to English; the requested output language+ # must still reach the assembler's final language directive.+ self.language = normalize_language(language)self.llm_config = get_llm_config()self.binding = getattr(self.llm_config, "binding", None) or "openai"self.model = getattr(self.llm_config, "model", None)diff --git a/deeptutor/api/routers/settings.py b/deeptutor/api/routers/settings.pyindex 6c51db8ea..3489eab97 100644--- a/deeptutor/api/routers/settings.py+++ b/deeptutor/api/routers/settings.py@@ -59,6 +59,7 @@ from deeptutor.services.settings.interface_settings import (DEFAULT_UI_SETTINGS as INTERFACE_DEFAULTS,)from deeptutor.services.settings.interface_settings import (+ UiLanguage,atomic_update,resolve_languages,sanitize_enabled_tools,@@ -142,8 +143,8 @@ class SidebarNavOrder(BaseModel):class UISettings(BaseModel):theme: Literal["light", "dark", "glass", "snow"] = "snow"- language: Literal["zh", "en", "fr"] = "en"- response_language: Literal["zh", "en", "fr"] = "en"+ language: UiLanguage = "en"+ response_language: UiLanguage = "en"sidebar_description: Optional[str] = Nonesidebar_nav_order: Optional[SidebarNavOrder] = Nonecode_block_theme: Optional[str] = None@@ -165,8 +166,8 @@ class UISettingsUpdate(BaseModel):# for exclude_unset partial merges, but an explicit value is still validated# so PUT /ui cannot persist a theme/language the app can't render.theme: Literal["light", "dark", "glass", "snow"] | None = None- language: Literal["zh", "en", "fr"] | None = None- response_language: Literal["zh", "en", "fr"] | None = None+ language: UiLanguage | None = None+ response_language: UiLanguage | None = Nonesidebar_description: str | None = Nonesidebar_nav_order: SidebarNavOrder | None = Nonecode_block_theme: str | None = None@@ -191,7 +192,7 @@ class ThemeUpdate(BaseModel):class LanguageUpdate(BaseModel):- language: Literal["zh", "en", "fr"]+ language: UiLanguageclass SidebarDescriptionUpdate(BaseModel):diff --git a/deeptutor/services/config/launch_settings.py b/deeptutor/services/config/launch_settings.pyindex e52f7cb93..966d316cc 100644--- a/deeptutor/services/config/launch_settings.py+++ b/deeptutor/services/config/launch_settings.py@@ -57,6 +57,8 @@ def _normalize_language(value: Any) -> str | None:return "zh"if language in {"fr", "french"} or language.startswith("fr_"):return "fr"+ if language in {"uk", "ua", "ukrainian"} or language.startswith("uk_"):+ return "uk"return Nonediff --git a/deeptutor/services/config/settings_spec.py b/deeptutor/services/config/settings_spec.pyindex 7a7c7f16a..802e60a01 100644--- a/deeptutor/services/config/settings_spec.py+++ b/deeptutor/services/config/settings_spec.py@@ -128,6 +128,7 @@ class SettingSpec:_LANGUAGE_CHOICES: tuple[tuple[str, str, str], ...] = (("en", "English", "Interface and replies in English."),("zh", "简体中文", "Interface and replies in Simplified Chinese."),+ ("fr", "Français", "Interface and replies in French."),("uk", "Українська", "Interface and replies in Ukrainian."),)diff --git a/deeptutor/services/settings/interface_settings.py b/deeptutor/services/settings/interface_settings.pyindex e257a119a..6ddb0951c 100644--- a/deeptutor/services/settings/interface_settings.py+++ b/deeptutor/services/settings/interface_settings.py@@ -13,11 +13,13 @@ import osfrom pathlib import Pathimport tempfileimport threading-from typing import Any+from typing import Any, Literalfrom deeptutor.services.path_service import get_path_servicefrom deeptutor.tools.builtin import USER_TOGGLEABLE_TOOL_NAMES+UiLanguage = Literal["en", "zh", "fr", "uk"]+DEFAULT_UI_SETTINGS: dict[str, Any] = {# "snow" is the pure-white neutral theme, shown as "Default" in the UI."theme": "snow",diff --git a/tests/api/test_settings_router.py b/tests/api/test_settings_router.pyindex be40d061d..afcee0e35 100644--- a/tests/api/test_settings_router.py+++ b/tests/api/test_settings_router.py@@ -76,21 +76,24 @@ async def test_ui_languages_are_persisted_independently(@pytest.mark.asyncio-async def test_ui_settings_persist_french_independently(- monkeypatch: pytest.MonkeyPatch, tmp_path[email protected]("language", ["fr", "uk"])+async def test_ui_settings_persist_supported_languages_independently(+ monkeypatch: pytest.MonkeyPatch, tmp_path, language: str) -> None:settings_file = tmp_path / "interface.json"monkeypatch.setattr(settings_router, "_settings_file", lambda: settings_file)response = await settings_router.update_ui_settings(- settings_router.UISettingsUpdate(theme="snow", language="fr", response_language="en")+ settings_router.UISettingsUpdate(theme="snow", language=language, response_language="en"))- assert response["language"] == "fr"+ assert response["language"] == languageassert response["response_language"] == "en"persisted = settings_router.load_ui_settings()- assert persisted["language"] == "fr"+ assert persisted["language"] == languageassert persisted["response_language"] == "en"+ assert (await settings_router.get_ui_settings())["language"] == language+ assert settings_router.LanguageUpdate(language=language).language == languagedef test_ui_settings_update_rejects_unsupported_language() -> None:diff --git a/tests/services/config/test_launch_settings.py b/tests/services/config/test_launch_settings.pyindex 0516986fe..8be84ccad 100644--- a/tests/services/config/test_launch_settings.py+++ b/tests/services/config/test_launch_settings.py@@ -3,6 +3,8 @@ from __future__ import annotationsimport jsonfrom pathlib import Path+import pytest+from deeptutor.services.config.launch_settings import load_launch_settings@@ -42,7 +44,13 @@ def test_launch_settings_reads_ports_from_system_json_and_ignores_env_json(assert "interface.json" in settings.source-def test_launch_settings_reads_french_from_interface_json(monkeypatch, tmp_path: Path) -> None:+ ("stored_language", "expected"),+ [("french", "fr"), ("ukrainian", "uk"), ("uk_UA", "uk")],+)+def test_launch_settings_reads_supported_languages_from_interface_json(+ monkeypatch, tmp_path: Path, stored_language: str, expected: str+) -> None:for key in ("BACKEND_PORT", "FRONTEND_PORT", "UI_LANGUAGE", "LANGUAGE"):monkeypatch.delenv(key, raising=False)@@ -52,13 +60,13 @@ def test_launch_settings_reads_french_from_interface_json(monkeypatch, tmp_path:encoding="utf-8",)(settings_dir / "interface.json").write_text(- json.dumps({"language": "french"}),+ json.dumps({"language": stored_language}),encoding="utf-8",)settings = load_launch_settings(tmp_path)- assert settings.language == "fr"+ assert settings.language == expectedassert "interface.json" in settings.sourcediff --git a/tests/services/prompt/test_language_directive.py b/tests/services/prompt/test_language_directive.pyindex ce5d57786..f29f816b5 100644--- a/tests/services/prompt/test_language_directive.py+++ b/tests/services/prompt/test_language_directive.py@@ -50,3 +50,20 @@ def test_chat_renders_the_overridable_directive(language: str, marker: str) -> Nassembler = LoopPromptAssembler(prompts={}, language=language)rendered = assembler.render([PromptBlock(name="Base", content="body")])assert marker in rendered+++ ("language", "label"),+ [("fr", "Français"), ("uk", "Українська")],+)+def test_loop_preserves_requested_output_language_with_english_prompt_assets(+ language: str, label: str+) -> None:+ from deeptutor.agents.loop.pipeline import AgenticLoopPipeline+ from deeptutor.agents.loop.prompt_blocks import PromptBlock++ pipeline = AgenticLoopPipeline(language=language)+ assert pipeline.language == language+ assert pipeline._prompt_assembler.language == "en"+ rendered = pipeline._prompt_assembler.render([PromptBlock(name="Base", content="body")])+ assert label in rendereddiff --git a/web/components/settings/shared.tsx b/web/components/settings/shared.tsxindex 2a1789083..0292c17dc 100644--- a/web/components/settings/shared.tsx+++ b/web/components/settings/shared.tsx@@ -5,6 +5,7 @@ import type {ServiceName,} from "@/features/settings/store/SettingsStore";import type { AppLanguage } from "@/i18n/init";+import { getLocale } from "@/lib/datetime";// Tailwind 3 silently drops `<color>-[var(--token)]/NN`: our tokens are hex// literals, so it cannot split them into channels and emits no rule at all.@@ -91,9 +92,7 @@ export function formatContextWindowUpdatedAt(if (!value) return "";const parsed = new Date(value);if (Number.isNaN(parsed.getTime())) return value;- const locale =- language === "zh" ? "zh-CN" : language === "fr" ? "fr-FR" : "en-US";- return parsed.toLocaleString(locale, {+ return parsed.toLocaleString(getLocale(language), {dateStyle: "medium",timeStyle: "short",});diff --git a/web/context/AppShellContext.tsx b/web/context/AppShellContext.tsxindex 679ae58ed..0559d5fa8 100644--- a/web/context/AppShellContext.tsx+++ b/web/context/AppShellContext.tsx@@ -52,6 +52,7 @@ import {writeStoredSidebarCollapsed,type AppLanguage,} from "@/context/app-shell-storage";+import { isAppLanguage } from "@/i18n/languages";interface AppShellContextValue {theme: Theme;@@ -122,9 +123,12 @@ export function AppShellProvider({ children }: { children: React.ReactNode }) {// split has `deeptutor-language` and no `deeptutor-response-language` —// and returning here on the first alone locked it out of ever adopting// the account's model output language.- if (hasStoredLanguage() && hasStoredResponseLanguage()) {+ const hadLanguageAtStart = hasStoredLanguage();+ if (hadLanguageAtStart && !cancelled) {+ setLanguageState(readStoredLanguage());+ }+ if (hadLanguageAtStart && hasStoredResponseLanguage()) {if (!cancelled) {- setLanguageState(readStoredLanguage());setLanguageReady(true);}return;@@ -143,12 +147,7 @@ export function AppShellProvider({ children }: { children: React.ReactNode }) {language?: unknown;response_language?: unknown;};- if (- payload.language !== "zh" &&- payload.language !== "en" &&- payload.language !== "fr"- )- return;+ if (!isAppLanguage(payload.language)) return;// Only what this browser is actually missing: a stored interface// language is this user's own choice and the server must not overwrite// it just because the response key was absent.diff --git a/web/context/app-shell-storage.ts b/web/context/app-shell-storage.tsindex 059d5ad50..3c3f23fdb 100644--- a/web/context/app-shell-storage.ts+++ b/web/context/app-shell-storage.ts@@ -2,12 +2,13 @@import { browserStorage } from "@/shared/storage";import { activeWorkspaceId } from "@/lib/workspace-scope";+import {+ isAppLanguage,+ normalizeLanguage as normalizeAppLanguage,+ type AppLanguage,+} from "@/i18n/languages";-// Re-exported rather than redeclared: this file had its own copy of the-// union, so widening the i18n one left this narrow and every call site-// that crossed the two failed to compile.-export type { AppLanguage } from "@/i18n/init";-import type { AppLanguage } from "@/i18n/init";+export type { AppLanguage } from "@/i18n/languages";export const ACTIVE_SESSION_STORAGE_KEY = "deeptutor.activeSessionId.tab";export const LANGUAGE_STORAGE_KEY = "deeptutor-language";@@ -75,16 +76,14 @@ export const CODE_BLOCK_SETTINGS_EVENT = "deeptutor:code-block-settings";export function normalizeLanguage(value: string | null | undefined,): AppLanguage {- return value === "zh" || value === "fr" || value === "uk" ? value : "en";+ return normalizeAppLanguage(value);}export function resolveResponseLanguage(value: string | null | undefined,legacyLanguage: string | null | undefined = "en",): AppLanguage {- return value === "zh" || value === "en" || value === "fr" || value === "uk"- ? value- : normalizeLanguage(legacyLanguage);+ return isAppLanguage(value) ? value : normalizeLanguage(legacyLanguage);}export function readStoredLanguage(): AppLanguage {diff --git a/web/contracts/generated/api.ts b/web/contracts/generated/api.tsindex 82060494b..980390725 100644--- a/web/contracts/generated/api.ts+++ b/web/contracts/generated/api.ts@@ -6158,6 +6158,46 @@ export interface paths {readonly patch?: never;readonly trace?: never;};+ readonly "/api/reading/materials/{material_id}/media": {+ readonly parameters: {+ readonly query?: never;+ readonly header?: never;+ readonly path?: never;+ readonly cookie?: never;+ };+ /**+ * List Material Media+ * @description The embedded-image index (name / locator / mime / size), empty if none.+ */+ readonly get: operations["list_material_media_api_reading_materials__material_id__media_get"];+ readonly put?: never;+ readonly post?: never;+ readonly delete?: never;+ readonly options?: never;+ readonly head?: never;+ readonly patch?: never;+ readonly trace?: never;+ };+ readonly "/api/reading/materials/{material_id}/media/{name}": {+ readonly parameters: {+ readonly query?: never;+ readonly header?: never;+ readonly path?: never;+ readonly cookie?: never;+ };+ /**+ * Get Material Media+ * @description One embedded image's bytes, for the reader pane's media strip.+ */+ readonly get: operations["get_material_media_api_reading_materials__material_id__media__name__get"];+ readonly put?: never;+ readonly post?: never;+ readonly delete?: never;+ readonly options?: never;+ readonly head?: never;+ readonly patch?: never;+ readonly trace?: never;+ };readonly "/api/reading/materials/{material_id}/position": {readonly parameters: {readonly query?: never;@@ -8031,6 +8071,30 @@ export interface paths {readonly patch?: never;readonly trace?: never;};+ readonly "/api/settings/voice-math-speak": {+ readonly parameters: {+ readonly query?: never;+ readonly header?: never;+ readonly path?: never;+ readonly cookie?: never;+ };+ readonly get?: never;+ /**+ * Update Voice Math Speak+ * @description Persist whether TTS verbalizes LaTeX as spoken math.+ *+ * A personal UI preference (any authenticated user). The voice router reads+ * this on each synthesis call; chat does not send a per-request override.+ * Dollar-sign delimiters are stripped even when this is off.+ */+ readonly put: operations["update_voice_math_speak_api_settings_voice_math_speak_put"];+ readonly post?: never;+ readonly delete?: never;+ readonly options?: never;+ readonly head?: never;+ readonly patch?: never;+ readonly trace?: never;+ };readonly "/api/settings/voice/preview": {readonly parameters: {readonly query?: never;@@ -11283,6 +11347,8 @@ export interface components {readonly [key: string]: unknown;};} | null;+ /** Image Caption */+ readonly image_caption?: boolean | null;};/** DocumentResponse */readonly DocumentResponse: {@@ -11798,7 +11864,7 @@ export interface components {* Language* @enum {string}*/- readonly language: "zh" | "en";+ readonly language: "en" | "zh" | "fr" | "uk";};/** LearnerOverrideRequest */readonly LearnerOverrideRequest: {@@ -12758,6 +12824,18 @@ export interface components {readonly options: {readonly [key: string]: string;};+ /**+ * Origin Ref+ * @default+ */+ readonly origin_ref: string;+ /**+ * Origin Type+ * @default conversation+ * @enum {string}+ */+ readonly origin_type:+ "conversation" | "external_import" | "document_analysis";/** Practice */readonly practice?: {readonly [key: string]: unknown;@@ -12805,7 +12883,10 @@ export interface components {* @default*/readonly section_title: string;- /** Session Id */+ /**+ * Session Id+ * @default+ */readonly session_id: string;/*** Session Title@@ -14563,9 +14644,9 @@ export interface components {/** Code Block Wrap Long Lines */readonly code_block_wrap_long_lines?: boolean | null;/** Language */- readonly language?: ("zh" | "en") | null;+ readonly language?: ("en" | "zh" | "fr" | "uk") | null;/** Response Language */- readonly response_language?: ("zh" | "en") | null;+ readonly response_language?: ("en" | "zh" | "fr" | "uk") | null;/** Sidebar Description */readonly sidebar_description?: string | null;readonly sidebar_nav_order?:@@ -14837,6 +14918,18 @@ export interface components {readonly options?: {readonly [key: string]: string;} | null;+ /**+ * Origin Ref+ * @default+ */+ readonly origin_ref: string;+ /**+ * Origin Type+ * @default conversation+ * @enum {string}+ */+ readonly origin_type:+ "conversation" | "external_import" | "document_analysis";/** Quality */readonly quality?: number | null;/** Question */@@ -14865,7 +14958,10 @@ export interface components {* @default*/readonly section_title: string;- /** Session Id */+ /**+ * Session Id+ * @default+ */readonly session_id: string;/*** Source@@ -15055,6 +15151,11 @@ export interface components {/** Voice Autoplay */readonly voice_autoplay: boolean;};+ /** VoiceMathSpeakUpdate */+ readonly VoiceMathSpeakUpdate: {+ /** Voice Math Speak */+ readonly voice_math_speak: boolean;+ };/** VoicePreviewPayload */readonly VoicePreviewPayload: {/** Catalog */@@ -15686,6 +15787,8 @@ export type SchemaVideoLearningSettingsRequest =components["schemas"]["VideoLearningSettingsRequest"];export type SchemaVoiceAutoplayUpdate =components["schemas"]["VoiceAutoplayUpdate"];+export type SchemaVoiceMathSpeakUpdate =+ components["schemas"]["VoiceMathSpeakUpdate"];export type SchemaVoicePreviewPayload =components["schemas"]["VoicePreviewPayload"];export type SchemaWebSourceInfo = components["schemas"]["WebSourceInfo"];@@ -28137,8 +28240,11 @@ export interface operations {readonly query: {/** @description Return 204 No Content instead of 404 when the entry is absent — used by the quiz viewer to probe not-yet-saved questions without logging noisy 404s. */readonly missing_ok?: boolean;+ readonly origin_ref?: string;+ readonly origin_type?:+ "conversation" | "external_import" | "document_analysis";readonly question_id: string;- readonly session_id: string;+ readonly session_id?: string;readonly turn_id?: string | null;};readonly header?: {@@ -29439,6 +29545,79 @@ export interface operations {};};};+ readonly list_material_media_api_reading_materials__material_id__media_get: {+ readonly parameters: {+ readonly query?: never;+ readonly header?: {+ readonly Authorization?: string | null;+ };+ readonly path: {+ readonly material_id: string;+ };+ readonly cookie?: {+ readonly dt_token?: string | null;+ };+ };+ readonly requestBody?: never;+ readonly responses: {+ /** @description Successful Response */+ readonly 200: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": readonly {+ readonly [key: string]: unknown;+ }[];+ };+ };+ /** @description Validation Error */+ readonly 422: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": components["schemas"]["HTTPValidationError"];+ };+ };+ };+ };+ readonly get_material_media_api_reading_materials__material_id__media__name__get: {+ readonly parameters: {+ readonly query?: never;+ readonly header?: {+ readonly Authorization?: string | null;+ };+ readonly path: {+ readonly material_id: string;+ readonly name: string;+ };+ readonly cookie?: {+ readonly dt_token?: string | null;+ };+ };+ readonly requestBody?: never;+ readonly responses: {+ /** @description Successful Response */+ readonly 200: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": unknown;+ };+ };+ /** @description Validation Error */+ readonly 422: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": components["schemas"]["HTTPValidationError"];+ };+ };+ };+ };readonly get_position_api_reading_materials__material_id__position_get: {readonly parameters: {readonly query?: never;@@ -33711,6 +33890,43 @@ export interface operations {};};};+ readonly update_voice_math_speak_api_settings_voice_math_speak_put: {+ readonly parameters: {+ readonly query?: never;+ readonly header?: {+ readonly Authorization?: string | null;+ };+ readonly path?: never;+ readonly cookie?: {+ readonly dt_token?: string | null;+ };+ };+ readonly requestBody: {+ readonly content: {+ readonly "application/json": components["schemas"]["VoiceMathSpeakUpdate"];+ };+ };+ readonly responses: {+ /** @description Successful Response */+ readonly 200: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": unknown;+ };+ };+ /** @description Validation Error */+ readonly 422: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": components["schemas"]["HTTPValidationError"];+ };+ };+ };+ };readonly preview_voice_api_settings_voice_preview_post: {readonly parameters: {readonly query?: never;diff --git a/web/contracts/schema/openapi.json b/web/contracts/schema/openapi.jsonindex f1ea5e9ba..773b69466 100644--- a/web/contracts/schema/openapi.json+++ b/web/contracts/schema/openapi.json@@ -3094,6 +3094,17 @@}],"title": "Engines"+ },+ "image_caption": {+ "anyOf": [+ {+ "type": "boolean"+ },+ {+ "type": "null"+ }+ ],+ "title": "Image Caption"}},"title": "DocumentParsingUpdate",@@ -4346,8 +4357,10 @@"properties": {"language": {"enum": [+ "en","zh",- "en"+ "fr",+ "uk"],"title": "Language","type": "string"@@ -6103,6 +6116,21 @@"title": "Options","type": "object"},+ "origin_ref": {+ "default": "",+ "title": "Origin Ref",+ "type": "string"+ },+ "origin_type": {+ "default": "conversation",+ "enum": [+ "conversation",+ "external_import",+ "document_analysis"+ ],+ "title": "Origin Type",+ "type": "string"+ },"practice": {"anyOf": [{@@ -6197,6 +6225,7 @@"type": "string"},"session_id": {+ "default": "","title": "Session Id","type": "string"},@@ -6243,7 +6272,6 @@},"required": ["id",- "session_id","question","created_at","updated_at"@@ -10072,8 +10100,10 @@"anyOf": [{"enum": [+ "en","zh",- "en"+ "fr",+ "uk"],"type": "string"},@@ -10087,8 +10117,10 @@"anyOf": [{"enum": [+ "en","zh",- "en"+ "fr",+ "uk"],"type": "string"},@@ -11015,6 +11047,21 @@],"title": "Options"},+ "origin_ref": {+ "default": "",+ "title": "Origin Ref",+ "type": "string"+ },+ "origin_type": {+ "default": "conversation",+ "enum": [+ "conversation",+ "external_import",+ "document_analysis"+ ],+ "title": "Origin Type",+ "type": "string"+ },"quality": {"anyOf": [{@@ -11066,6 +11113,7 @@"type": "string"},"session_id": {+ "default": "","title": "Session Id","type": "string"},@@ -11108,7 +11156,6 @@}},"required": [- "session_id","question_id","question"],@@ -11420,6 +11467,19 @@"title": "VoiceAutoplayUpdate","type": "object"},+ "VoiceMathSpeakUpdate": {+ "properties": {+ "voice_math_speak": {+ "title": "Voice Math Speak",+ "type": "boolean"+ }+ },+ "required": [+ "voice_math_speak"+ ],+ "title": "VoiceMathSpeakUpdate",+ "type": "object"+ },"VoicePreviewPayload": {"properties": {"catalog": {@@ -37271,12 +37331,38 @@{"in": "query","name": "session_id",- "required": true,+ "required": false,"schema": {+ "default": "","title": "Session Id","type": "string"}},+ {+ "in": "query",+ "name": "origin_type",+ "required": false,+ "schema": {+ "default": "conversation",+ "enum": [+ "conversation",+ "external_import",+ "document_analysis"+ ],+ "title": "Origin Type",+ "type": "string"+ }+ },+ {+ "in": "query",+ "name": "origin_ref",+ "required": false,+ "schema": {+ "default": "",+ "title": "Origin Ref",+ "type": "string"+ }+ },{"in": "query","name": "question_id",@@ -40572,6 +40658,168 @@]}},+ "/api/reading/materials/{material_id}/media": {+ "get": {+ "description": "The embedded-image index (name / locator / mime / size), empty if none.",+ "operationId": "list_material_media_api_reading_materials__material_id__media_get",+ "parameters": [+ {+ "in": "path",+ "name": "material_id",+ "required": true,+ "schema": {+ "title": "Material Id",+ "type": "string"+ }+ },+ {+ "in": "header",+ "name": "Authorization",+ "required": false,+ "schema": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Authorization"+ }+ },+ {+ "in": "cookie",+ "name": "dt_token",+ "required": false,+ "schema": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Dt Token"+ }+ }+ ],+ "responses": {+ "200": {+ "content": {+ "application/json": {+ "schema": {+ "items": {+ "additionalProperties": true,+ "type": "object"+ },+ "title": "Response List Material Media Api Reading Materials Material Id Media Get",+ "type": "array"+ }+ }+ },+ "description": "Successful Response"+ },+ "422": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/HTTPValidationError"+ }+ }+ },+ "description": "Validation Error"+ }+ },+ "summary": "List Material Media",+ "tags": [+ "reading"+ ]+ }+ },+ "/api/reading/materials/{material_id}/media/{name}": {+ "get": {+ "description": "One embedded image's bytes, for the reader pane's media strip.",+ "operationId": "get_material_media_api_reading_materials__material_id__media__name__get",+ "parameters": [+ {+ "in": "path",+ "name": "material_id",+ "required": true,+ "schema": {+ "title": "Material Id",+ "type": "string"+ }+ },+ {+ "in": "path",+ "name": "name",+ "required": true,+ "schema": {+ "title": "Name",+ "type": "string"+ }+ },+ {+ "in": "header",+ "name": "Authorization",+ "required": false,+ "schema": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Authorization"+ }+ },+ {+ "in": "cookie",+ "name": "dt_token",+ "required": false,+ "schema": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Dt Token"+ }+ }+ ],+ "responses": {+ "200": {+ "content": {+ "application/json": {+ "schema": {}+ }+ },+ "description": "Successful Response"+ },+ "422": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/HTTPValidationError"+ }+ }+ },+ "description": "Validation Error"+ }+ },+ "summary": "Get Material Media",+ "tags": [+ "reading"+ ]+ }+ },"/api/reading/materials/{material_id}/position": {"get": {"description": "Return the user's last durable viewport for this material.",@@ -49362,6 +49610,80 @@]}},+ "/api/settings/voice-math-speak": {+ "put": {+ "description": "Persist whether TTS verbalizes LaTeX as spoken math.\n\nA personal UI preference (any authenticated user). The voice router reads\nthis on each synthesis call; chat does not send a per-request override.\nDollar-sign delimiters are stripped even when this is off.",+ "operationId": "update_voice_math_speak_api_settings_voice_math_speak_put",+ "parameters": [+ {+ "in": "header",+ "name": "Authorization",+ "required": false,+ "schema": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Authorization"+ }+ },+ {+ "in": "cookie",+ "name": "dt_token",+ "required": false,+ "schema": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Dt Token"+ }+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/VoiceMathSpeakUpdate"+ }+ }+ },+ "required": true+ },+ "responses": {+ "200": {+ "content": {+ "application/json": {+ "schema": {}+ }+ },+ "description": "Successful Response"+ },+ "422": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/HTTPValidationError"+ }+ }+ },+ "description": "Validation Error"+ }+ },+ "summary": "Update Voice Math Speak",+ "tags": [+ "settings"+ ]+ }+ },"/api/settings/voice/preview": {"post": {"description": "Audition the model being edited without saving or activating its catalog.",diff --git a/web/hooks/useSetupSync.ts b/web/hooks/useSetupSync.tsindex e36b28404..fc8c3bc9f 100644--- a/web/hooks/useSetupSync.ts+++ b/web/hooks/useSetupSync.ts@@ -3,6 +3,7 @@import { useEffect, useRef } from "react";import { apiFetch, apiUrl } from "@/lib/api";+import { isAppLanguage } from "@/i18n/languages";import {resolveResponseLanguage,writeStoredLanguage,@@ -64,11 +65,7 @@ export function useSetupSync(theme?: unknown;};if (cancelled) return;- if (- payload.language === "zh" ||- payload.language === "en" ||- payload.language === "fr"- ) {+ if (isAppLanguage(payload.language)) {writeStoredLanguage(payload.language);writeStoredResponseLanguage(resolveResponseLanguage(diff --git a/web/i18n/init.ts b/web/i18n/init.tsindex 2ab7bd708..b29336f9c 100644--- a/web/i18n/init.ts+++ b/web/i18n/init.ts@@ -2,30 +2,10 @@ import i18n, { type Resource } from "i18next";import { initReactI18next } from "react-i18next";import enApp from "@/locales/en/app.json";+import { normalizeLanguage, type AppLanguage } from "./languages";-export type AppLanguage = "en" | "zh" | "fr" | "uk";--/**- * The languages the app offers, in menu order — the single source of truth for- * every language picker. Pickers used to hardcode `["en", "zh"]` inline, so a- * new locale had to be added in each of them and was silently missing from the- * ones nobody remembered.- */-export const APP_LANGUAGES: readonly { code: AppLanguage; labelKey: string }[] = [- { code: "en", labelKey: "language.english" },- { code: "zh", labelKey: "language.chinese" },- { code: "fr", labelKey: "language.french" },- { code: "uk", labelKey: "language.ukrainian" },-];--export function normalizeLanguage(lang: unknown): AppLanguage {- if (!lang) return "en";- const s = String(lang).toLowerCase();- if (s === "zh" || s === "cn" || s === "chinese") return "zh";- if (s === "fr" || s === "french") return "fr";- if (s === "uk" || s === "ua" || s === "ukrainian") return "uk";- return "en";-}+export { APP_LANGUAGES, isAppLanguage, normalizeLanguage } from "./languages";+export type { AppLanguage } from "./languages";let _initialized = false;diff --git a/web/i18n/languages.ts b/web/i18n/languages.tsnew file mode 100644index 000000000..1cba2b950--- /dev/null+++ b/web/i18n/languages.ts@@ -0,0 +1,27 @@+/** UI locales that have a selectable bundle. The bundles may fall back to English per key. */+export const APP_LANGUAGES = [+ { code: "en", labelKey: "language.english" },+ { code: "zh", labelKey: "language.chinese" },+ { code: "fr", labelKey: "language.french" },+ { code: "uk", labelKey: "language.ukrainian" },+] as const;++export type AppLanguage = (typeof APP_LANGUAGES)[number]["code"];++const SUPPORTED_CODES: ReadonlySet<string> = new Set(+ APP_LANGUAGES.map(({ code }) => code),+);++export function isAppLanguage(value: unknown): value is AppLanguage {+ return typeof value === "string" && SUPPORTED_CODES.has(value);+}++export function normalizeLanguage(value: unknown): AppLanguage {+ if (typeof value !== "string") return "en";+ const code = value.trim().toLowerCase().replaceAll("_", "-");+ const base = code.split("-", 1)[0];+ if (base === "zh" || base === "cn" || code === "chinese") return "zh";+ if (base === "fr" || code === "french") return "fr";+ if (base === "uk" || base === "ua" || code === "ukrainian") return "uk";+ return "en";+}diff --git a/web/lib/datetime.ts b/web/lib/datetime.tsindex c5b12cba5..4c0e5528f 100644--- a/web/lib/datetime.ts+++ b/web/lib/datetime.ts@@ -1,7 +1,10 @@-export type Language = "en" | "zh" | "uk";+import type { AppLanguage } from "@/i18n/languages";++export type Language = AppLanguage;export function getLocale(lang: Language): string {if (lang === "zh") return "zh-CN";+ if (lang === "fr") return "fr-FR";if (lang === "uk") return "uk-UA";return "en-US";}diff --git a/web/lib/tool-availability.ts b/web/lib/tool-availability.tsindex 0cff703e6..616886c51 100644--- a/web/lib/tool-availability.ts+++ b/web/lib/tool-availability.ts@@ -1,4 +1,6 @@-export type ToolAvailabilityLanguage = "en" | "zh" | "uk";+import type { AppLanguage } from "@/i18n/languages";++export type ToolAvailabilityLanguage = AppLanguage;export type ToolAvailabilityCopy = {badge: string;diff --git a/web/tests/app-shell-language-adoption.spec.tsx b/web/tests/app-shell-language-adoption.spec.tsxnew file mode 100644index 000000000..00c3183da--- /dev/null+++ b/web/tests/app-shell-language-adoption.spec.tsx@@ -0,0 +1,57 @@+import { cleanup, render, screen, waitFor } from "@testing-library/react";+import { afterEach, beforeEach, expect, it, vi } from "vitest";++import { AppShellProvider, useAppShell } from "@/context/AppShellContext";+import {+ LANGUAGE_STORAGE_KEY,+ RESPONSE_LANGUAGE_STORAGE_KEY,+} from "@/context/app-shell-storage";+import { apiFetch } from "@/lib/api";++vi.mock("@/lib/api", () => ({+ apiFetch: vi.fn(),+ apiUrl: (path: string) => path,+}));++function LanguageProbe() {+ const { language, languageReady } = useAppShell();+ return <output data-testid="language" data-ready={languageReady}>{language}</output>;+}++beforeEach(() => {+ localStorage.clear();+ vi.mocked(apiFetch).mockReset();+ vi.mocked(apiFetch).mockResolvedValue({+ ok: true,+ json: async () => ({ language: "uk", response_language: "fr" }),+ } as Response);+});++afterEach(() => cleanup());++it("adopts Ukrainian UI and French output preferences from the server on a new browser", async () => {+ render(<AppShellProvider><LanguageProbe /></AppShellProvider>);++ await waitFor(() => {+ expect(screen.getByTestId("language")).toHaveTextContent("uk");+ expect(screen.getByTestId("language")).toHaveAttribute("data-ready", "true");+ });+ expect(localStorage.getItem(LANGUAGE_STORAGE_KEY)).toBe("uk");+ expect(localStorage.getItem(RESPONSE_LANGUAGE_STORAGE_KEY)).toBe("fr");+});++it("keeps a browser's French UI choice while adopting its missing output preference", async () => {+ localStorage.setItem(LANGUAGE_STORAGE_KEY, "fr");+ vi.mocked(apiFetch).mockResolvedValue({+ ok: true,+ json: async () => ({ language: "uk", response_language: "uk" }),+ } as Response);+ render(<AppShellProvider><LanguageProbe /></AppShellProvider>);++ await waitFor(() => {+ expect(screen.getByTestId("language")).toHaveTextContent("fr");+ expect(screen.getByTestId("language")).toHaveAttribute("data-ready", "true");+ });+ expect(localStorage.getItem(LANGUAGE_STORAGE_KEY)).toBe("fr");+ expect(localStorage.getItem(RESPONSE_LANGUAGE_STORAGE_KEY)).toBe("uk");+});diff --git a/web/tests/app-shell-language-bootstrap.test.ts b/web/tests/app-shell-language-bootstrap.test.tsindex 46e395a8a..27190d183 100644--- a/web/tests/app-shell-language-bootstrap.test.ts+++ b/web/tests/app-shell-language-bootstrap.test.ts@@ -50,6 +50,10 @@ test("a stored choice is reported for every supported language", () => {assert.equal(hasStoredLanguage(), true);assert.equal(readStoredLanguage(), "fr");});+ withLocalStorage({ [LANGUAGE_STORAGE_KEY]: "uk" }, () => {+ assert.equal(hasStoredLanguage(), true);+ assert.equal(readStoredLanguage(), "uk");+ });});test("an unusable value still counts as a choice and normalizes to English", () => {diff --git a/web/tests/language-preferences.test.ts b/web/tests/language-preferences.test.tsindex 66ecf82f7..24eeb2a8c 100644--- a/web/tests/language-preferences.test.ts+++ b/web/tests/language-preferences.test.ts@@ -4,16 +4,27 @@ import fs from "node:fs";import path from "node:path";import { resolveResponseLanguage } from "../context/app-shell-storage";+import { APP_LANGUAGES, isAppLanguage, normalizeLanguage } from "../i18n/languages";++test("the locale registry accepts every supported language", () => {+ assert.deepEqual(APP_LANGUAGES.map(({ code }) => code), ["en", "zh", "fr", "uk"]);+ for (const { code } of APP_LANGUAGES) assert.equal(isAppLanguage(code), true);+ assert.equal(isAppLanguage("de"), false);+ assert.equal(normalizeLanguage("uk-UA"), "uk");+});test("response language remains independent from the interface language", () => {assert.equal(resolveResponseLanguage("zh", "en"), "zh");assert.equal(resolveResponseLanguage("en", "zh"), "en");assert.equal(resolveResponseLanguage("fr", "en"), "fr");assert.equal(resolveResponseLanguage("en", "fr"), "en");+ assert.equal(resolveResponseLanguage("uk", "en"), "uk");+ assert.equal(resolveResponseLanguage("en", "uk"), "en");});test("legacy settings inherit the interface language when response language is missing", () => {assert.equal(resolveResponseLanguage(null, "zh"), "zh");assert.equal(resolveResponseLanguage(undefined, "en"), "en");assert.equal(resolveResponseLanguage(null, "fr"), "fr");+ assert.equal(resolveResponseLanguage(null, "uk"), "uk");});