企业官网建设流程全解析

Better DeepSeek是一款为 DeepSeek Chat 注入超能力的浏览器扩展，内置了一套轻量级 i18n 本地化系统：所有界面文案存放在src/locales/下的 JSON 文件中，组件通过一个t()函数按键路径取词，缺失翻译自动回退英文。如果你想为它贡献新语言（德语、日语、韩语……），只需要翻译一个 JSON 文件——不需要写任何框架代码。本文将带你从零走通"新增语言"的完整流程。

一、i18n 系统是如何工作的：30 秒读懂核心设计

Better DeepSeek 没有引入任何重型国际化库，整个系统只由两部分构成：

t()的取词逻辑（见 i18n.svelte.js 中的t(path, vars)）：

1. 点路径解析：t('settings.save')会逐层走进 JSON 的messages.settings.save；
2. 英文回退：当前语言缺这个 key 时，自动去第一个语言（en）取值；
3. 保底兜底：哪里都没有，就显示 key 路径本身，保证界面永不"空白"；
4. 模板变量插值：值里的{{version}}、{{count}}、{{date}}等占位符会在运行时替换成动态内容。

语言文件在构建时被自动收集（import.meta.glob("../locales/*.json")，见 i18n.svelte.js）——这意味着你只需在src/locales/下放好新文件，它就会自动出现在设置面板的语言下拉框和自动检测逻辑中，无需改动任何注册代码。

二、新增语言完整流程：6 步贡献指南

1. 环境准备：克隆仓库并安装依赖

git clone https://gitcode.com/gh_mirrors/be/better-deepseek cd better-deepseek npm install

2. 创建语言文件

把 src/locales/en.json 复制为src/locales/{code}.json，其中{code}使用 ISO 639-1 语言代码（如de、fr、ja）。注意带地区变体的写法，例如简体中文是zh-cn（参见现成的 src/locales/zh-cn.json）。

文件顶层结构保持两段式：

{ "updatedAt": "2026-05-20T00:00:00Z", "messages": { "common": { "save": "Speichern", "cancel": "Abbrechen" } } }

其中updatedAt请填当天日期（ISO 8601 格式），它是远程更新机制判断新旧版本的关键字段，别忘改。

3. 翻译规则：只翻值，不翻键

这是整个贡献流程中最重要的一条：

• ⚠️键名（keys）永远不翻译，messages内的嵌套结构必须与en.json完全一致；
• 模板变量（如{{version}}）连同花括号原样保留，但可以在句子里调整位置以符合本语言语序——例如 en.json 中"version": "v{{version}}"；
• 部分值包含<strong>等行内 HTML（界面用{@html ...}渲染），必须原样保留；
• 复数不用复杂规则，而是拆成不同 key（如filesUploaded与filesUploadedShort），翻译时按各自 key 处理即可。

以简体中文文件为例，common区块的翻译对照如下（zh-cn.json）：

4. 在语言文件中注册语言名称

所有语言文件都有messages.language区块，里面存"每种语言的本族名"。你在每个语言文件里都要为新语言加一行，例如在en.json中（见 en.json）：

"language": { "en": "English", "tr": "Türkçe", "de": "Deutsch" }

而新语言文件de.json里则用德语写其他语言的名字（"en": "Englisch"）。这一步完成后，新语言才会显示在设置面板的下拉选择器中（渲染逻辑见 SettingsPanel.svelte，使用i18n.getNativeName(code)展示本族名）。

5. 构建并测试

npm run build

在浏览器中加载dist-chrome目录下的未打包扩展，打开设置面板的语言区域，切换到你的新语言。所有走了t()的界面字符串都应显示为你的翻译。

6. 运行自动校验，提交翻译

提交前务必运行内置的本地化校验脚本：

npm run check-locales

该脚本（scripts/check-locales.js）会递归对比所有语言文件与基准文件en.json，输出彩色报告：

• Missing Keys（红色）：en.json有而你文件里没有的键——必须补译；
• Extra Keys（青色）：你文件里有但en.json已删除的过时键——可以安全清理。

全部通过后，提交 PR（包含你的新语言文件 + 更新后的src/locales/en.json）。如果不熟悉 Git/PR，也可以把翻译好的 JSON 文件附在 Issue 中，并注明语言名称，维护者会代为处理。

三、翻译时最容易踩的 4 个坑

结合 LOCALIZATION.md 官方指南，整理成速查表：

另外注意：并非所有字符串都需要翻译——直接发给 AI 模型的内容（如自动指令）是刻意保持英文的，遇到这类 key 保留原样即可。

四、远程语言更新：翻译合并后，用户秒级生效

Better DeepSeek 最贴心的设计之一：翻译更新不需要用户升级扩展版本。机制如下：

1. 扩展启动时，以及用户在设置面板点击Check for Language Updates按钮时（SettingsPanel.svelte 中checkLanguageUpdates()会向后台发送BDS_UPDATE_LANGUAGES消息），后台会拉取仓库main分支上最新的语言文件；
2. 后台 src/background/index.js 中的handleLanguageUpdate()逐个对比远程与内置文件的updatedAt时间戳，远程更新才替换，并写入chrome.storage.local持久化，重启浏览器也不丢失；
3. 前端启动时通过i18n.loadUpdatedLocales()把更新热加载进内存（storage.js）；
4. 设置面板里的Reset to Factory Languages按钮可一键还原为内置翻译（调用 i18n.svelte.js 的resetLocales()）。

所以对译者来说：PR 一旦合并进main，用户点一下"检查语言更新"就能用上你的新翻译——这就是为什么updatedAt字段如此关键。

五、语言是怎么被选中的：同步模式与手动模式

了解用户端的行为，有助于你理解自己翻译的展示效果。设置面板中的Sync extension language with browser（settings.syncLocale）开关控制两种模式：

• 自动同步（默认）：忽略手动选择，每次页面加载按优先级自动检测——
  1. DeepSeek 的NEXT_LOCALEcookie（跟随 DeepSeek 网页端的语言设置）；
  2. 浏览器的navigator.language；
  3. 回退到第一个可用语言（English）。
• 手动模式：关闭同步后，下拉框中选中的语言会持久化到chrome.storage.local，之后每次加载都沿用。

自动检测逻辑运行在 i18n.svelte.js 的init()中，扩展启动时触发，其他标签页设置变更时也会同步。你的语言文件放进src/locales/后，自动检测与手动选择器都会自动包含它，无需额外适配。

六、贡献前自检清单 ✅

提交 PR 前，逐条确认：

• 文件名使用正确的 ISO 639-1 代码，位于 src/locales/
• updatedAt已更新为当天日期
• 结构、键名与 src/locales/en.json 完全一致
• 模板变量{{...}}与 HTML 标签全部保留
• 所有语言文件的messages.language都注册了新语言的本族名
• npm run check-locales通过，无 Missing Keys

💡 完整文档参考：LOCALIZATION.md。 语言文件位置：src/locales/（当前收录 en、zh-cn、tr、ru、fa 共 5 种语言，单文件约 1500 行）。 校验工具源码：scripts/check-locales.js i18n 核心实现：src/lib/i18n.svelte.js

翻译一个 JSON 文件，就能让全世界使用者在自己的语言里打开 Better DeepSeek。上手门槛极低，欢迎贡献你的第一种语言！