agentic_huge_data_base / wiki
页面 Open WebUI · 14.3 翻译变量插值·DeepWiki 中文全文译文
DeepWiki 中文译文 / Open WebUI / 14.3

14.3 · 翻译变量插值（Variable Interpolation in Translations）

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

项目Open WebUI 章节14.3 状态全文译文 模块工具、记忆与模型调用
项目要点页2.5 参考项目 项目章节目录Open WebUI DeepWiki 原始章节Variable Interpolation in Translations 上一章14.2 下一章15
源码线索
  • 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.3-variable-interpolation-in-translations
翻译时间：2026-06-09T16:11:36.691Z
翻译模型：deepseek-chat
原文字符数：11883
项目：Open WebUI (open-webui)

---

翻译中的变量插值

相关源文件

以下文件被用作生成此 Wiki 页面的上下文：

  • 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
  • src/lib/i18n/locales/ru-RU/translation.json
  • src/lib/i18n/locales/uk-UA/translation.json
  • src/lib/i18n/locales/zh-CN/translation.json
  • src/lib/i18n/locales/zh-TW/translation.json

本文档描述了 Open WebUI 国际化（i18n）框架中使用的变量插值系统。变量插值允许将动态值插入到翻译字符串中，从而生成包含用户特定数据、数量、名称、日期和其他运行时值的本地化消息。

有关整体 i18n 系统架构和区域管理的信息，请参阅 14.1 翻译系统架构。有关支持语言的详细信息，请参阅 14.2 支持的区域设置。

目的与范围

翻译中的变量插值实现了以下功能：

  • 将运行时值（用户名、数量、模型名称）动态插入到本地化字符串中。
  • 在所有支持的区域设置（30+ 种语言）中保持一致的占位符语法。
  • 类型安全的变量替换，保留翻译上下文。
  • 支持复杂的格式化场景，包括复数标记和嵌套值。

该系统使用双花括号语法（{{variable}}）实现，在运行时由前端逻辑提供的实际值替换。

变量插值语法

基本语法

翻译字符串中的变量使用双花括号分隔符：

"{{VARIABLE_NAME}}"

变量名区分大小写。虽然许多系统变量使用 UPPER_SNAKE_CASE，但实体特定的变量通常使用 camelCase 或 lowercase。

翻译文件中的示例：

  • "{{COUNT}} Available Tools" — src/lib/i18n/locales/zh-CN/translation.json:12
  • "{{user}}'s Chats" — src/lib/i18n/locales/zh-CN/translation.json:32
  • "{{model}} download has been canceled" — src/lib/i18n/locales/zh-CN/translation.json:29

来源：src/lib/i18n/locales/zh-CN/translation.json:12-32，src/lib/i18n/locales/en-US/translation.json:11-33

单个字符串中的多个变量

单个翻译字符串可以包含多个变量占位符，以构建复杂的动态消息。

示例：

  • "{{LOCALIZED_DATE}} at {{LOCALIZED_TIME}}" — src/lib/i18n/locales/zh-CN/translation.json:28
  • "{{NAMES}} reacted with {{REACTION}}" — src/lib/i18n/locales/zh-CN/translation.json:31

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

所有格和上下文变量

变量可以嵌入到语法结构中，以在不同语言中保持自然的语流。

示例：

  • "{{user}}'s Chats"（英语所有格）— src/lib/i18n/locales/en-US/translation.json:33
  • "{{user}} 的对话记录"（中文所有格）— src/lib/i18n/locales/zh-CN/translation.json:32
  • "Chats von {{user}}"（德语介词结构）— src/lib/i18n/locales/de-DE/translation.json:33

来源：src/lib/i18n/locales/en-US/translation.json:33，src/lib/i18n/locales/zh-CN/translation.json:32，src/lib/i18n/locales/de-DE/translation.json:33

变量插值流程

下图展示了从 Svelte 组件经过 i18n 插值引擎到最终渲染 UI 的数据流。

