14.1 · 翻译系统架构（Translation System Architecture）

多模型对话工作台与知识应用入口 · 本章是 Open WebUI DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目Open WebUI 章节14.1 状态全文译文模块系统架构、工具、记忆与模型调用、检索、召回与知识系统

项目要点页2.5 参考项目项目章节目录Open WebUI DeepWiki 原始章节Translation System Architecture 上一章14 下一章14.2

源码线索

src/lib/i18n/index.ts
src/lib/i18n/locales/ca-ES/translation.json
src/lib/i18n/locales/de-DE/translation.json
src/lib/i18n/locales/en-GB/translation.json
src/lib/i18n/locales/en-US/translation.json
src/lib/i18n/locales/es-ES/translation.json
src/lib/i18n/locales/fa-IR/translation.json
src/lib/i18n/locales/fr-CA/translation.json
src/lib/i18n/locales/fr-FR/translation.json
src/lib/i18n/locales/languages.json

模块标签

系统架构
工具、记忆与模型调用
检索、召回与知识系统

中文译文

翻译系统架构（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/open-webui/open-webui/14.1-translation-system-architecture

翻译时间：2026-06-09T16:11:23.815Z

翻译模型：deepseek-chat

原文字符数：9805

项目：Open WebUI (open-webui)

---

翻译系统架构

目的与范围

本文档描述了 Open WebUI 中的国际化（i18n）系统架构，该系统为整个应用程序提供多语言支持。目前系统支持超过 30 种语言，采用基于 JSON 的翻译格式，具备动态语言包加载和变量插值能力。它确保聊天界面、设置和管理面板都能获得本地化体验。

系统概述

i18n 系统是一个关键的基础设施组件，为所有面向用户的组件提供翻译覆盖。它利用基于 Svelte 的 store 来管理当前语言状态，并提供翻译函数供组件级别集成。

翻译架构数据流

下图展示了翻译数据如何从静态 JSON 文件流向渲染后的 Svelte 组件。

graph TB
    subgraph "TranslationSourceSpace"
        ["JSON_EN_US"]["src/lib/i18n/locales/en-US/translation.json"]
        ["JSON_ZH_CN"]["src/lib/i18n/locales/zh-CN/translation.json"]
        ["JSON_DE_DE"]["src/lib/i18n/locales/de-DE/translation.json"]
        ["LANG_LIST"]["src/lib/i18n/locales/languages.json"]
    end

    subgraph "CodeEntitySpace"
        ["I18N_INDEX_TS"]["src/lib/i18n/index.ts"]
        ["I18N_STORE"]["i18next / svelte-i18n store"]
        ["T_FUNC"]["$t() 翻译函数"]
    end

    subgraph "UIComponentSpace"
        ["CHAT_UI"]["Chat.svelte"]
        ["SETTINGS_UI"]["SettingsModal.svelte"]
        ["SIDEBAR_UI"]["Sidebar.svelte"]
    end

    ["JSON_EN_US"] --> ["I18N_INDEX_TS"]
    ["JSON_ZH_CN"] --> ["I18N_INDEX_TS"]
    ["JSON_DE_DE"] --> ["I18N_INDEX_TS"]
    ["LANG_LIST"] --> ["I18N_INDEX_TS"]

    ["I18N_INDEX_TS"] --> ["I18N_STORE"]
    ["I18N_STORE"] --> ["T_FUNC"]

    ["T_FUNC"] --> ["CHAT_UI"]
    ["T_FUNC"] --> ["SETTINGS_UI"]
    ["T_FUNC"] --> ["SIDEBAR_UI"]

图：翻译数据流

来源：src/lib/i18n/locales/languages.json:1-242，src/lib/i18n/index.ts:1-8，src/lib/i18n/locales/en-US/translation.json:1-100

翻译文件结构

所有翻译文件都遵循一致的 JSON 结构，位于 src/lib/i18n/locales/{locale-code}/translation.json。每个文件包含扁平的键值对，其中键是英文源字符串，值是本地化后的翻译。

语言环境元数据

系统在 src/lib/i18n/locales/languages.json 中维护一个支持语言的注册表。每个条目定义了语言环境的 code 和显示用的 title。

属性	描述	示例
`code`	ISO 语言环境标识符	`"zh-CN"`
`title`	人类可读的名称	`"Chinese (简体中文)"`

来源：src/lib/i18n/locales/languages.json:235-241

翻译条目格式

每个翻译文件由 JSON 键值对组成。键是作为翻译标识符的英文字符串，值是翻译后的字符串。如果某个翻译缺失（在 en-US 源文件中常见），则值为空字符串 ""，此时会回退到键本身。

示例：简体中文

{
  "About": "关于",
  "Account": "账号",
  "Add User": "添加用户",
  "Admin Panel": "管理员面板"
}

来源：src/lib/i18n/locales/zh-CN/translation.json:48-108

示例：德语

{
  "About": "Über",
  "Account": "Konto",
  "Add User": "Benutzer hinzufügen",
  "Admin Panel": "Admin-Bereich"
}

来源：src/lib/i18n/locales/de-DE/translation.json:49-109

