Skip to content

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

34.0 KB
Raw Blame
"""Branded banner + localized labels for ``deeptutor start`` / ``deeptutor init``.

Both commands read the user's language preference from
``data/user/settings/interface.json`` (default ``en``) so their startup
output matches the UI language the user has chosen.
"""

from __future__ import annotations

from rich.align import Align
from rich.console import Console
from rich.panel import Panel
from rich.text import Text

from deeptutor.__version__ import __version__

_ASCII_LOGO = r""" ____                  _____      _
|  _ \  ___  ___ _ __ |_   _|   _| |_ ___  _ __
| | | |/ _ \/ _ \ '_ \  | || | | | __/ _ \| '__|
| |_| |  __/  __/ |_) | | || |_| | || (_) | |
|____/ \___|\___| .__/  |_| \__,_|\__\___/|_|
                |_|"""


LABELS: dict[str, dict[str, str]] = {
    "en": {
        "tagline": "Agent-Native Personalized Tutoring",
        "lab": "Data Intelligence Lab @ HKU",
        # init
        "init.mode": "Workspace initializer",
        "init.workspace": "Workspace",
        "init.note_settings_dir": "Settings will be written under data/user/settings.",
        "init.cancelled": "Setup cancelled. Nothing was saved.",
        "init.step_ports": "Step {n}/{total} · Ports",
        "init.step_llm": "Step {n}/{total} · LLM provider",
        "init.step_embedding": "Step {n}/{total} · Embedding (RAG / Knowledge Base)",
        "init.step_search": "Step {n}/{total} · Web search",
        "init.step_review": "Step {n}/{total} · Review & save",
        "init.backend_port": "Backend port",
        "init.frontend_port": "Frontend port",
        "init.llm_section": "LLM provider",
        "init.pick_provider": "Pick an LLM provider",
        "init.pick_embedding_provider": "Pick an embedding provider",
        "init.show_all": "Show all providers",
        "init.custom_provider": "Custom / Other",
        "init.skip_step": "Skip / configure later",
        "init.back": "Back",
        "init.skipped": "Skipped — you can configure this later in Web Settings.",
        "init.binding": "Binding",
        "init.base_url": "Base URL",
        "init.api_key": "API key",
        "init.api_key_env_detected": "Detected {env_var}={masked} in your environment. Use it?",
        "init.api_key_prompt": "API key (input hidden, Enter to skip)",
        "init.api_key_reuse_llm": "Reuse the LLM API key {masked}?",
        "init.edit_base_url": "Edit Base URL?",
        "init.new_base_url": "New Base URL",
        "init.model": "Model",
        "init.fetch_models": "Fetching available models from {url} ...",
        "init.fetch_models_ok": "Found {count} model(s).",
        "init.fetch_models_fail": "Could not list models ({error}). Using fallback list.",
        "init.pick_model": "Pick a model — or type {marker} to enter your own",
        "init.custom_model": "Custom model name",
        "init.embedding_section": "Embedding provider",
        "init.embedding_endpoint": "Embedding endpoint URL",
        "init.embedding_api_key": "Embedding API key",
        "init.embedding_model": "Embedding model",
        "init.embedding_dimension": "Embedding dimension (blank for auto)",
        "init.search_section": "Web search provider",
        "init.pick_search_provider": "Pick a web-search provider",
        "init.search_api_key_prompt": "API key (input hidden, Enter to skip)",
        "init.search_base_url_prompt": "Base URL",
        "init.search_no_key_note": "{label} does not need an API key.",
        "init.search_disabled_note": "Web search will be disabled. Agents will skip search tools.",
        "init.review_search": "Search",
        "init.review_search_disabled": "disabled",
        "init.probe_offer": "Test connection now?",
        "init.probe_running": "Testing {what} ...",
        "init.probe_ok": "{what} OK  ·  {ms}ms",
        "init.probe_fail": "{what} failed: {error}",
        "init.probe_retry": "Re-enter API key and retry?",
        "init.copilot_reuse_login": "Reuse the GitHub Copilot login for {account}?",
        "init.copilot_login_start": "Starting GitHub device login ...",
        "init.copilot_login_ok": "GitHub Copilot login succeeded for {account}.",
        "init.copilot_login_fail": "GitHub Copilot login failed: {error}",
        "init.review_title": "Review",
        "init.review_llm": "LLM",
        "init.review_embedding": "Embedding",
        "init.review_ports": "Ports",
        "init.review_ports_value": "backend {backend}, frontend {frontend}",
        "init.confirm_save": "Save these settings?",
        "init.saved": "Settings saved. You can edit them later in the Web Settings page or data/user/settings/.",
        "init.next_step": "Run `deeptutor start` to launch DeepTutor.",
        "init.choice": "Choice",
        "init.choice_invalid": "Invalid choice. Try again.",
        # start (launcher)
        "start.mode": "Launching backend + frontend",
        "start.backend": "Backend",
        "start.browser_api": "Browser API",
        "start.frontend": "Frontend",
        "start.workspace": "Workspace",
        "start.frontend_runtime": "Frontend runtime",
        "start.press_ctrl_c": "Press Ctrl+C to stop.",
        "start.detached_started": "DeepTutor is starting in the background (launcher PID {pid}).",
        "start.detached_already_running": (
            "A detached DeepTutor launcher is already running (PID {pid}). Log: {log}"
        ),
        "start.detached_log": "Log: {path}",
        "start.detached_stop_hint": 'Stop it with `deeptutor stop --home "{home}"`.',
        "start.starting_backend": "Starting backend ...",
        "start.starting_frontend": "Starting frontend ...",
        "start.reusing_frontend": "Reusing existing frontend at {url} (PID {pid}).",
        "start.restarting_frontend": (
            "Existing frontend at {url} is not responding; restarting it (PID {pid})."
        ),
        "start.frontend_restart_failed": (
            "Existing frontend at {url} is not responding and could not be stopped automatically. "
            "Stop PID {pid} and run `deeptutor start` again."
        ),
        "start.waiting_for": "Waiting for {name} at {url} ...",
        "start.ready": "{name} is ready.",
        "start.open_in_browser": "Open {url} in your browser.",
        "start.received_signal": "Received {signal}; shutting down ...",
        "start.stopping": "Stopping {name} (PID {pid})",
        "start.exited": "{name} exited with code {code}",
        "stop.not_running": "No detached DeepTutor launcher is running.",
        "stop.requested": "Requested a graceful stop from launcher PID {pid}.",
        "stop.complete": "DeepTutor stopped.",
        "stop.timeout": "Launcher PID {pid} did not stop in time. Check {log}.",
        "start.not_ready": (
            "{name} did not become ready within {timeout}s. "
            "Slow hardware or a workspace with data to migrate can need longer; "
            "set {env} to a larger number of seconds."
        ),
        "start.port_in_use": (
            "DeepTutor cannot start because port(s) already in use: {ports}. "
            "Stop the existing process or change data/user/settings/system.json."
        ),
        "start.port_conflict_title": "Port conflict detected:",
        "start.port_conflict_line": "  {role} port {port} is in use by:",
        "start.port_conflict_proc": "    PID {pid} · {command}",
        "start.port_conflict_unknown_proc": "    (process info unavailable)",
        "start.port_option_change": "Change ports (saved to data/user/settings/system.json)",
        "start.port_option_kill": "Stop the occupying process(es) and continue",
        "start.port_invalid": "Invalid port: {value}. Enter a free port between 1 and 65535.",
        "start.port_saved": "Ports saved to {path}.",
        "start.port_killing": "Stopping PID {pid} ({command}) ...",
        "start.port_kill_failed": "Could not free port {port} (PID {pid}).",
        "start.port_freed": "Port {port} released.",
    },
    "zh": {
        "tagline": "智能体原生的个性化辅导",
        "lab": "香港大学数据智能实验室",
        # init
        "init.mode": "工作目录初始化",
        "init.workspace": "工作目录",
        "init.note_settings_dir": "配置文件将写入 data/user/settings 目录。",
        "init.cancelled": "已取消,未保存任何更改。",
        "init.step_ports": "第 {n}/{total} 步 · 端口",
        "init.step_llm": "第 {n}/{total} 步 · 大模型服务",
        "init.step_embedding": "第 {n}/{total} 步 · 向量模型 (知识库 / RAG)",
        "init.step_search": "第 {n}/{total} 步 · 联网搜索",
        "init.step_review": "第 {n}/{total} 步 · 确认并保存",
        "init.backend_port": "后端端口",
        "init.frontend_port": "前端端口",
        "init.llm_section": "大模型服务",
        "init.pick_provider": "请选择大模型服务",
        "init.pick_embedding_provider": "请选择向量模型服务",
        "init.show_all": "查看全部服务商",
        "init.custom_provider": "其他 / 自定义",
        "init.skip_step": "跳过 / 稍后配置",
        "init.back": "返回上一步",
        "init.skipped": "已跳过 —— 后续可在 Web 设置页中配置。",
        "init.binding": "服务类型",
        "init.base_url": "Base URL",
        "init.api_key": "API Key",
        "init.api_key_env_detected": "已检测到环境变量 {env_var}={masked},是否使用?",
        "init.api_key_prompt": "API Key (输入不显示,直接回车跳过)",
        "init.api_key_reuse_llm": "复用大模型的 API Key ({masked})?",
        "init.edit_base_url": "需要修改 Base URL 吗?",
        "init.new_base_url": "新的 Base URL",
        "init.model": "模型",
        "init.fetch_models": "正在从 {url} 拉取可用模型列表 ...",
        "init.fetch_models_ok": "找到 {count} 个模型。",
        "init.fetch_models_fail": "无法获取模型列表 ({error}),将使用本地推荐列表。",
        "init.pick_model": "请选择模型 —— 或输入 {marker} 手动填写",
        "init.custom_model": "自定义模型名称",
        "init.embedding_section": "向量模型服务",
        "init.embedding_endpoint": "向量服务地址",
        "init.embedding_api_key": "向量服务 API Key",
        "init.embedding_model": "向量模型",
        "init.embedding_dimension": "向量维度 (留空自动检测)",
        "init.search_section": "联网搜索服务",
        "init.pick_search_provider": "请选择联网搜索服务",
        "init.search_api_key_prompt": "API Key (输入不显示,直接回车跳过)",
        "init.search_base_url_prompt": "Base URL",
        "init.search_no_key_note": "{label} 无需 API Key。",
        "init.search_disabled_note": "联网搜索将被禁用。Agent 将跳过搜索工具。",
        "init.review_search": "搜索",
        "init.review_search_disabled": "已禁用",
        "init.probe_offer": "立即测试连接?",
        "init.probe_running": "正在测试 {what} ...",
        "init.probe_ok": "{what} 连接成功  ·  {ms}ms",
        "init.probe_fail": "{what} 连接失败: {error}",
        "init.probe_retry": "重新输入 API Key 并重试?",
        "init.copilot_reuse_login": "复用 {account} 的 GitHub Copilot 登录?",
        "init.copilot_login_start": "正在启动 GitHub 设备登录 ...",
        "init.copilot_login_ok": "GitHub Copilot 登录成功: {account}。",
        "init.copilot_login_fail": "GitHub Copilot 登录失败: {error}",
        "init.review_title": "配置确认",
        "init.review_llm": "大模型",
        "init.review_embedding": "向量",
        "init.review_ports": "端口",
        "init.review_ports_value": "后端 {backend},前端 {frontend}",
        "init.confirm_save": "确认保存以上配置?",
        "init.saved": "配置已保存。后续可在 Web 设置页或 data/user/settings/ 中修改。",
        "init.next_step": "运行 `deeptutor start` 启动 DeepTutor。",
        "init.choice": "请选择",
        "init.choice_invalid": "无效选项,请重新输入。",
        # start (launcher)
        "start.mode": "启动后端 + 前端",
        "start.backend": "后端",
        "start.browser_api": "前端 API",
        "start.frontend": "前端",
        "start.workspace": "工作目录",
        "start.frontend_runtime": "前端运行模式",
        "start.press_ctrl_c": "按 Ctrl+C 停止。",
        "start.detached_started": "DeepTutor 正在后台启动(launcher PID {pid})。",
        "start.detached_already_running": (
            "已有后台 DeepTutor launcher 正在运行(PID {pid})。日志:{log}"
        ),
        "start.detached_log": "日志:{path}",
        "start.detached_stop_hint": '运行 `deeptutor stop --home "{home}"` 停止。',
        "start.starting_backend": "正在启动后端服务 ...",
        "start.starting_frontend": "正在启动前端服务 ...",
        "start.reusing_frontend": "复用已运行的前端 {url} (PID {pid})。",
        "start.restarting_frontend": "已运行的前端 {url} 无响应,正在重启 (PID {pid})。",
        "start.frontend_restart_failed": (
            "已运行的前端 {url} 无响应,且无法自动停止。"
            "请先停止 PID {pid},然后重新运行 `deeptutor start`。"
        ),
        "start.waiting_for": "正在等待 {name} ({url}) ...",
        "start.ready": "{name} 已就绪。",
        "start.open_in_browser": "请在浏览器中打开 {url}。",
        "start.received_signal": "收到 {signal} 信号,正在关闭 ...",
        "start.stopping": "正在停止 {name} (PID {pid})",
        "start.exited": "{name} 已退出 (退出码 {code})",
        "stop.not_running": "当前没有后台 DeepTutor launcher 在运行。",
        "stop.requested": "已请求 launcher PID {pid} 正常停止。",
        "stop.complete": "DeepTutor 已停止。",
        "stop.timeout": "launcher PID {pid} 未能及时停止,请检查 {log}。",
        "start.not_ready": (
            "{name} 在 {timeout} 秒内未就绪。"
            "硬件较慢或工作区需要迁移数据时启动会更久,"
            "可将 {env} 设为更大的秒数。"
        ),
        "start.port_in_use": (
            "无法启动 DeepTutor,端口已被占用: {ports}。"
            "请先停止占用进程,或修改 data/user/settings/system.json 中的端口设置。"
        ),
        "start.port_conflict_title": "检测到端口被占用:",
        "start.port_conflict_line": "  {role}端口 {port} 被以下进程占用:",
        "start.port_conflict_proc": "    PID {pid} · {command}",
        "start.port_conflict_unknown_proc": "    (无法获取进程信息)",
        "start.port_option_change": "更改端口设置 (写入 data/user/settings/system.json)",
        "start.port_option_kill": "停止占用进程并继续启动",
        "start.port_invalid": "无效端口: {value}。请输入 1-65535 之间且未被占用的端口。",
        "start.port_saved": "端口设置已保存到 {path}。",
        "start.port_killing": "正在停止 PID {pid} ({command}) ...",
        "start.port_kill_failed": "无法释放端口 {port} (PID {pid})。",
        "start.port_freed": "端口 {port} 已释放。",
    },
    "de": {
        "tagline": "Agent-native, personalisierte Lernbegleitung",
        "lab": "Data Intelligence Lab @ HKU",
        "init.mode": "Workspace-Einrichtung",
        "init.workspace": "Workspace",
        "init.note_settings_dir": "Einstellungen werden unter data/user/settings gespeichert.",
        "init.cancelled": "Einrichtung abgebrochen. Nichts wurde gespeichert.",
        "init.step_ports": "Schritt {n}/{total} · Ports",
        "init.step_llm": "Schritt {n}/{total} · LLM-Provider",
        "init.step_embedding": "Schritt {n}/{total} · Embedding (RAG / Knowledge Base)",
        "init.step_search": "Schritt {n}/{total} · Websuche",
        "init.step_review": "Schritt {n}/{total} · Prüfen und speichern",
        "init.backend_port": "Backend-Port",
        "init.frontend_port": "Frontend-Port",
        "init.llm_section": "LLM-Provider",
        "init.pick_provider": "Wähle einen LLM-Provider",
        "init.pick_embedding_provider": "Wähle einen Embedding-Provider",
        "init.show_all": "Alle Provider anzeigen",
        "init.custom_provider": "Eigener / Anderer",
        "init.skip_step": "Überspringen / später einrichten",
        "init.back": "Zurück",
        "init.skipped": "Übersprungen. Du kannst das später in den Web-Einstellungen einrichten.",
        "init.binding": "Binding",
        "init.base_url": "Base URL",
        "init.api_key": "API-Key",
        "init.api_key_env_detected": "{env_var}={masked} in deiner Umgebung gefunden. Verwenden?",
        "init.api_key_prompt": "API-Key (Eingabe verborgen, Enter zum Überspringen)",
        "init.api_key_reuse_llm": "LLM-API-Key {masked} wiederverwenden?",
        "init.copilot_reuse_login": "GitHub-Copilot-Anmeldung für {account} wiederverwenden?",
        "init.copilot_login_start": "GitHub-Geräteanmeldung wird gestartet ...",
        "init.copilot_login_ok": "GitHub-Copilot-Anmeldung für {account} erfolgreich.",
        "init.copilot_login_fail": "GitHub-Copilot-Anmeldung fehlgeschlagen: {error}",
        "init.edit_base_url": "Base URL ändern?",
        "init.new_base_url": "Neue Base URL",
        "init.model": "Modell",
        "init.fetch_models": "Verfügbare Modelle werden von {url} abgerufen ...",
        "init.fetch_models_ok": "{count} Modell(e) gefunden.",
        "init.fetch_models_fail": "Modelle konnten nicht abgerufen werden ({error}). Ersatzliste wird verwendet.",
        "init.pick_model": "Wähle ein Modell oder gib {marker} ein, um ein eigenes einzutragen",
        "init.custom_model": "Name des eigenen Modells",
        "init.embedding_section": "Embedding-Provider",
        "init.embedding_endpoint": "Embedding-Endpoint-URL",
        "init.embedding_api_key": "Embedding-API-Key",
        "init.embedding_model": "Embedding-Modell",
        "init.embedding_dimension": "Embedding-Dimension (leer für automatisch)",
        "init.search_section": "Websuche-Provider",
        "init.pick_search_provider": "Wähle einen Websuche-Provider",
        "init.search_api_key_prompt": "API-Key (Eingabe verborgen, Enter zum Überspringen)",
        "init.search_base_url_prompt": "Base URL",
        "init.search_no_key_note": "{label} braucht keinen API-Key.",
        "init.search_disabled_note": "Die Websuche wird deaktiviert. Agents überspringen Such-Tools.",
        "init.review_search": "Suche",
        "init.review_search_disabled": "deaktiviert",
        "init.probe_offer": "Verbindung jetzt testen?",
        "init.probe_running": "{what} wird getestet ...",
        "init.probe_ok": "{what} OK  ·  {ms}ms",
        "init.probe_fail": "{what} fehlgeschlagen: {error}",
        "init.probe_retry": "API-Key neu eingeben und erneut versuchen?",
        "init.review_title": "Überblick",
        "init.review_llm": "LLM",
        "init.review_embedding": "Embedding",
        "init.review_ports": "Ports",
        "init.review_ports_value": "Backend {backend}, Frontend {frontend}",
        "init.confirm_save": "Diese Einstellungen speichern?",
        "init.saved": "Einstellungen gespeichert. Du kannst sie später in den Web-Einstellungen oder unter data/user/settings/ ändern.",
        "init.next_step": "Starte DeepTutor mit `deeptutor start`.",
        "init.choice": "Auswahl",
        "init.choice_invalid": "Ungültige Auswahl. Versuch es noch einmal.",
        "start.mode": "Backend und Frontend werden gestartet",
        "start.backend": "Backend",
        "start.browser_api": "Browser-API",
        "start.frontend": "Frontend",
        "start.workspace": "Workspace",
        "start.frontend_runtime": "Frontend-Laufzeit",
        "start.press_ctrl_c": "Zum Beenden Strg+C drücken.",
        "start.detached_started": "DeepTutor startet im Hintergrund (Launcher-PID {pid}).",
        "start.detached_already_running": "Ein DeepTutor-Launcher läuft bereits im Hintergrund (PID {pid}). Log: {log}",
        "start.detached_log": "Log: {path}",
        "start.detached_stop_hint": 'Beenden mit `deeptutor stop --home "{home}"`.',
        "start.starting_backend": "Backend wird gestartet ...",
        "start.starting_frontend": "Frontend wird gestartet ...",
        "start.reusing_frontend": "Vorhandenes Frontend unter {url} wird weiterverwendet (PID {pid}).",
        "start.restarting_frontend": "Vorhandenes Frontend unter {url} reagiert nicht und wird neu gestartet (PID {pid}).",
        "start.frontend_restart_failed": "Vorhandenes Frontend unter {url} reagiert nicht und konnte nicht automatisch beendet werden. Beende PID {pid} und führe `deeptutor start` erneut aus.",
        "start.waiting_for": "Warte auf {name} unter {url} ...",
        "start.ready": "{name} ist bereit.",
        "start.open_in_browser": "Öffne {url} in deinem Browser.",
        "start.received_signal": "{signal} empfangen, wird beendet ...",
        "start.stopping": "{name} wird beendet (PID {pid})",
        "start.exited": "{name} wurde mit Code {code} beendet",
        "stop.not_running": "Es läuft kein DeepTutor-Launcher im Hintergrund.",
        "stop.requested": "Launcher-PID {pid} wurde aufgefordert, sich sauber zu beenden.",
        "stop.complete": "DeepTutor wurde beendet.",
        "stop.timeout": "Launcher-PID {pid} hat sich nicht rechtzeitig beendet. Prüfe {log}.",
        "start.not_ready": "{name} war nach {timeout}s nicht bereit. Langsame Hardware oder ein Workspace mit zu migrierenden Daten kann länger brauchen; setze {env} auf eine größere Zahl an Sekunden.",
        "start.port_in_use": "DeepTutor kann nicht starten, weil Port(s) bereits belegt sind: {ports}. Beende den laufenden Prozess oder ändere data/user/settings/system.json.",
        "start.port_conflict_title": "Port-Konflikt erkannt:",
        "start.port_conflict_line": "  {role}-Port {port} wird verwendet von:",
        "start.port_conflict_proc": "    PID {pid} · {command}",
        "start.port_conflict_unknown_proc": "    (keine Prozessinformation verfügbar)",
        "start.port_option_change": "Ports ändern (wird in data/user/settings/system.json gespeichert)",
        "start.port_option_kill": "Belegende(n) Prozess(e) beenden und fortfahren",
        "start.port_invalid": "Ungültiger Port: {value}. Gib einen freien Port zwischen 1 und 65535 ein.",
        "start.port_saved": "Ports in {path} gespeichert.",
        "start.port_killing": "PID {pid} ({command}) wird beendet ...",
        "start.port_kill_failed": "Port {port} konnte nicht freigegeben werden (PID {pid}).",
        "start.port_freed": "Port {port} freigegeben.",
    },
    "uk": {
        "tagline": "Агентно-орієнтоване персоналізоване навчання",
        "lab": "Data Intelligence Lab @ HKU",
        "init.mode": "Майстер ініціалізації робочого простору",
        "init.workspace": "Робочий простір",
        "init.note_settings_dir": "Налаштування буде записано в data/user/settings.",
        "init.cancelled": "Налаштування скасовано. Нічого не збережено.",
        "init.step_ports": "Крок {n}/{total} · Порти",
        "init.step_llm": "Крок {n}/{total} · Провайдер LLM",
        "init.step_embedding": "Крок {n}/{total} · Ембединги (RAG / База знань)",
        "init.step_search": "Крок {n}/{total} · Веб-пошук",
        "init.step_review": "Крок {n}/{total} · Перевірка та збереження",
        "init.backend_port": "Порт бекенду",
        "init.frontend_port": "Порт фронтенду",
        "init.llm_section": "Провайдер LLM",
        "init.pick_provider": "Виберіть провайдера LLM",
        "init.pick_embedding_provider": "Виберіть провайдера ембедингів",
        "init.show_all": "Показати всіх провайдерів",
        "init.custom_provider": "Власний / Інший",
        "init.skip_step": "Пропустити / налаштувати пізніше",
        "init.back": "Назад",
        "init.skipped": "Пропущено — налаштуйте це пізніше у веб-налаштуваннях.",
        "init.binding": "Прив'язка",
        "init.base_url": "Базова URL-адреса",
        "init.api_key": "Ключ API",
        "init.api_key_env_detected": "Виявлено {env_var}={masked} у вашому середовищі. Використати його?",
        "init.api_key_prompt": "Ключ API (введення приховане, Enter для пропуску)",
        "init.api_key_reuse_llm": "Повторно використати ключ API LLM {masked}?",
        "init.copilot_reuse_login": "Повторно використати вхід у GitHub Copilot для {account}?",
        "init.copilot_login_start": "Починаємо вхід у GitHub за кодом пристрою ...",
        "init.copilot_login_ok": "Вхід у GitHub Copilot для {account} виконано успішно.",
        "init.copilot_login_fail": "Не вдалося ввійти в GitHub Copilot: {error}",
        "init.edit_base_url": "Змінити базову URL-адресу?",
        "init.new_base_url": "Нова базова URL-адреса",
        "init.model": "Модель",
        "init.fetch_models": "Отримання доступних моделей з {url} ...",
        "init.fetch_models_ok": "Знайдено моделей: {count}.",
        "init.fetch_models_fail": "Не вдалося отримати список моделей ({error}). Використовується резервний список.",
        "init.pick_model": "Виберіть модель — або введіть {marker}, щоб вказати власну",
        "init.custom_model": "Назва власної моделі",
        "init.embedding_section": "Провайдер ембедингів",
        "init.embedding_endpoint": "URL-адреса ендпоінту ембедингів",
        "init.embedding_api_key": "Ключ API ембедингів",
        "init.embedding_model": "Модель ембедингів",
        "init.embedding_dimension": "Розмірність ембедингів (залиште пустим для автовизначення)",
        "init.search_section": "Провайдер веб-пошуку",
        "init.pick_search_provider": "Оберіть провайдера веб-пошуку",
        "init.search_api_key_prompt": "API-ключ (введення приховане, Enter — пропустити)",
        "init.search_base_url_prompt": "Базовий URL",
        "init.search_no_key_note": "{label} не потребує API-ключа.",
        "init.search_disabled_note": "Веб-пошук буде вимкнено. Агенти пропускатимуть інструменти пошуку.",
        "init.review_search": "Пошук",
        "init.review_search_disabled": "вимкнено",
        "init.probe_offer": "Перевірити з'єднання зараз?",
        "init.probe_running": "Перевірка {what} ...",
        "init.probe_ok": "{what} ОК  ·  {ms}мс",
        "init.probe_fail": "{what} не вдалося: {error}",
        "init.probe_retry": "Ввести API-ключ повторно та повторити спробу?",
        "init.review_title": "Перегляд",
        "init.review_llm": "LLM",
        "init.review_embedding": "Ембединг",
        "init.review_ports": "Порти",
        "init.review_ports_value": "бекенд {backend}, фронтенд {frontend}",
        "init.confirm_save": "Зберегти ці налаштування?",
        "init.saved": "Налаштування збережено. Ви можете змінити їх пізніше на сторінці веб-налаштувань або в data/user/settings/.",
        "init.next_step": "Запустіть `deeptutor start`, щоб запустити DeepTutor.",
        "init.choice": "Вибір",
        "init.choice_invalid": "Невірний вибір. Спробуйте ще раз.",
        "start.mode": "Запуск бекенду + фронтенду",
        "start.backend": "Бекенд",
        "start.browser_api": "Browser API",
        "start.frontend": "Фронтенд",
        "start.workspace": "Робочий простір",
        "start.frontend_runtime": "Середовище виконання фронтенду",
        "start.press_ctrl_c": "Натисніть Ctrl+C для зупинки.",
        "start.detached_started": "DeepTutor запускається у фоновому режимі (PID лаунчера {pid}).",
        "start.detached_already_running": "Відокремлений лаунчер DeepTutor вже запущено (PID {pid}). Журнал: {log}",
        "start.detached_log": "Журнал: {path}",
        "start.detached_stop_hint": 'Зупиніть його командою `deeptutor stop --home "{home}"`.',
        "start.starting_backend": "Запуск бекенду ...",
        "start.starting_frontend": "Запуск фронтенду ...",
        "start.reusing_frontend": "Використання наявного фронтенду за адресою {url} (PID {pid}).",
        "start.restarting_frontend": "Наявний фронтенд за адресою {url} не відповідає; перезапуск (PID {pid}).",
        "start.frontend_restart_failed": "Наявний фронтенд за адресою {url} не відповідає і не може бути зупинений автоматично. Зупиніть PID {pid} та знову запустіть `deeptutor start`.",
        "start.waiting_for": "Очікування {name} за адресою {url} ...",
        "start.ready": "{name} готовий.",
        "start.open_in_browser": "Відкрийте {url} у браузері.",
        "start.received_signal": "Отримано {signal}; завершення роботи ...",
        "start.stopping": "Зупинення {name} (PID {pid})",
        "start.exited": "{name} завершився з кодом {code}",
        "stop.not_running": "Відкріплений лаунчер DeepTutor не запущено.",
        "stop.requested": "Запит на коректну зупинку від лаунчера PID {pid}.",
        "stop.complete": "DeepTutor зупинено.",
        "stop.timeout": "Лаунчер PID {pid} не зупинився вчасно. Перевірте {log}.",
        "start.not_ready": "{name} не готовий протягом {timeout} с",
        "start.port_in_use": "DeepTutor не може запуститися: порт(и) вже зайнято: {ports}. Зупиніть наявний процес або змініть data/user/settings/system.json.",
        "start.port_conflict_title": "Виявлено конфлікт портів:",
        "start.port_conflict_line": "  порт {role} {port} зайнято:",
        "start.port_conflict_proc": "    PID {pid} · {command}",
        "start.port_conflict_unknown_proc": "    (інформація про процес недоступна)",
        "start.port_option_change": "Змінити порти (збережеться в data/user/settings/system.json)",
        "start.port_option_kill": "Зупинити процес(и), що займають порт, і продовжити",
        "start.port_invalid": "Недійсний порт: {value}. Введіть вільний порт від 1 до 65535.",
        "start.port_saved": "Порти збережено в {path}.",
        "start.port_killing": "Зупинення PID {pid} ({command}) ...",
        "start.port_kill_failed": "Не вдалося звільнити порт {port} (PID {pid}).",
        "start.port_freed": "Порт {port} звільнено.",
    },
}