标题："翻译数据流与插值管道"

graph TB
    subgraph "前端层"
        Component["Svelte 组件<br/>(例如 Chat.svelte)"]
        I18nStore["i18next 存储<br/>(src/lib/i18n/index.ts)"]
    end

    subgraph "I18N 引擎"
        Lookup["键查找<br/>(区域管理器)"]
        Interpolator["变量插值器<br/>(i18next 插值)"]
    end

    subgraph "数据源"
        TransJSON["translation.json<br/>(src/lib/i18n/locales/*/translation.json)"]
        RuntimeState["运行时状态<br/>(变量对象)"]
    end

    Component -->|"调用 $i18n.t(key, vars)"| I18nStore
    I18nStore --> Lookup
    Lookup -->|"获取模板"| TransJSON
    TransJSON -->|"返回 '{{COUNT}} files'"| Lookup
    Lookup -->|"传递模板 + 变量"| Interpolator
    RuntimeState -->|"提供 {COUNT: 5}"| Interpolator
    Interpolator -->|"替换值"| Result["'5 files'"]
    Result --> I18nStore
    I18nStore -->|"渲染本地化文本"| Component

来源：src/lib/i18n/index.ts:1-50，src/lib/i18n/locales/zh-CN/translation.json:1-40，src/lib/i18n/locales/en-US/translation.json:1-40

常见变量模式

计数与数量变量（{{COUNT}}）

{{COUNT}} 变量是最常见的占位符，用于复数和数值显示。请注意，某些区域设置（如加泰罗尼亚语、西班牙语或俄语）可能会使用 selected_one、selected_many 或 selected_other 键来处理复杂的复数形式。

翻译键描述
"{{COUNT}} Available Tools"工作区中的工具数量。
"{{COUNT}} characters"输入文本的长度。
"{{COUNT}} extracted lines"RAG 文档处理的结果。
"{{COUNT}} hidden lines"消息历史中折叠的内容。
"{{COUNT}} Replies"线程消息计数。

来源：src/lib/i18n/locales/zh-CN/translation.json:12-21，src/lib/i18n/locales/ca-ES/translation.json:20-22，src/lib/i18n/locales/es-ES/translation.json:20-22，src/lib/i18n/locales/ru-RU/translation.json:20-23

身份与系统变量
变量使用上下文示例
{{user}}用户特定归属"{{user}}'s Chats"
{{modelName}}特定 AI 模型标签"{{modelName}} profile image"
{{webUIName}}品牌与系统要求"{{webUIName}} Backend Required"
{{LATEST_VERSION}}更新通知"A new version (v{{LATEST_VERSION}}) is now available."

来源：src/lib/i18n/locales/zh-CN/translation.json:30-39,44

相对时间变量

Open WebUI 使用专门的插值来处理时间前字符串，以支持本地化的持续时间。

示例：

  • "{{COUNT}}d_time_ago"（天）— src/lib/i18n/locales/zh-CN/translation.json:23
  • "{{COUNT}}h_time_ago"（小时）— src/lib/i18n/locales/zh-CN/translation.json:24
  • "{{COUNT}}m_time_ago"（分钟）— src/lib/i18n/locales/zh-CN/translation.json:25

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

翻译文件组织

翻译文件按照 languages.json 中定义的 IETF 语言标签进行组织。每个文件是一个扁平的 JSON 对象，其中键是英文源字符串（或唯一 ID），值是包含变量的本地化模板。

标题："区域文件结构与变量映射"