变量插值系统

翻译系统通过使用 {{VARIABLE}} 语法支持动态内容的变量插值。这允许翻译包含运行时值，如计数、名称和模型标识符。

常见变量类型

变量模式	用途	示例键
`{{COUNT}}`	数字计数	`"{{COUNT}} Available Tools"`
`{{user}}`	用户标识符	`"{{user}}'s Chats"`
`{{model}}`	AI 模型名称	`"{{model}} download has been canceled"`
`{{REACTION}}`	表情/反应	`"{{NAMES}} reacted with {{REACTION}}"`
`{{LOCALIZED_DATE}}`	日期字符串	`"{{LOCALIZED_DATE}} at {{LOCALIZED_TIME}}"`

来源：src/lib/i18n/locales/zh-CN/translation.json:11-32，src/lib/i18n/locales/fr-FR/translation.json:11-33

插值逻辑

插值过程在运行时发生，当在 Svelte 组件中调用 $t() 函数时。引擎会用函数参数中提供的值替换占位符。

graph LR
    subgraph "InputSpace"
        ["KEY_INPUT"]["键: '{{COUNT}} files'"]
        ["DATA_INPUT"]["数据: { COUNT: 5 }"]
    end

    subgraph "ProcessingSpace"
        ["LOOKUP_LOCALE"]["查找 zh-CN 值"]
        ["REPLACE_VARS"]["正则替换 {{COUNT}} -> 5"]
    end

    subgraph "OutputSpace"
        ["FINAL_RESULT"]["'5 个文件'"]
    end

    ["KEY_INPUT"] --> ["LOOKUP_LOCALE"]
    ["DATA_INPUT"] --> ["REPLACE_VARS"]
    ["LOOKUP_LOCALE"] --> ["REPLACE_VARS"]
    ["REPLACE_VARS"] --> ["FINAL_RESULT"]

图：插值处理

来源：src/lib/i18n/locales/zh-CN/translation.json:15

支持的语言环境

系统支持多种语言，包括特定的区域变体（例如 en-US 与 en-GB）以及实验性语言环境，如 dg-DG（Doge）。

代码	语言	源文件
`en-US`	英语（美国）	`src/lib/i18n/locales/en-US/translation.json`
`zh-CN`	中文（简体）	`src/lib/i18n/locales/zh-CN/translation.json`
`de-DE`	德语	`src/lib/i18n/locales/de-DE/translation.json`
`es-ES`	西班牙语	`src/lib/i18n/locales/es-ES/translation.json`
`fr-FR`	法语	`src/lib/i18n/locales/fr-FR/translation.json`
`ru-RU`	俄语	`src/lib/i18n/locales/ru-RU/translation.json`
`ko-KR`	韩语	`src/lib/i18n/locales/ko-KR/translation.json`
`uk-UA`	乌克兰语	`src/lib/i18n/locales/uk-UA/translation.json`
`fa-IR`	波斯语	`src/lib/i18n/locales/fa-IR/translation.json`

来源：src/lib/i18n/locales/languages.json:1-246

实现细节

回退机制

当目标语言环境中某个翻译键缺失或值为空字符串时（如 en-US 中所示），系统默认回退到键本身（即英文源字符串）。

直接查找：尝试在 current_locale 中查找 key。
空值检查：如果值为 ""（例如 src/lib/i18n/locales/en-US/translation.json:2），则进入回退流程。
键回退：返回 key 字符串作为最终输出。

来源：src/lib/i18n/locales/en-US/translation.json:1-100，src/lib/i18n/locales/es-ES/translation.json:20-22

语言环境加载与切换

应用程序在布局挂载阶段初始化 i18n 系统。用户偏好的语言通常存储在应用程序设置中并持久化。

sequenceDiagram
    participant User
    participant Settings as "SettingsModal.svelte"
    participant Store as "i18n Store"
    participant UI as "Svelte 组件"

    User->>Settings: 选择 "Deutsch"
    Settings->>Store: setLocale("de-DE")
    Store->>Store: 加载 de-DE/translation.json
    Store-->>UI: 触发重新渲染
    UI->>UI: 使用 $t() 更新文本

图：语言环境切换序列

来源：src/lib/i18n/locales/languages.json:91-93，src/lib/i18n/locales/zh-CN/translation.json:104-109

功能覆盖范围

翻译系统覆盖了 Open WebUI 平台的几个不同功能领域：

身份验证：登录、账户激活和 LDAP 设置。src/lib/i18n/locales/zh-CN/translation.json:56-58
聊天管理：归档、删除和分享对话。src/lib/i18n/locales/zh-CN/translation.json:118-131
模型配置：高级参数（top_p、temperature）和模型发现。src/lib/i18n/locales/zh-CN/translation.json:150-152
RAG 系统：知识库索引、文档上传和嵌入设置。src/lib/i18n/locales/zh-CN/translation.json:115-116
管理工具：用户管理、组权限和系统分析。src/lib/i18n/locales/zh-CN/translation.json:105-110

来源：src/lib/i18n/locales/zh-CN/translation.json:1-200