def _pick_language(language: str | None) -> str:
    if not language:
        return "en"
    code = str(language).lower().strip()
    if code in {"zh", "zh-cn", "zh-hans", "chinese", "cn"}:
        return "zh"
    if code in {"de", "de-de", "de-at", "de-ch", "german", "deutsch"}:
        return "de"
    if code in {"uk", "uk-ua", "ukrainian", "ua"}:
        return "uk"
    return "en"


def resolve_language(default: str = "en") -> str:
    """Read the saved UI language, falling back to ``default``.

    Safe to call before the runtime is fully initialized; any failure
    silently falls back to the default.
    """
    try:
        from deeptutor.services.settings.interface_settings import get_ui_language

        return _pick_language(get_ui_language(default))
    except Exception:
        return _pick_language(default)


def labels_for(language: str | None) -> dict[str, str]:
    return LABELS[_pick_language(language)]


def render_banner(language: str | None, *, mode_key: str | None = None) -> Panel:
    """Build the branded banner panel.

    Parameters
    ----------
    language:
        Language code (``"en"``/``"zh"``). Unknown values fall back to English.
    mode_key:
        Optional key into ``LABELS[lang]`` to display under the tagline
        (e.g. ``"start.mode"``, ``"init.mode"``).
    """

    lang = _pick_language(language)
    strings = LABELS[lang]

    logo = Text(_ASCII_LOGO, style="bold bright_cyan")
    tagline_line = f"{strings['tagline']}  ·  v{__version__}"

    body = Text()
    body.append(logo)
    body.append("\n\n")
    body.append(tagline_line, style="bold white")
    body.append("\n")
    body.append(strings["lab"], style="dim")
    if mode_key and mode_key in strings:
        body.append("\n")
        body.append(strings[mode_key], style="italic bright_magenta")

    return Panel(
        Align.left(body),
        title="[bold bright_cyan]DeepTutor[/]",
        border_style="bright_cyan",
        padding=(1, 2),
    )


def print_banner(
    console: Console | None = None,
    *,
    language: str | None = None,
    mode_key: str | None = None,
) -> None:
    """Print the branded banner to ``console`` (creates one if omitted)."""

    target = console or Console()
    target.print(render_banner(language, mode_key=mode_key))


__all__: tuple[str, ...] = (
    "LABELS",
    "labels_for",
    "print_banner",
    "render_banner",
    "resolve_language",
)