graph LR
    subgraph "区域文件系统"
        DirEN["src/lib/i18n/locales/en-US/"]
        DirZH["src/lib/i18n/locales/zh-CN/"]
        DirDE["src/lib/i18n/locales/de-DE/"]
        DirES["src/lib/i18n/locales/es-ES/"]
        DirFR["src/lib/i18n/locales/fr-FR/"]
        DirUK["src/lib/i18n/locales/uk-UA/"]
        DirFA["src/lib/i18n/locales/fa-IR/"]
    end

    DirEN --> FileEN["translation.json"]
    DirZH --> FileZH["translation.json"]
    DirDE --> FileDE["translation.json"]
    DirES --> FileES["translation.json"]
    DirFR --> FileFR["translation.json"]
    DirUK --> FileUK["translation.json"]
    DirFA --> FileFA["translation.json"]

    subgraph "JSON 映射逻辑"
        Template["{<br/>&nbsp;&nbsp;'{{COUNT}} files': '{{COUNT}} 个文件',<br/>&nbsp;&nbsp;'by {{user}}': '由 {{user}} 发布'<br/>}"]
    end

    FileZH -.-> Template

来源：src/lib/i18n/locales/zh-CN/translation.json:1，src/lib/i18n/locales/de-DE/translation.json:1，src/lib/i18n/locales/es-ES/translation.json:1，src/lib/i18n/locales/fr-FR/translation.json:1，src/lib/i18n/locales/uk-UA/translation.json:1，src/lib/i18n/locales/fa-IR/translation.json:1，src/lib/i18n/locales/languages.json:1-246

实现细节

变量命名约定

代码库对插值变量采用三种主要的命名模式：

  1. 系统常量（UPPER_CASE）：用于全局系统值，如 {{LATEST_VERSION}} 或 {{COMMAND}}。src/lib/i18n/locales/zh-CN/translation.json:44,63
  2. 数量（UPPER_CASE）：特别是 {{COUNT}} 用于所有与复数相关的逻辑。src/lib/i18n/locales/zh-CN/translation.json:12-27
  3. 实体属性（camelCase / lowercase）：用于动态数据，如 {{modelName}}、{{user}} 或 {{model}}。src/lib/i18n/locales/zh-CN/translation.json:29-32
多区域变量一致性

为确保系统正常运行，双花括号内的变量名必须在所有翻译文件中保持一致，即使周围文本发生显著变化。

区域设置翻译字符串
en-US"Activate this command by typing \"/{{COMMAND}}\" to chat input." src/lib/i18n/locales/en-US/translation.json:64
zh-CN"在对话框中输入 \"/{{COMMAND}}\" 激活此命令" src/lib/i18n/locales/zh-CN/translation.json:63
de-DE"Aktivieren Sie diesen Befehl, indem Sie \"/{{COMMAND}}\" in die Chat-Eingabe tippen." src/lib/i18n/locales/de-DE/translation.json:64
uk-UA"Активуйте цю команду, ввівви \"/{{COMMAND}}\" у введення чату." src/lib/i18n/locales/uk-UA/translation.json:66

来源：src/lib/i18n/locales/en-US/translation.json:64，src/lib/i18n/locales/zh-CN/translation.json:63，src/lib/i18n/locales/de-DE/translation.json:64，src/lib/i18n/locales/uk-UA/translation.json:66

开发者最佳实践

  1. 保留变量语法：添加新翻译时，确保严格遵循 {{variable}} 语法。不要使用单花括号或其他分隔符。
  2. 上下文键：如果像 {{COUNT}} 这样的变量对不同项目需要不同的措辞（例如，"5 files" 与 "5 users"），请在 JSON 中使用唯一的键，以便翻译人员调整词序或性别特定的形容词。
  3. 默认值：在 en-US 区域设置中，许多值保留为空字符串 ""。这表示键本身被用作默认显示字符串。src/lib/i18n/locales/en-US/translation.json:1-154
  4. 转义：如果变量需要在翻译中用引号包裹，请使用转义字符：\"{{NAME}}\"。例如，在中文中，"Are you sure you want to delete \"{{NAME}}\"?" 的翻译是 "您确定要删除 “{{NAME}}” 吗？" src/lib/i18n/locales/zh-CN/translation.json:191。

来源：src/lib/i18n/locales/zh-CN/translation.json:1-100，src/lib/i18n/locales/en-US/translation.json:1-100，src/lib/i18n/locales/zh-CN/translation.json:191