Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

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.py
index 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_language
from deeptutor.services.prompt.lookup import prompt_text as _prompt_text
from 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.py
index 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] = None
sidebar_nav_order: Optional[SidebarNavOrder] = None
code_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 = None
sidebar_description: str | None = None
sidebar_nav_order: SidebarNavOrder | None = None
code_block_theme: str | None = None
@@ -191,7 +192,7 @@ class ThemeUpdate(BaseModel):
class LanguageUpdate(BaseModel):
- language: Literal["zh", "en", "fr"]
+ language: UiLanguage
class SidebarDescriptionUpdate(BaseModel):
diff --git a/deeptutor/services/config/launch_settings.py b/deeptutor/services/config/launch_settings.py
index 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 None
diff --git a/deeptutor/services/config/settings_spec.py b/deeptutor/services/config/settings_spec.py
index 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.py
index e257a119a..6ddb0951c 100644
--- a/deeptutor/services/settings/interface_settings.py
+++ b/deeptutor/services/settings/interface_settings.py
@@ -13,11 +13,13 @@ import os
from pathlib import Path
import tempfile
import threading
-from typing import Any
+from typing import Any, Literal
from deeptutor.services.path_service import get_path_service
from 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.py
index 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"] == language
assert response["response_language"] == "en"
persisted = settings_router.load_ui_settings()
- assert persisted["language"] == "fr"
+ assert persisted["language"] == language
assert persisted["response_language"] == "en"
+ assert (await settings_router.get_ui_settings())["language"] == language
+ assert settings_router.LanguageUpdate(language=language).language == language
def 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.py
index 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 annotations
import json
from 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 == expected
assert "interface.json" in settings.source
diff --git a/tests/services/prompt/test_language_directive.py b/tests/services/prompt/test_language_directive.py
index 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) -> N
assembler = 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 rendered
diff --git a/web/components/settings/shared.tsx b/web/components/settings/shared.tsx
index 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.tsx
index 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.ts
index 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.ts
index 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.json
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.tsx
new file mode 100644
index 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.ts
index 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.ts
index 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");
});