From 34a17689976cc9bad364dfdebeeb91fda611af6a Mon Sep 17 00:00:00 2001
From: yuyan <yuyan@ansss.de>
Date: Sat, 4 Jul 2026 10:06:29 +0800
Subject: [PATCH 1/6] =?UTF-8?q?feat(i18n):=20=E5=A2=9E=E5=8A=A0=E4=B8=AD?=
 =?UTF-8?q?=E8=8B=B1=E5=8F=8C=E8=AF=AD=E6=94=AF=E6=8C=81=EF=BC=8C=E5=8F=AF?=
 =?UTF-8?q?=E8=87=AA=E7=94=B1=E5=88=87=E6=8D=A2=E7=95=8C=E9=9D=A2=E8=AF=AD?=
 =?UTF-8?q?=E8=A8=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 新增 locales 模块，包含中英文翻译字典、类型定义和工具函数
- 添加 useI18n composable，组件通过 provide/inject 获取翻译函数
- 语言默认跟随浏览器设置，支持在 Settings 面板手动切换并持久化
- 所有功能文案和技术术语均已翻译，品牌名 ModBox 保持原样
- 功能按钮（操作类型、拦截类型、规则标题等）增加 tooltip 悬停说明
- Settings 面板新增「使用帮助」弹窗，提供功能概述和使用指引
- 构建通过，118 个已有测试全部通过
---
 package-lock.json                |   4 +-
 src/App.vue                      |  64 +++++++++-
 src/components/Dropdown.vue      |   9 +-
 src/components/DropdownMenu.vue  |   8 +-
 src/components/Editor.vue        |  13 +-
 src/components/Folder.vue        |  44 +++----
 src/components/FolderDragger.vue |  15 ++-
 src/components/FolderPanel.vue   |  23 ++--
 src/components/RuleDragger.vue   |  17 ++-
 src/components/Settings.vue      | 167 ++++++++++++++++++------
 src/components/Tab.vue           | 208 +++++++++++++++---------------
 src/components/TabDragger.vue    |  17 ++-
 src/composables/index.ts         |  37 +++++-
 src/locales/en.ts                | 210 ++++++++++++++++++++++++++++++
 src/locales/index.ts             |  71 +++++++++++
 src/locales/types.ts             | 178 ++++++++++++++++++++++++++
 src/locales/zh-CN.ts             | 211 +++++++++++++++++++++++++++++++
 src/style.scss                   |   9 ++
 18 files changed, 1087 insertions(+), 218 deletions(-)
 create mode 100644 src/locales/en.ts
 create mode 100644 src/locales/index.ts
 create mode 100644 src/locales/types.ts
 create mode 100644 src/locales/zh-CN.ts

diff --git a/package-lock.json b/package-lock.json
index ed913ac..3e1c98c 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "mod-box",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "mod-box",
-      "version": "0.2.2",
+      "version": "0.2.4",
       "dependencies": {
         "vue": "^3.4.33"
       },
diff --git a/src/App.vue b/src/App.vue
index d321a4a..c8f4d64 100644
--- a/src/App.vue
+++ b/src/App.vue
@@ -1,7 +1,7 @@
 <template>
   <div>
     <div v-if="error" class="error error--top">
-      There was an error setting the rules, did you use an invalid header name
+      {{ t("app.error") }}
     </div>
     <FolderPanel
       v-if="data.folders"
@@ -17,11 +17,15 @@
 </template>
 
 <script setup lang="ts">
-import { ref, onMounted, watch } from "vue";
+import { ref, provide, onMounted, watch } from "vue";
 import type { Ref } from "vue";
 
 import { DataType, FolderType } from "./interfaces";
 import { generateRules, isChrome } from "./utils";
+import { detectLocale, SUPPORTED_LOCALES } from "./locales";
+import type { Locale } from "./locales";
+import { LOCALE_KEY } from "./composables";
+import { getMessage } from "./locales";
 
 import FolderPanel from "./components/FolderPanel.vue";
 
@@ -60,6 +64,56 @@ const data: Ref<DataType> = ref({
 const totalActiveRules = ref(0);
 const error = ref(false);
 
+/**
+ * i18n 初始化
+ * 优先级：chrome.storage > localStorage > 浏览器语言自动检测
+ */
+const locale: Ref<Locale> = ref(detectLocale());
+provide(LOCALE_KEY, locale);
+
+// 在 provide 之后创建 i18n 实例供本组件使用
+const { t } = {
+  t(path: string, params?: Record<string, string | number>) {
+    return getMessage(locale.value, path, params);
+  },
+};
+
+/**
+ * 将当前语言偏好持久化到 chrome.storage 或 localStorage
+ * chrome 环境下失败静默处理，不影响用户体验
+ *
+ * @param newLocale - 当前 locale 值
+ */
+function saveLocale(newLocale: Locale) {
+  if (isChrome) {
+    chrome.storage.local.set({ locale: newLocale }).then(() => {
+      console.log("Chrome storage locale set");
+    });
+  } else {
+    window.localStorage.setItem("locale", newLocale);
+  }
+}
+
+/**
+ * 从 storage 恢复已保存的语言偏好
+ * 如果用户之前手动切换过则覆盖浏览器的自动检测结果
+ * 提升：chrome.storage.local 需要异步读取，非 chrome 环境从 localStorage 读取
+ */
+async function loadLocale() {
+  let storedLocale: string | null | undefined;
+
+  if (isChrome) {
+    const chromeData = await chrome.storage.local.get(["locale"]);
+    storedLocale = chromeData.locale;
+  } else {
+    storedLocale = window.localStorage.getItem("locale");
+  }
+
+  if (storedLocale && SUPPORTED_LOCALES.includes(storedLocale as Locale)) {
+    locale.value = storedLocale as Locale;
+  }
+}
+
 /**
  * Event handlers from FolderPanel
  */
@@ -165,10 +219,14 @@ watch(
   { deep: true }
 );
 
+// 监听 locale 变更并持久化
+watch(locale, (newLocale) => saveLocale(newLocale));
+
 /**
  * Lifecycle
  */
-onMounted(() => {
+onMounted(async () => {
+  await loadLocale();
   loadData();
 });
 </script>
diff --git a/src/components/Dropdown.vue b/src/components/Dropdown.vue
index a163402..d3eb90b 100644
--- a/src/components/Dropdown.vue
+++ b/src/components/Dropdown.vue
@@ -7,7 +7,9 @@
       </svg>
     </button>
     <div v-show="isOpen" class="dropdown__menu">
-      <button v-for="(option, index) in options" :key="index" @click="option.action ? option.action() : set(option.value)" class="dropdown__menu__item" :class="{'dropdown__menu__item--active' : model === option.value}">
+      <button v-for="(option, index) in options" :key="index" @click="option.action ? option.action() : set(option.value)"
+        class="dropdown__menu__item" :class="{'dropdown__menu__item--active' : model === option.value}"
+        :title="option.tooltip || ''">
         {{ option.label }}
       </button>
     </div>
@@ -26,7 +28,8 @@ const { isOpen, toggle, close } = useOutsideClick(root);
 interface Option {
   label: string,
   value: string | boolean,
-  action?: Function
+  action?: Function,
+  tooltip?: string,
 }
 
 const props = defineProps({
@@ -43,7 +46,7 @@ const defaultOption = computed(() => {
   if(typeof model.value !== "undefined" && model.value !== "") {
     return options.value.find(option => option.value === model.value)
   }
-  
+
   return options.value[0]
 })
 
diff --git a/src/components/DropdownMenu.vue b/src/components/DropdownMenu.vue
index 0ac6062..942af05 100644
--- a/src/components/DropdownMenu.vue
+++ b/src/components/DropdownMenu.vue
@@ -12,8 +12,8 @@
         </button>
         <div v-if="option.confirm" :class="{'dropdown__menu__item__confirm--active': confirmationOpen === index}" class="dropdown__menu__item__confirm">
           <div class="btn-group">
-            <button class="btn btn--danger" @click="handleClick(option, index, true)">Yes</button>
-            <button class="btn" @click="confirmationOpen = -1">No</button>
+            <button class="btn btn--danger" @click="handleClick(option, index, true)">{{ t("dropdownMenu.yes") }}</button>
+            <button class="btn" @click="confirmationOpen = -1">{{ t("dropdownMenu.no") }}</button>
           </div>
         </div>
       </div>
@@ -24,7 +24,9 @@
 <script setup lang="ts">
 import { ref, toRefs, watch } from "vue";
 import type { Ref, PropType } from "vue";
-import { useOutsideClick } from "../composables";
+import { useOutsideClick, useI18n } from "../composables";
+
+const { t } = useI18n();
 
 const root: Ref<HTMLElement | null> = ref(null);
 const { isOpen, toggle, close } = useOutsideClick(root);
diff --git a/src/components/Editor.vue b/src/components/Editor.vue
index 66143be..03d0d28 100644
--- a/src/components/Editor.vue
+++ b/src/components/Editor.vue
@@ -11,7 +11,7 @@
       :title="model || fallback || ''"
     >
       {{ model || fallback || "-" }}
-    
+
     </button>
 
     <button
@@ -41,7 +41,7 @@
       <Tooltip v-if="splitDomains.length > 1" :trigger="splitDomains.length - 1">
         <div v-for="(domain, idx) in splitDomains" :key="idx">{{ cleanDomain(domain) }}</div>
       </Tooltip>
-      
+
       <button v-if="!splitDomains.length" @click="edit" class="editor__trigger">
         -
         <svg
@@ -75,8 +75,8 @@
         ></textarea>
       </div>
       <div style="margin-top: 10px; display: flex; gap: 2px;">
-        <button class="btn button--primary" @click="save">Save</button>
-        <button class="btn button--secondary" @click="cancel" style="border-color: transparent; box-shadow: none">Cancel</button>
+        <button class="btn button--primary" @click="save">{{ t("editor.save") }}</button>
+        <button class="btn button--secondary" @click="cancel" style="border-color: transparent; box-shadow: none">{{ t("editor.cancel") }}</button>
       </div>
     </div>
   </div>
@@ -86,9 +86,12 @@
 import { ref, nextTick, toRefs, computed } from "vue";
 import type { Ref } from "vue";
 import { cleanDomain } from "../utils";
+import { useI18n } from "../composables";
 
 import Tooltip from "./Tooltip.vue";
 
+const { t } = useI18n();
+
 const model = defineModel<string>();
 const props = defineProps(["placeholder", "locked", "fallback", "domains", "label", "aligned", "icon"]);
 
@@ -124,8 +127,6 @@ const splitDomains = computed(() => {
     return [];
   }
 
-  // 
-
   if(model.value === "" && typeof fallback?.value === "string") {
     if(fallback?.value === "") {
       return [];
diff --git a/src/components/Folder.vue b/src/components/Folder.vue
index cdab543..4f59cdd 100644
--- a/src/components/Folder.vue
+++ b/src/components/Folder.vue
@@ -1,9 +1,13 @@
 <template>
   <div class="folder" :class="{ 'folder--active': folder.active }">
     <div class="folder__header mb10">
-      <h3>Folder ({{ folder.name }})</h3>
-      <button @click="showSettings = !showSettings" class="btn-icon" :class="{ 'btn-icon--active': showSettings }">
-        
+      <h3>{{ t("folder.title", { name: folder.name }) }}</h3>
+      <button
+        @click="showSettings = !showSettings"
+        class="btn-icon"
+        :class="{ 'btn-icon--active': showSettings }"
+        :title="t('folder.settings')"
+      >
         <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor"
           class="bi bi-gear-wide-connected" viewBox="0 0 16 16">
           <path
@@ -24,29 +28,29 @@
       </div>
 
       <div v-if="showDeleteConfirmation" class="panel__modal">
-        <h3 class="mb10">Confirm folder deletion</h3>
+        <h3 class="mb10">{{ t("folder.confirmDeletion") }}</h3>
         <div class="panel__modal__actions">
-          <button class="btn btn--danger" @click="deleteFolder">Delete</button>
-          <button class="btn" @click="showDeleteConfirmation = false">Cancel</button>
+          <button class="btn btn--danger" @click="deleteFolder">{{ t("folder.delete") }}</button>
+          <button class="btn" @click="showDeleteConfirmation = false">{{ t("folder.cancel") }}</button>
         </div>
       </div>
 
-      <h3 class="mb10">Folder settings</h3>
+      <h3 class="mb10">{{ t("folder.settings") }}</h3>
       <div class="mb10">
         <div class="field">
-          <label class="field__label" for="">Folder name</label>
-          <input class="field__input" type="text" v-model="folder.name" placeholder="Folder name" ref="folderName" />
+          <label class="field__label" for="">{{ t("folder.name") }}</label>
+          <input class="field__input" type="text" v-model="folder.name" :placeholder="t('folder.name')" ref="folderName" />
         </div>
       </div>
       <div class="panel__actions btn-group">
         <button @click="showDeleteConfirmation = true" class="btn">
-          Delete folder
+          {{ t("folder.deleteFolder") }}
         </button>
         <button @click="cloneFolder" class="btn">
-          Clone folder
+          {{ t("folder.cloneFolder") }}
         </button>
         <button @click="toggleActive" class="btn">
-          {{ folder.active ? "Disable folder" : "Enable folder"}}
+          {{ folder.active ? t("folder.disableFolder") : t("folder.enableFolder") }}
         </button>
       </div>
     </div>
@@ -55,17 +59,6 @@
     <div class="tabs mb15">
       <TabDragger :tabs="folder.tabs" :active-tab="activeTab" @moveTab="moveTab" @toggleTab="toggleTab"
         @setTab="setTab" />
-      <!-- <div class="tabs__tab" v-for="(tab, index) in folder.tabs" :class="{ 'tabs__tab--active': index === activeTab }">
-        <button class="tabs__tab__label" @click="activeTab = index">
-          {{ tab.name }}
-        </button>
-
-        <div class="toggle" @click="tab.active = !tab.active" :class="{ 'toggle--active': tab.active }">
-          <div class="toggle__text">
-            {{ tab.active ? "On" : "Off" }}
-          </div>
-        </div>
-      </div> -->
       <div class="tabs__tab">
         <button class="btn-icon" @click="addTab">
           <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-plus-lg"
@@ -92,6 +85,9 @@ import { isChrome } from "../utils"
 import Tab from "./Tab.vue";
 import TabDragger from "./TabDragger.vue";
 import { TabType } from "../interfaces";
+import { useI18n } from "../composables";
+
+const { t } = useI18n();
 
 const props = defineProps({
   folder: {
@@ -187,7 +183,7 @@ async function restoreTab() {
  */
 
 onMounted(() => {
-  // opens the folder settings automaticallly
+  // opens the folder settings automatically
   if (folder.value.name === "New folder" || folder.value.name === "Cloned folder") {
     showSettings.value = true;
 
diff --git a/src/components/FolderDragger.vue b/src/components/FolderDragger.vue
index 2ed8d1c..fa21bf2 100644
--- a/src/components/FolderDragger.vue
+++ b/src/components/FolderDragger.vue
@@ -1,6 +1,6 @@
 <template>
   <div v-for="(folder, index) in folders" :key="`folder-drag-${index}`" class="folders__list__item"
-    :class="{ 
+    :class="{
       'folders__list__item--active': index === activeFolder && !showSettings,
       'folders__list__item--bottom': index === target && target > tmp && target !== tmp,
       'folders__list__item--top': index === target && target < tmp,
@@ -15,10 +15,10 @@
     @dragend="dragging = false; tmp = -1; target = -1"
     @dragenter="target = index"
   >
-    <button :title="'select ' + folder.name" @click="setFolder(index)" class="folders__list__item__label">{{
+    <button :title="t('folderDragger.selectFolder', { name: folder.name })" @click="setFolder(index)" class="folders__list__item__label">{{
       name(folder) }}</button>
 
-    <div v-if="folders.length > 1 && !compact" class="folders__list__item__handle" @mousedown="tmp = index" @mouseup="tmp = -1" title="drag to move">
+    <div v-if="folders.length > 1 && !compact" class="folders__list__item__handle" @mousedown="tmp = index" @mouseup="tmp = -1" :title="t('folderDragger.dragToMove')">
       <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-grip-vertical"
         viewBox="0 0 16 16">
         <path
@@ -27,9 +27,9 @@
     </div>
 
     <button v-if="!compact" class="toggle" @click="toggle(folder)" :class="{ 'toggle--active': folder.active }"
-      :title="folder.active ? 'Disable folder rules' : 'Enable folder rules'">
+      :title="folder.active ? t('folderDragger.disableRules') : t('folderDragger.enableRules')">
       <div class="toggle__text">
-        {{ folder.active ? "On" : "Off" }}
+        {{ folder.active ? t("folderPanel.on") : t("folderPanel.off") }}
       </div>
     </button>
   </div>
@@ -38,6 +38,9 @@
 <script setup lang="ts">
 import { ref, toRefs, type PropType } from "vue";
 import { FolderType } from "../interfaces";
+import { useI18n } from "../composables";
+
+const { t } = useI18n();
 
 const props = defineProps({
   folders: {
@@ -95,7 +98,7 @@ function name(folder:FolderType) {
   if(compact.value) {
     const words = folder.name.split(" ");
     let letters = "";
-    
+
     words.forEach(word => {
       letters += word.substring(0,1)
     })
diff --git a/src/components/FolderPanel.vue b/src/components/FolderPanel.vue
index c2a3a9e..53db4e0 100644
--- a/src/components/FolderPanel.vue
+++ b/src/components/FolderPanel.vue
@@ -10,8 +10,8 @@
           <img src="/images/48_48.png" alt="Modbox" />
           <span v-if="!compact">ModBox</span>
         </h1>
-        <h3 v-if="!compact" class="mb10">Folders</h3>
-        <div v-if="!data.folders.length">No folders</div>
+        <h3 v-if="!compact" class="mb10">{{ t("folderPanel.folders") }}</h3>
+        <div v-if="!data.folders.length">{{ t("folderPanel.noFolders") }}</div>
 
         <FolderDragger
           :folders="data.folders"
@@ -26,7 +26,7 @@
         <button
           class="mt10 mb20"
           @click="addFolder"
-          title="Add folder"
+          :title="compact ? t('folderPanel.addFolder') : undefined"
           :class="{
             btn: !compact,
             'btn-icon btn-icon--with--border': compact,
@@ -46,28 +46,30 @@
               />
             </svg>
           </template>
-          <template v-else>Add</template>
+          <template v-else>{{ t("folderPanel.add") }}</template>
         </button>
 
         <hr />
 
         <div class="folders__list__settings">
-          <h3 v-if="!compact" class="mb10">Global</h3>
+          <h3 v-if="!compact" class="mb10">{{ t("folderPanel.global") }}</h3>
           <div v-if="!compact" class="folders__list__item">
             <button
               class="folders__list__item__label"
               @click="$emit('toggleGlobalActive')"
+              :title="t('folderPanel.rulesEnabledTooltip')"
             >
-              Rules enabled
+              {{ t("folderPanel.rulesEnabled") }}
               <div class="badge">{{ totalActiveRules }}</div>
             </button>
             <div
               class="toggle toggle--warning"
               @click="$emit('toggleGlobalActive')"
               :class="{ 'toggle--active': data.active }"
+              :title="t('folderPanel.rulesEnabledTooltip')"
             >
               <div class="toggle__text">
-                {{ data.active ? "On" : "Off" }}
+                {{ data.active ? t("folderPanel.on") : t("folderPanel.off") }}
               </div>
             </div>
           </div>
@@ -82,9 +84,9 @@
             <button
               class="folders__list__item__label"
               @click="showSettings = true"
-              title="Global settings"
+              :title="t('folderPanel.settings')"
             >
-              <template v-if="!compact">Settings</template>
+              <template v-if="!compact">{{ t("folderPanel.settings") }}</template>
               <template v-else>
                 <svg
                   xmlns="http://www.w3.org/2000/svg"
@@ -136,11 +138,14 @@ import * as _ from "lodash";
 
 import { DataType, FolderType } from "../interfaces";
 import { isChrome } from "../utils";
+import { useI18n } from "../composables";
 
 import Folder from "./Folder.vue";
 import FolderDragger from "./FolderDragger.vue";
 import Settings from "./Settings.vue";
 
+const { t } = useI18n();
+
 const props = defineProps({
   data: {
     type: Object as PropType<DataType>,
diff --git a/src/components/RuleDragger.vue b/src/components/RuleDragger.vue
index 7c24caa..915e00c 100644
--- a/src/components/RuleDragger.vue
+++ b/src/components/RuleDragger.vue
@@ -12,9 +12,9 @@
     @dragend="dragging = false; setTmp(-1); setTarget(-1)"
     @dragenter="setTarget(index)"
     >
-    
+
     <td class="table__handle">
-      <button class="handle" @mousedown="setTmp(index)" @mouseup="setTmp(-1)" :title="total > 1 ? 'drag to move' : ''" :disabled="total < 2">
+      <button class="handle" @mousedown="setTmp(index)" @mouseup="setTmp(-1)" :title="total > 1 ? t('ruleDragger.dragToMove') : ''" :disabled="total < 2">
         <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-grip-vertical"
           viewBox="0 0 16 16">
           <path
@@ -29,12 +29,15 @@
 
 <script setup lang="ts">
 import { ref, toRefs } from "vue";
+import { useI18n } from "../composables";
+
+const { t } = useI18n();
 
 const props = defineProps({
   index: {
     type: Number,
     required: true
-  }, 
+  },
   tmp: {
     type: Number,
     required: true
@@ -42,11 +45,11 @@ const props = defineProps({
   target: {
     type: Number,
     required: true
-  }, 
+  },
   total: {
     type: Number,
     required: true
-  }, 
+  },
 });
 
 const propRefs = toRefs(props);
@@ -54,16 +57,13 @@ const index = propRefs.index;
 const tmp = propRefs.tmp;
 const target = propRefs.target;
 const total = propRefs.total;
-// const activeFolder = propRefs.activeFolder;
 
 const emit = defineEmits(["onMoveRule", "onSetTmp", "onSetTarget"]);
 
-// const tmp = ref(-1);
 const active = ref(0);
 const dragging = ref(false);
 
 function onDragStart(newTmp: number) {
-  // tmp.value = index;
   setTmp(newTmp);
 }
 
@@ -73,7 +73,6 @@ function onDragDrop(index: number) {
 
 function moveRule(from: number, to: number) {
   emit("onMoveRule", from, to);
-  // console.log(`moveRule from: ${from}, to: ${to}`);
   setTmp(-1)
 }
 
diff --git a/src/components/Settings.vue b/src/components/Settings.vue
index 947572b..acf3c0a 100644
--- a/src/components/Settings.vue
+++ b/src/components/Settings.vue
@@ -1,19 +1,39 @@
 <template>
   <div>
     <div class="folder__header mb10">
-      <h3>Settings</h3>
+      <h3>{{ t("settings.title") }}</h3>
     </div>
 
     <!-- Compact Mode -->
     <div class="panel panel--large mb20">
-      <h3 class="mb10">Compact mode <div class="tag">New</div></h3>
+      <h3 class="mb10" :title="t('settings.compactModeTooltip')">
+        {{ t("settings.compactMode") }} <div class="tag">{{ t("settings.new") }}</div>
+      </h3>
       <p class="mb20">
-        If you need a bit more space to work with your rules, compact mode reduces the left hand column width.
+        {{ t("settings.compactDesc") }}
       </p>
 
       <div class="panel__actions">
         <button @click="$emit('toggleCompact')" class="btn">
-          {{ compact ? "Disable compact mode" : "Enable compact mode" }}
+          {{ compact ? t("settings.disableCompact") : t("settings.enableCompact") }}
+        </button>
+      </div>
+    </div>
+
+    <!-- Language -->
+    <div class="panel panel--large mb20">
+      <h3 class="mb10">{{ t("settings.language") }} <div class="tag">{{ t("settings.new") }}</div></h3>
+      <p class="mb20">{{ t("settings.languageDesc") }}</p>
+
+      <div class="panel__actions btn-group">
+        <button
+          v-for="loc in availableLocales"
+          :key="loc.code"
+          class="btn"
+          :class="{ 'btn--primary': locale === loc.code }"
+          @click="changeLocale(loc.code)"
+        >
+          {{ loc.label }}
         </button>
       </div>
     </div>
@@ -21,13 +41,11 @@
     <!-- Export -->
     <div class="panel panel--large mb20">
       <h3 class="mb10">
-        Export
-        <div class="tag">New</div>
+        {{ t("settings.export") }}
+        <div class="tag">{{ t("settings.new") }}</div>
       </h3>
       <p class="mb20">
-        You can export your rules into .json packages to backup, or send
-        to friends/colleagues. Check the folders you want and click
-        export.
+        {{ t("settings.exportDesc") }}
       </p>
 
       <div class="mb20">
@@ -68,7 +86,7 @@
           @click="download"
           :disabled="!selectedExport.length"
         >
-          Export
+          {{ t("settings.exportBtn") }}
         </button>
       </div>
     </div>
@@ -76,12 +94,11 @@
     <!-- Import -->
     <div class="panel panel--large mb20">
       <h3 class="mb10">
-        Import
-        <div class="tag">New</div>
+        {{ t("settings.import") }}
+        <div class="tag">{{ t("settings.new") }}</div>
       </h3>
       <p class="mb20">
-        You can select and import modbox backup files and append them to
-        your current set of folders, tabs and rules.
+        {{ t("settings.importDesc") }}
       </p>
 
       <div class="mb20">
@@ -132,49 +149,92 @@
           @click="clearImported"
           :disabled="!importData.length"
         >
-          Clear
+          {{ t("settings.clear") }}
         </button>
         <button
           class="btn"
           @click="appendImported"
           :disabled="!selectedImport.length"
         >
-          Append
+          {{ t("settings.append") }}
         </button>
       </div>
     </div>
 
+    <!-- Help -->
+    <div class="panel panel--large mb20">
+      <h3 class="mb10">{{ t("settings.help") }} <div class="tag">{{ t("settings.new") }}</div></h3>
+      <p class="mb20">{{ t("settings.helpDesc") }}</p>
+
+      <div class="panel__actions">
+        <button @click="showHelp = true" class="btn">
+          {{ t("settings.openHelp") }}
+        </button>
+      </div>
+
+      <!-- Help Modal -->
+      <div v-if="showHelp" class="panel__modal">
+        <div class="help-content">
+          <h3 class="mb15">{{ t("settings.helpContent.title") }}</h3>
+
+          <p class="mb15">{{ t("settings.helpContent.overview") }}</p>
+
+          <h4 class="mb10">{{ t("settings.helpContent.folders.title") }}</h4>
+          <p class="mb15">{{ t("settings.helpContent.folders.body") }}</p>
+
+          <h4 class="mb10">{{ t("settings.helpContent.rules.title") }}</h4>
+          <p class="mb15">{{ t("settings.helpContent.rules.body") }}</p>
+
+          <h4 class="mb10">{{ t("settings.helpContent.condition.title") }}</h4>
+          <p class="mb15">{{ t("settings.helpContent.condition.body") }}</p>
+
+          <h4 class="mb10">{{ t("settings.helpContent.toggle.title") }}</h4>
+          <p class="mb15">{{ t("settings.helpContent.toggle.body") }}</p>
+
+          <h4 class="mb10">{{ t("settings.helpContent.compact.title") }}</h4>
+          <p class="mb15">{{ t("settings.helpContent.compact.body") }}</p>
+
+          <h4 class="mb10">{{ t("settings.helpContent.exportImport.title") }}</h4>
+          <p class="mb15">{{ t("settings.helpContent.exportImport.body") }}</p>
+
+          <div class="panel__modal__actions">
+            <button class="btn" @click="showHelp = false">
+              {{ t("folder.cancel") }}
+            </button>
+          </div>
+        </div>
+      </div>
+    </div>
+
     <!-- Delete All -->
     <div class="panel panel--large mb20">
       <div v-if="showDeleteConfirmation" class="panel__modal">
-        <h3 class="mb10">Confirm rules deletion</h3>
+        <h3 class="mb10">{{ t("settings.confirmDeletion") }}</h3>
         <div class="panel__modal__actions">
-          <button class="btn btn--danger" @click="confirmReset">Delete</button>
+          <button class="btn btn--danger" @click="confirmReset">{{ t("folder.delete") }}</button>
           <button class="btn" @click="showDeleteConfirmation = false">
-            Cancel
+            {{ t("folder.cancel") }}
           </button>
         </div>
       </div>
 
-      <h3 class="mb10">Delete all rules</h3>
+      <h3 class="mb10">{{ t("settings.deleteAll") }}</h3>
       <p class="mb20">
-        If you want to totally reset all of your rules. This cannot be
-        undone so please use carefully.
+        {{ t("settings.deleteAllDesc") }}
       </p>
 
       <div class="panel__actions">
         <button @click="showDeleteConfirmation = true" class="btn">
-          Delete all
+          {{ t("settings.deleteAllBtn") }}
         </button>
       </div>
     </div>
 
     <!-- About -->
     <div class="panel panel--large">
-      <h3 class="mb10">About</h3>
+      <h3 class="mb10">{{ t("settings.about") }}</h3>
       <p class="mb20">
-        ModBox is a hobby project with the aim of providing developers and
-        hackers a tool for testing and debugging.
+        {{ t("settings.aboutDesc") }}
       </p>
 
       <div class="panel__actions">
@@ -183,14 +243,14 @@
           class="btn"
           target="_blank"
         >
-          My LinkedIn
+          {{ t("settings.linkedIn") }}
         </a>
         <a
           href="https://www.buymeacoffee.com/robphillips"
           class="btn"
           target="_blank"
         >
-          Tip Jar
+          {{ t("settings.tipJar") }}
         </a>
       </div>
     </div>
@@ -198,9 +258,24 @@
 </template>
 
 <script setup lang="ts">
-import { ref, type PropType } from "vue";
-import type { Ref } from "vue";
+import { ref, inject, computed, type PropType } from "vue";
 import { FolderType, isValidExportPayload } from "../interfaces";
+import { LOCALE_KEY, useI18n } from "../composables";
+import type { Locale } from "../locales";
+import { SUPPORTED_LOCALES, LOCALE_LABELS } from "../locales";
+import type { Ref } from "vue";
+
+const { t } = useI18n();
+
+const locale = inject<Ref<Locale>>(LOCALE_KEY);
+
+/** 可选的语言列表 */
+const availableLocales = computed(() =>
+  SUPPORTED_LOCALES.map((code) => ({
+    code,
+    label: LOCALE_LABELS[code],
+  }))
+);
 
 const props = defineProps({
   folders: {
@@ -229,6 +304,26 @@ const importData: Ref<FolderType[]> = ref([]);
 const exportError = ref("");
 const importError = ref("");
 const showDeleteConfirmation = ref(false);
+const showHelp = ref(false);
+
+/**
+ * 切换界面语言并持久化到 storage
+ * 因为 locale 是一个 provide 进来的 Ref，修改它在 App.vue 会被 watch 到并自动保存
+ * 此处额外保存一次以确保 chrome.storage 同步（跨 popup 实例可见）
+ *
+ * @param newLocale - 目标语言代码
+ */
+function changeLocale(newLocale: Locale) {
+  if (!locale) return;
+  locale.value = newLocale;
+
+  // 持久化到 storage
+  if (typeof chrome !== "undefined" && chrome?.storage) {
+    chrome.storage.local.set({ locale: newLocale });
+  } else {
+    window.localStorage.setItem("locale", newLocale);
+  }
+}
 
 /**
  * Export functionality
@@ -267,7 +362,7 @@ function download() {
     const json = JSON.stringify(payload);
 
     if (json.length > MAX_EXPORT_SIZE) {
-      exportError.value = "Export data is too large. Try selecting fewer folders.";
+      exportError.value = t("settings.exportTooLarge");
       return;
     }
 
@@ -304,7 +399,7 @@ function download() {
 
     selectedExport.value = [];
   } catch (e) {
-    exportError.value = "Failed to export rules. Please try again.";
+    exportError.value = t("settings.exportFailed");
 
     // Cleanup on error
     if (anchor?.parentNode) {
@@ -322,7 +417,7 @@ function download() {
 function onFileChange(e: Event) {
   const target = e.target as HTMLInputElement;
   const file = target.files?.[0];
-  
+
   if (!file) return;
 
   const fr = new FileReader();
@@ -331,18 +426,18 @@ function onFileChange(e: Event) {
     try {
       const result = event.target?.result;
       if (typeof result !== 'string') return;
-      
+
       const payload = JSON.parse(result);
 
       if (!isValidExportPayload(payload)) {
-        importError.value = "Invalid file format. Please select a valid ModBox backup file.";
+        importError.value = t("settings.invalidFile");
         return;
       }
 
       importData.value = payload.folders;
       importError.value = "";
     } catch {
-      importError.value = "Failed to parse file. Please ensure it's a valid JSON file.";
+      importError.value = t("settings.parseFailed");
     }
   };
   fr.readAsText(file);
diff --git a/src/components/Tab.vue b/src/components/Tab.vue
index 001923b..49493ec 100644
--- a/src/components/Tab.vue
+++ b/src/components/Tab.vue
@@ -3,7 +3,7 @@
     <div class="toast__text">
       {{ toast.message }}
     </div>
-    
+
     <button class="btn-icon" @click="toast.active = false">
       <svg
         xmlns="http://www.w3.org/2000/svg"
@@ -21,11 +21,12 @@
   </div>
   <div class="tab" :class="{ 'tab--active': tab.active }">
     <div class="folder__header mb10">
-      <h3>Tab ({{ tab.name }})</h3>
+      <h3>{{ t("tab.title", { name: tab.name }) }}</h3>
       <button
         @click="showSettings = !showSettings"
         class="btn-icon"
         :class="{ 'btn-icon--active': showSettings }"
+        :title="t('tab.settings')"
       >
         <svg
           xmlns="http://www.w3.org/2000/svg"
@@ -61,31 +62,31 @@
       </div>
 
       <div v-if="showDeleteConfirmation" class="panel__modal">
-        <h3 class="mb10">Confirm tab deletion</h3>
+        <h3 class="mb10">{{ t("tab.confirmDeletion") }}</h3>
         <div class="panel__modal__actions">
-          <button class="btn btn--danger" @click="deleteTab">Delete</button>
+          <button class="btn btn--danger" @click="deleteTab">{{ t("folder.delete") }}</button>
           <button class="btn" @click="showDeleteConfirmation = false">
-            Cancel
+            {{ t("folder.cancel") }}
           </button>
         </div>
       </div>
-      <h3 class="mb20">Tab settings</h3>
+      <h3 class="mb20">{{ t("tab.settings") }}</h3>
 
       <div class="field mb20">
-        <label class="field__label">Tab name</label>
+        <label class="field__label">{{ t("tab.name") }}</label>
         <input
           class="field__input"
           type="text"
           v-model="tab.name"
-          placeholder="Tab name"
+          :placeholder="t('tab.name')"
           ref="tabName"
         />
       </div>
 
       <div class="field mb20">
         <label class="field__label">
-          Tab request domains
-          <Tooltip> Single or comma separated domains </Tooltip>
+          {{ t("tab.requestDomains") }}
+          <Tooltip>{{ t("tab.requestDomainsHint") }}</Tooltip>
         </label>
         <input
           class="field__input"
@@ -93,26 +94,24 @@
           v-model="tab.requestDomains"
           placeholder="Domains"
         />
-        <label class="field__hint"
-          >- Applies to all tab rules unless overridden</label
-        >
+        <label class="field__hint">{{ t("tab.domainsFallbackHint") }}</label>
       </div>
 
       <div class="panel__actions btn-group">
         <button @click="showDeleteConfirmation = true" class="btn">
-          Delete tab
+          {{ t("tab.deleteTab") }}
         </button>
-        <button @click="cloneTab" class="btn">Clone tab</button>
+        <button @click="cloneTab" class="btn">{{ t("tab.cloneTab") }}</button>
       </div>
     </div>
 
     <div class="panel">
-      <h3 class="mb10">
-        Request headers
+      <h3 class="mb10" :title="t('tab.requestHeadersTooltip')">
+        {{ t("tab.requestHeaders") }}
          - {{ requestHeaderTotal }}
       </h3>
       <div class="empty" v-if="!tab.requestHeaders?.length">
-        Zero request headers
+        {{ t("tab.zeroRequestHeaders") }}
       </div>
 
       <table class="table" v-if="tab.requestHeaders?.length">
@@ -120,20 +119,15 @@
           <th></th>
           <th></th>
           <th></th>
-          <th>Name</th>
-          <th>Value</th>
+          <th>{{ t("tab.table.name") }}</th>
+          <th>{{ t("tab.table.value") }}</th>
           <th>
-            Url Filter
-            <!-- <Tooltip>
-              The pattern which is matched against the network request url
-            </Tooltip> -->
+            {{ t("tab.table.urlFilter") }}
           </th>
           <th>
-            Domains
-
-            <!-- <Tooltip> Single or comma separated domains </Tooltip> -->
+            {{ t("tab.table.domains") }}
           </th>
-          <th>Note</th>
+          <th>{{ t("tab.table.note") }}</th>
           <th></th>
         </tr>
 
@@ -154,7 +148,7 @@
               :class="{ 'toggle--active': header.active }"
             >
               <div class="toggle__text">
-                {{ header.active ? "On" : "Off" }}
+                {{ header.active ? t("folderPanel.on") : t("folderPanel.off") }}
               </div>
             </button>
           </td>
@@ -162,21 +156,21 @@
             <Dropdown v-model="header.operation" :options="operationOptions" />
           </td>
           <td :colspan="header.operation !== 'remove' ? 1 : 2">
-            <Editor v-model="header.name" placeholder="Header name" label="Header name" />
+            <Editor v-model="header.name" :placeholder="t('tab.placeholder.headerName')" :label="t('tab.table.name')" />
           </td>
           <td v-if="header.operation !== 'remove'">
-            <Editor v-model="header.value" placeholder="Header value" />
+            <Editor v-model="header.value" :placeholder="t('tab.placeholder.headerValue')" />
           </td>
           <td>
             <Editor
               v-model="header.condition.urlFilter"
-              placeholder="urlFilter"
+              :placeholder="t('tab.placeholder.urlFilter')"
             />
           </td>
           <td>
             <Editor
               v-model="header.condition.requestDomains"
-              placeholder="Request domains"
+              :placeholder="t('tab.placeholder.domains')"
               :aligned="'right'"
               :fallback="tab.requestDomains"
               :domains="true"
@@ -185,10 +179,10 @@
           <td class="table__short">
             <Editor
               v-model="header.note"
-              placeholder="Note"
+              :placeholder="t('tab.placeholder.note')"
               :icon="true"
               :aligned="'right'"
-              label="Note"
+              :label="t('tab.table.note')"
             />
           </td>
           <td class="table__short text-right">
@@ -198,16 +192,16 @@
       </table>
 
       <button class="btn mt10" @click="addRequestHeader()">
-        Add
+        {{ t("folderPanel.add") }}
       </button>
     </div>
 
     <div class="panel">
-      <h3 class="mb10">
-        Response headers - {{ responseHeaderTotal }}
+      <h3 class="mb10" :title="t('tab.responseHeadersTooltip')">
+        {{ t("tab.responseHeaders") }} - {{ responseHeaderTotal }}
       </h3>
       <div class="empty" v-if="!tab.responseHeaders?.length">
-        Zero response headers
+        {{ t("tab.zeroResponseHeaders") }}
       </div>
 
       <table class="table" v-if="tab.responseHeaders?.length">
@@ -215,19 +209,15 @@
           <th></th>
           <th></th>
           <th></th>
-          <th>Name</th>
-          <th>Value</th>
+          <th>{{ t("tab.table.name") }}</th>
+          <th>{{ t("tab.table.value") }}</th>
           <th>
-            Url Filter
-            <!-- <Tooltip>
-              The pattern which is matched against the network request url
-            </Tooltip> -->
+            {{ t("tab.table.urlFilter") }}
           </th>
           <th>
-            Domains
-            <!-- <Tooltip>Single or comma separated domains</Tooltip> -->
+            {{ t("tab.table.domains") }}
           </th>
-          <th>Note</th>
+          <th>{{ t("tab.table.note") }}</th>
           <th></th>
         </tr>
         <RuleDragger
@@ -247,7 +237,7 @@
               :class="{ 'toggle--active': header.active }"
             >
               <div class="toggle__text">
-                {{ header.active ? "On" : "Off" }}
+                {{ header.active ? t("folderPanel.on") : t("folderPanel.off") }}
               </div>
             </button>
           </td>
@@ -255,21 +245,21 @@
             <Dropdown v-model="header.operation" :options="operationOptions" />
           </td>
           <td :colspan="header.operation !== 'remove' ? 1 : 2">
-            <Editor v-model="header.name" placeholder="Header name" />
+            <Editor v-model="header.name" :placeholder="t('tab.placeholder.headerName')" />
           </td>
           <td v-if="header.operation !== 'remove'">
-            <Editor v-model="header.value" placeholder="Header value" />
+            <Editor v-model="header.value" :placeholder="t('tab.placeholder.headerValue')" />
           </td>
           <td>
             <Editor
               v-model="header.condition.urlFilter"
-              placeholder="urlFilter"
+              :placeholder="t('tab.placeholder.urlFilter')"
             />
           </td>
           <td>
             <Editor
               v-model="header.condition.requestDomains"
-              placeholder="Request domains"
+              :placeholder="t('tab.placeholder.domains')"
               :fallback="tab.requestDomains"
               :domains="true"
               :aligned="'right'"
@@ -278,10 +268,10 @@
           <td class="table__short">
             <Editor
               v-model="header.note"
-              placeholder="Note"
+              :placeholder="t('tab.placeholder.note')"
               :icon="true"
               :aligned="'right'"
-              label="Note"
+              :label="t('tab.table.note')"
             />
           </td>
           <td class="table__short text-right">
@@ -291,34 +281,30 @@
       </table>
 
       <button class="btn mt10" @click="addResponseHeader()">
-        Add
+        {{ t("folderPanel.add") }}
       </button>
     </div>
 
     <div class="panel">
-      <h3 class="mb10">
-        Block requests - {{ blockedTotal }}
+      <h3 class="mb10" :title="t('tab.blockRequestsTooltip')">
+        {{ t("tab.blockRequests") }} - {{ blockedTotal }}
       </h3>
       <div class="empty" v-if="!tab.blockedRequests?.length">
-        Zero blocked requests
+        {{ t("tab.zeroBlockedRequests") }}
       </div>
 
       <table v-if="tab.blockedRequests?.length" class="table">
         <tr>
           <th></th>
           <th class="table__short"></th>
-          <th>Type</th>
+          <th>{{ t("tab.table.type") }}</th>
           <th>
-            Url Filter
-            <!-- <Tooltip>
-              The pattern which is matched against the network request url
-            </Tooltip> -->
+            {{ t("tab.table.urlFilter") }}
           </th>
           <th>
-            Domains
-            <!-- <Tooltip> Single or comma separated domains</Tooltip> -->
+            {{ t("tab.table.domains") }}
           </th>
-          <th>Note</th>
+          <th>{{ t("tab.table.note") }}</th>
           <th class="table__short"></th>
         </tr>
         <RuleDragger
@@ -338,7 +324,7 @@
               :class="{ 'toggle--active': request.active }"
             >
               <div class="toggle__text">
-                {{ request.active ? "On" : "Off" }}
+                {{ request.active ? t("folderPanel.on") : t("folderPanel.off") }}
               </div>
             </button>
           </td>
@@ -352,14 +338,14 @@
             <Editor
               v-if="!request.condition.document"
               v-model="request.condition.urlFilter"
-              placeholder="urlFilter"
+              :placeholder="t('tab.placeholder.urlFilter')"
               :locked="request.condition.document"
             />
           </td>
           <td>
             <Editor
               v-model="request.condition.requestDomains"
-              placeholder="Request domains"
+              :placeholder="t('tab.placeholder.domains')"
               :fallback="tab.requestDomains"
               :domains="true"
               :aligned="'right'"
@@ -368,10 +354,10 @@
           <td class="table__short">
             <Editor
               v-model="request.note"
-              placeholder="Note"
+              :placeholder="t('tab.placeholder.note')"
               :icon="true"
               :aligned="'right'"
-              label="Note"
+              :label="t('tab.table.note')"
             />
           </td>
           <td class="table__short text-right">
@@ -381,16 +367,16 @@
       </table>
 
       <button class="mt10 btn" @click="addBlockedRequest()">
-        Add
+        {{ t("folderPanel.add") }}
       </button>
     </div>
 
     <div class="panel">
-      <h3 class="mb10">
-        Redirect requests - {{ redirectedTotal }}
+      <h3 class="mb10" :title="t('tab.redirectRequestsTooltip')">
+        {{ t("tab.redirectRequests") }} - {{ redirectedTotal }}
       </h3>
       <div class="empty" v-if="!tab.redirectRequests?.length">
-        Zero redirect requests
+        {{ t("tab.zeroRedirectRequests") }}
       </div>
 
       <table v-if="tab.redirectRequests?.length" class="table">
@@ -398,23 +384,17 @@
           <th></th>
           <th class="table__short"></th>
           <th>
-            Url Filter
-            <!-- <Tooltip>
-              The pattern which is matched against the network request url
-            </Tooltip> -->
+            {{ t("tab.table.urlFilter") }}
           </th>
           <th>
-            Destination
-            <!-- <Tooltip> An absolute destination Url </Tooltip> -->
+            {{ t("tab.table.destination") }}
           </th>
           <th>
-            Domains
-            <!-- <Tooltip> Single or comma separated domains</Tooltip> -->
+            {{ t("tab.table.domains") }}
           </th>
-          <th>Note</th>
+          <th>{{ t("tab.table.note") }}</th>
           <th class="table__short"></th>
         </tr>
-        <!-- <tr v-for="request in tab.redirectRequests"> -->
         <RuleDragger
           v-for="(request, index) in tab.redirectRequests"
           :index="Number(index)"
@@ -432,23 +412,23 @@
               :class="{ 'toggle--active': request.active }"
             >
               <div class="toggle__text">
-                {{ request.active ? "On" : "Off" }}
+                {{ request.active ? t("folderPanel.on") : t("folderPanel.off") }}
               </div>
             </button>
           </td>
           <td>
             <Editor
               v-model="request.condition.urlFilter"
-              placeholder="urlFilter"
+              :placeholder="t('tab.placeholder.urlFilter')"
             />
           </td>
           <td>
-            <Editor v-model="request.url" placeholder="Url" />
+            <Editor v-model="request.url" :placeholder="t('tab.placeholder.url')" />
           </td>
           <td>
             <Editor
               v-model="request.condition.requestDomains"
-              placeholder="Request domains"
+              :placeholder="t('tab.placeholder.domains')"
               :fallback="tab.requestDomains"
               :domains="true"
               :aligned="'right'"
@@ -457,10 +437,10 @@
           <td class="table__short">
             <Editor
               v-model="request.note"
-              placeholder="Note"
+              :placeholder="t('tab.placeholder.note')"
               :icon="true"
               :aligned="'right'"
-              label="Note"
+              :label="t('tab.table.note')"
             />
           </td>
           <td class="table__short text-right">
@@ -470,7 +450,7 @@
       </table>
 
       <button class="mt10 btn" @click="addRedirectRequest()">
-        Add
+        {{ t("folderPanel.add") }}
       </button>
     </div>
   </div>
@@ -485,6 +465,9 @@ import Dropdown from "./Dropdown.vue";
 import DropdownMenu from "./DropdownMenu.vue";
 import Tooltip from "./Tooltip.vue";
 import RuleDragger from "./RuleDragger.vue";
+import { useI18n } from "../composables";
+
+const { t } = useI18n();
 
 const props = defineProps({
   tab: {
@@ -499,14 +482,14 @@ const tabName: Ref<HTMLInputElement | null> = ref(null);
 
 const requestActions = [
   {
-    label: "Delete",
+    label: t("tab.action.delete"),
     confirm: true,
     action: (rule:any) => {
       deleteRequestHeader(rule)
     },
   },
   {
-    label: "Copy to clipboard",
+    label: t("tab.action.copyToClipboard"),
     action: (rule: any) => {
       showToast(`${rule.name}${rule.value ? ':' + rule.value : ''}`);
     },
@@ -515,14 +498,14 @@ const requestActions = [
 
 const responseActions = [
   {
-    label: "Delete",
+    label: t("tab.action.delete"),
     confirm: true,
     action: (rule:any) => {
       deleteResponseHeader(rule)
     },
   },
   {
-    label: "Copy to clipboard",
+    label: t("tab.action.copyToClipboard"),
     action: (rule: any) => {
       showToast(`${rule.name}${rule.value ? ':' + rule.value : ''}`);
     },
@@ -531,7 +514,7 @@ const responseActions = [
 
 const blockActions = [
   {
-    label: "Delete",
+    label: t("tab.action.delete"),
     confirm: true,
     action: (rule:any) => {
       deleteBlockRequest(rule)
@@ -541,7 +524,7 @@ const blockActions = [
 
 const redirectActions = [
   {
-    label: "Delete",
+    label: t("tab.action.delete"),
     confirm: true,
     action: (rule:any) => {
       deleteRedirectRequest(rule)
@@ -549,27 +532,34 @@ const redirectActions = [
   }
 ];
 
-const operationOptions = [
+/**
+ * 操作选项（Set / Remove）使用计算属性以支持 i18n 动态更新
+ */
+const operationOptions = computed(() => [
   {
-    label: "Set",
+    label: t("tab.dropdown.set"),
     value: "set",
+    tooltip: t("operation.setTooltip"),
   },
   {
-    label: "Remove",
+    label: t("tab.dropdown.remove"),
     value: "remove",
+    tooltip: t("operation.removeTooltip"),
   },
-];
+]);
 
-const blockOptions = [
+const blockOptions = computed(() => [
   {
-    label: "Assets",
+    label: t("tab.dropdown.assets"),
     value: false,
+    tooltip: t("blockType.assetsTooltip"),
   },
   {
-    label: "Domain",
+    label: t("tab.dropdown.domain"),
     value: true,
+    tooltip: t("blockType.domainTooltip"),
   },
-];
+]);
 
 /**
  * reactive
@@ -631,12 +621,12 @@ const responseHeaderTotal = computed(() => {
 async function showToast(text: string) {
   try {
     await navigator.clipboard.writeText(text).then(() => {
-      toast.value.message = "Copied to clipboard...";
+      toast.value.message = t("tab.toast.copied");
       toast.value.active = true;
       hideToast();
     });
   } catch (error) {
-    toast.value.message = "Couldn't copy to clipboard...";
+    toast.value.message = t("tab.toast.failed");
     toast.value.active = true;
     hideToast();
   }
diff --git a/src/components/TabDragger.vue b/src/components/TabDragger.vue
index 5e9d908..1a68b40 100644
--- a/src/components/TabDragger.vue
+++ b/src/components/TabDragger.vue
@@ -1,15 +1,15 @@
 <template>
-  <div 
+  <div
     v-for="(tab, index) in tabs"
     :key="`tab-drag-${index}`"
     class="tabs__tab"
-    :class="{ 
+    :class="{
       'tabs__tab--active': index === activeTab,
       'tabs__tab--right': index === target && target > tmp && target !== tmp,
       'tabs__tab--left': index === target && target < tmp,
       'tabs__tab--disabled': !tab.active
     }"
-    @click="active = index" :draggable="tmp >= 0" 
+    @click="active = index" :draggable="tmp >= 0"
     @dragover.prevent="target = index"
     @drop="onDragDrop(index)"
     @dragstart="onDragStart(index)"
@@ -17,7 +17,7 @@
     @dragenter="target = index"
     >
 
-    <div v-if="tabs.length > 1" class="tabs__tab__handle" @mousedown="tmp = index" @mouseup="tmp = -1" title="drag to move">
+    <div v-if="tabs.length > 1" class="tabs__tab__handle" @mousedown="tmp = index" @mouseup="tmp = -1" :title="t('tabDragger.dragToMove')">
       <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-grip-horizontal"
         viewBox="0 0 16 16">
         <path
@@ -25,14 +25,14 @@
       </svg>
     </div>
 
-    <button :title="'select ' + tab.name" @click="setTab(index)" class="tabs__tab__label">{{
+    <button :title="t('tabDragger.selectTab', { name: tab.name })" @click="setTab(index)" class="tabs__tab__label">{{
       tab.name }}
     </button>
 
     <button class="toggle" @click="toggle(tab)" :class="{ 'toggle--active': tab.active }"
-      :title="tab.active ? 'Disable folder rules' : 'Enable folder rules'">
+      :title="tab.active ? t('tabDragger.disableRules') : t('tabDragger.enableRules')">
       <div class="toggle__text">
-        {{ tab.active ? "On" : "Off" }}
+        {{ tab.active ? t("folderPanel.on") : t("folderPanel.off") }}
       </div>
     </button>
   </div>
@@ -42,6 +42,9 @@
 <script setup lang="ts">
 import { ref, toRefs, type PropType } from "vue";
 import { TabType } from "../interfaces";
+import { useI18n } from "../composables";
+
+const { t } = useI18n();
 
 const props = defineProps({
   tabs: {
diff --git a/src/composables/index.ts b/src/composables/index.ts
index 2cd06ac..0119140 100644
--- a/src/composables/index.ts
+++ b/src/composables/index.ts
@@ -1,4 +1,5 @@
-import { ref, onUnmounted, type Ref } from 'vue';
+import { ref, onUnmounted, inject, type Ref, type InjectionKey } from 'vue';
+import { getMessage, type Locale } from '../locales';
 
 /**
  * Composable for handling dropdown/modal outside click behavior
@@ -44,3 +45,37 @@ export function useOutsideClick(rootRef: Ref<HTMLElement | null>) {
   };
 }
 
+/** i18n 注入键：当前 locale */
+export const LOCALE_KEY: InjectionKey<Ref<Locale>> = Symbol("locale");
+
+/**
+ * i18n composable
+ * 提供翻译函数 t()，支持路径和插值参数
+ *
+ * @returns {{ t: (path: string, params?: Record<string, string | number>) => string }}
+ */
+export function useI18n() {
+  const locale = inject<Ref<Locale>>(LOCALE_KEY);
+
+  /**
+   * 获取翻译文本
+   *
+   * @param path - 用点号连接的翻译路径，如 "folder.title"
+   * @param params - 可选插值参数，如 { name: "foo" }
+   * @returns 翻译后的字符串
+   */
+  function t(path: string, params?: Record<string, string | number>): string {
+    if (!locale) {
+      // 在 provide 初始化之前调用时，使用浏览器语言作为回退
+      const fallbackLocale: Locale =
+        typeof navigator !== "undefined" && navigator.language.startsWith("zh")
+          ? "zh-CN"
+          : "en";
+      return getMessage(fallbackLocale, path, params);
+    }
+    return getMessage(locale.value, path, params);
+  }
+
+  return { t };
+}
+
diff --git a/src/locales/en.ts b/src/locales/en.ts
new file mode 100644
index 0000000..f8ae0e6
--- /dev/null
+++ b/src/locales/en.ts
@@ -0,0 +1,210 @@
+import type { LocaleMessages } from "./types";
+
+/**
+ * English translation dictionary
+ */
+const en: LocaleMessages = {
+  app: {
+    error: "There was an error setting the rules, did you use an invalid header name?",
+  },
+
+  folderPanel: {
+    folders: "Folders",
+    noFolders: "No folders",
+    add: "Add",
+    addFolder: "Add folder",
+    global: "Global",
+    rulesEnabled: "Rules enabled",
+    rulesEnabledTooltip:
+      "Global toggle: when off, all rules are paused. The number on the badge shows how many rules are currently active.",
+    settings: "Settings",
+    globalSettings: "Global settings",
+    on: "On",
+    off: "Off",
+  },
+
+  folder: {
+    title: "Folder ({name})",
+    confirmDeletion: "Confirm folder deletion",
+    delete: "Delete",
+    cancel: "Cancel",
+    settings: "Folder settings",
+    name: "Folder name",
+    deleteFolder: "Delete folder",
+    cloneFolder: "Clone folder",
+    disableFolder: "Disable folder",
+    enableFolder: "Enable folder",
+  },
+
+  tab: {
+    title: "Tab ({name})",
+    confirmDeletion: "Confirm tab deletion",
+    settings: "Tab settings",
+    name: "Tab name",
+    requestDomains: "Tab request domains",
+    requestDomainsHint: "Single or comma separated domains",
+    domainsFallbackHint: "- Applies to all tab rules unless overridden",
+    deleteTab: "Delete tab",
+    cloneTab: "Clone tab",
+    requestHeaders: "Request headers",
+    requestHeadersTooltip:
+      "Modify outgoing HTTP request headers: set new values or remove existing headers, with URL filter and domain scoping support.",
+    zeroRequestHeaders: "Zero request headers",
+    responseHeaders: "Response headers",
+    responseHeadersTooltip:
+      "Modify server response headers: set new values or remove existing headers, with URL filter and domain scoping support.",
+    zeroResponseHeaders: "Zero response headers",
+    blockRequests: "Block requests",
+    blockRequestsTooltip:
+      "Block matching requests: choose to block assets (JS/CSS/images etc.) or entire page documents, with domain scoping support.",
+    zeroBlockedRequests: "Zero blocked requests",
+    redirectRequests: "Redirect requests",
+    redirectRequestsTooltip:
+      "Redirect matching requests to a specified target URL, with domain scoping support.",
+    zeroRedirectRequests: "Zero redirect requests",
+    table: {
+      name: "Name",
+      value: "Value",
+      urlFilter: "Url Filter",
+      domains: "Domains",
+      note: "Note",
+      type: "Type",
+      destination: "Destination",
+    },
+    placeholder: {
+      headerName: "Header name",
+      headerValue: "Header value",
+      urlFilter: "urlFilter",
+      domains: "Request domains",
+      note: "Note",
+      url: "Url",
+    },
+    action: {
+      delete: "Delete",
+      copyToClipboard: "Copy to clipboard",
+    },
+    toast: {
+      copied: "Copied to clipboard...",
+      failed: "Couldn't copy to clipboard...",
+    },
+    dropdown: {
+      set: "Set",
+      remove: "Remove",
+      assets: "Assets",
+      domain: "Domain",
+    },
+  },
+
+  editor: {
+    save: "Save",
+    cancel: "Cancel",
+  },
+
+  settings: {
+    title: "Settings",
+    compactMode: "Compact mode",
+    compactModeTooltip:
+      "Narrow the left sidebar to give the rule editing area more room.",
+    new: "New",
+    compactDesc:
+      "If you need a bit more space to work with your rules, compact mode reduces the left hand column width.",
+    disableCompact: "Disable compact mode",
+    enableCompact: "Enable compact mode",
+    language: "Language",
+    languageDesc: "Choose the interface language. Changes take effect immediately.",
+    export: "Export",
+    exportDesc:
+      "You can export your rules into .json packages to backup, or send to friends/colleagues. Check the folders you want and click export.",
+    import: "Import",
+    importDesc:
+      "You can select and import modbox backup files and append them to your current set of folders, tabs and rules.",
+    confirmDeletion: "Confirm rules deletion",
+    deleteAll: "Delete all rules",
+    deleteAllDesc:
+      "If you want to totally reset all of your rules. This cannot be undone so please use carefully.",
+    deleteAllBtn: "Delete all",
+    about: "About",
+    aboutDesc:
+      "ModBox is a hobby project with the aim of providing developers and hackers a tool for testing and debugging.",
+    linkedIn: "My LinkedIn",
+    tipJar: "Tip Jar",
+    clear: "Clear",
+    append: "Append",
+    exportBtn: "Export",
+    invalidFile: "Invalid file format. Please select a valid ModBox backup file.",
+    parseFailed: "Failed to parse file. Please ensure it's a valid JSON file.",
+    exportTooLarge: "Export data is too large. Try selecting fewer folders.",
+    exportFailed: "Failed to export rules. Please try again.",
+    help: "Help",
+    helpDesc: "View a quick guide to ModBox's features to help you get started.",
+    openHelp: "Open help",
+    helpContent: {
+      title: "ModBox Help",
+      overview:
+        "ModBox is a Chrome extension for modifying HTTP request/response headers, blocking requests, and redirecting requests. Rules are organized in a two-level hierarchy of Folders and Tabs for easy grouping.",
+      folders: {
+        title: "Folders & Tabs",
+        body: "Folders group related rule sets, and each folder can contain multiple tabs. Click a folder name to expand its rules. Drag-and-drop reordering, cloning, and import/export are supported.",
+      },
+      rules: {
+        title: "Rule Types",
+        body: "Each tab supports four rule types: Request Headers (modify outgoing HTTP headers), Response Headers (modify server response headers), Block Requests (prevent specific URLs from loading), and Redirect Requests (send requests to a different URL).",
+      },
+      condition: {
+        title: "Rule Conditions",
+        body: "Each rule can have a URL Filter (match specific URL patterns) and Domain scoping (only apply on specific domains). Domains support comma-separated values. Tab-level domains serve as the default for all rules within that tab.",
+      },
+      toggle: {
+        title: "Toggle Controls",
+        body: "Every rule, tab, folder, and the global scope has a toggle switch. When turned off, rules at that level are paused. The number next to the global toggle shows how many rules are currently active.",
+      },
+      compact: {
+        title: "Compact Mode",
+        body: "When enabled in Settings, compact mode narrows the left sidebar, showing only folder initials, giving the rule editing area more room.",
+      },
+      exportImport: {
+        title: "Export & Import",
+        body: "In the Settings panel you can export selected folders as JSON files for backup or sharing. You can also import rules from JSON files — new rules are appended to your existing ones.",
+      },
+    },
+  },
+
+  dropdownMenu: {
+    yes: "Yes",
+    no: "No",
+  },
+
+  tabDragger: {
+    selectTab: "select {name}",
+    dragToMove: "drag to move",
+    disableRules: "Disable tab rules",
+    enableRules: "Enable tab rules",
+  },
+
+  folderDragger: {
+    selectFolder: "select {name}",
+    dragToMove: "drag to move",
+    disableRules: "Disable folder rules",
+    enableRules: "Enable folder rules",
+  },
+
+  ruleDragger: {
+    dragToMove: "drag to move",
+  },
+
+  operation: {
+    set: "Set",
+    setTooltip: "Set the header to a new value, overwriting if it already exists.",
+    remove: "Remove",
+    removeTooltip: "Remove this header from the request or response.",
+  },
+
+  blockType: {
+    assets: "Assets",
+    assetsTooltip: "Block non-document requests like JS, CSS, images, XHR etc.",
+    domain: "Domain",
+    domainTooltip: "Block entire page document loads on the matched domain.",
+  },
+};
+
+export default en;
diff --git a/src/locales/index.ts b/src/locales/index.ts
new file mode 100644
index 0000000..ff4a71a
--- /dev/null
+++ b/src/locales/index.ts
@@ -0,0 +1,71 @@
+import type { LocaleMessages } from "./types";
+import type { Locale } from "./types";
+export type { LocaleMessages, Locale };
+import { SUPPORTED_LOCALES, LOCALE_LABELS } from "./types";
+export { SUPPORTED_LOCALES, LOCALE_LABELS };
+import zhCN from "./zh-CN";
+import en from "./en";
+
+/** 所有语言包的映射表 */
+const messages: Record<Locale, LocaleMessages> = {
+  "zh-CN": zhCN,
+  en,
+};
+
+/**
+ * 从浏览器语言自动检测最佳匹配的 locale
+ * 优先精确匹配，否则回退到首个支持的语言（en）
+ */
+export function detectLocale(): Locale {
+  if (typeof navigator === "undefined") return "en";
+
+  const browserLang = navigator.language;
+  // 精确匹配
+  for (const locale of SUPPORTED_LOCALES) {
+    if (locale === browserLang) return locale;
+  }
+  // 前缀匹配（例如 zh 匹配 zh-CN）
+  const baseLang = browserLang.split("-")[0];
+  for (const locale of SUPPORTED_LOCALES) {
+    if (locale.startsWith(baseLang)) return locale;
+  }
+  return "en";
+}
+
+/**
+ * 深层获取翻译文本
+ * 支持点号路径，如 "folder.title" 对应 messages.folder.title
+ *
+ * @param locale - 语言代码
+ * @param path - 用点号连接的翻译路径
+ * @param params - 可选插值参数，如 { name: "foo" }
+ * @returns 翻译后的字符串，未找到时返回路径本身
+ */
+export function getMessage(locale: Locale, path: string, params?: Record<string, string | number>): string {
+  const msg = messages[locale];
+  if (!msg) return path;
+
+  const keys = path.split(".");
+  let result: unknown = msg;
+
+  for (const key of keys) {
+    if (result && typeof result === "object" && key in (result as Record<string, unknown>)) {
+      result = (result as Record<string, unknown>)[key];
+    } else {
+      return path;
+    }
+  }
+
+  if (typeof result !== "string") return path;
+
+  // 插值替换
+  if (params) {
+    return result.replace(/\{(\w+)\}/g, (_, key: string) => {
+      return String(params[key] ?? `{${key}}`);
+    });
+  }
+
+  return result;
+}
+
+export { messages };
diff --git a/src/locales/types.ts b/src/locales/types.ts
new file mode 100644
index 0000000..fe630da
--- /dev/null
+++ b/src/locales/types.ts
@@ -0,0 +1,178 @@
+/**
+ * 国际化消息字典的类型定义
+ * 确保中英文翻译结构完全一致
+ */
+export interface LocaleMessages {
+  app: {
+    error: string;
+  };
+  folderPanel: {
+    folders: string;
+    noFolders: string;
+    add: string;
+    addFolder: string;
+    global: string;
+    rulesEnabled: string;
+    rulesEnabledTooltip: string;
+    settings: string;
+    globalSettings: string;
+    on: string;
+    off: string;
+  };
+  folder: {
+    title: string;
+    confirmDeletion: string;
+    delete: string;
+    cancel: string;
+    settings: string;
+    name: string;
+    deleteFolder: string;
+    cloneFolder: string;
+    disableFolder: string;
+    enableFolder: string;
+  };
+  tab: {
+    title: string;
+    confirmDeletion: string;
+    settings: string;
+    name: string;
+    requestDomains: string;
+    requestDomainsHint: string;
+    domainsFallbackHint: string;
+    deleteTab: string;
+    cloneTab: string;
+    requestHeaders: string;
+    requestHeadersTooltip: string;
+    zeroRequestHeaders: string;
+    responseHeaders: string;
+    responseHeadersTooltip: string;
+    zeroResponseHeaders: string;
+    blockRequests: string;
+    blockRequestsTooltip: string;
+    zeroBlockedRequests: string;
+    redirectRequests: string;
+    redirectRequestsTooltip: string;
+    zeroRedirectRequests: string;
+    table: {
+      name: string;
+      value: string;
+      urlFilter: string;
+      domains: string;
+      note: string;
+      type: string;
+      destination: string;
+    };
+    placeholder: {
+      headerName: string;
+      headerValue: string;
+      urlFilter: string;
+      domains: string;
+      note: string;
+      url: string;
+    };
+    action: {
+      delete: string;
+      copyToClipboard: string;
+    };
+    toast: {
+      copied: string;
+      failed: string;
+    };
+    dropdown: {
+      set: string;
+      remove: string;
+      assets: string;
+      domain: string;
+    };
+  };
+  editor: {
+    save: string;
+    cancel: string;
+  };
+  settings: {
+    title: string;
+    compactMode: string;
+    compactModeTooltip: string;
+    new: string;
+    compactDesc: string;
+    disableCompact: string;
+    enableCompact: string;
+    language: string;
+    languageDesc: string;
+    export: string;
+    exportDesc: string;
+    import: string;
+    importDesc: string;
+    confirmDeletion: string;
+    deleteAll: string;
+    deleteAllDesc: string;
+    deleteAllBtn: string;
+    about: string;
+    aboutDesc: string;
+    linkedIn: string;
+    tipJar: string;
+    clear: string;
+    append: string;
+    exportBtn: string;
+    invalidFile: string;
+    parseFailed: string;
+    exportTooLarge: string;
+    exportFailed: string;
+    help: string;
+    helpDesc: string;
+    openHelp: string;
+    helpContent: {
+      title: string;
+      overview: string;
+      folders: { title: string; body: string };
+      rules: { title: string; body: string };
+      condition: { title: string; body: string };
+      toggle: { title: string; body: string };
+      compact: { title: string; body: string };
+      exportImport: { title: string; body: string };
+    };
+  };
+  dropdownMenu: {
+    yes: string;
+    no: string;
+  };
+  tabDragger: {
+    selectTab: string;
+    dragToMove: string;
+    disableRules: string;
+    enableRules: string;
+  };
+  folderDragger: {
+    selectFolder: string;
+    dragToMove: string;
+    disableRules: string;
+    enableRules: string;
+  };
+  ruleDragger: {
+    dragToMove: string;
+  };
+  operation: {
+    set: string;
+    setTooltip: string;
+    remove: string;
+    removeTooltip: string;
+  };
+  blockType: {
+    assets: string;
+    assetsTooltip: string;
+    domain: string;
+    domainTooltip: string;
+  };
+}
+
+/** 支持的语言代码 */
+export type Locale = "zh-CN" | "en";
+
+/** 所有支持的语言列表 */
+export const SUPPORTED_LOCALES: Locale[] = ["zh-CN", "en"];
+
+/** 语言显示名称映射 */
+export const LOCALE_LABELS: Record<Locale, string> = {
+  "zh-CN": "中文",
+  en: "English",
+};
diff --git a/src/locales/zh-CN.ts b/src/locales/zh-CN.ts
new file mode 100644
index 0000000..d888aa9
--- /dev/null
+++ b/src/locales/zh-CN.ts
@@ -0,0 +1,211 @@
+import type { LocaleMessages } from "./types";
+
+/**
+ * 简体中文翻译字典
+ */
+const zhCN: LocaleMessages = {
+  app: {
+    error: "设置规则时出错，是否使用了无效的标头名称？",
+  },
+
+  folderPanel: {
+    folders: "文件夹",
+    noFolders: "暂无文件夹",
+    add: "添加",
+    addFolder: "添加文件夹",
+    global: "全局",
+    rulesEnabled: "规则已启用",
+    rulesEnabledTooltip:
+      "全局开关：关闭后所有规则将暂停生效，开关下的数字代表当前生效的规则数量",
+    settings: "设置",
+    globalSettings: "全局设置",
+    on: "开",
+    off: "关",
+  },
+
+  folder: {
+    title: "文件夹（{name}）",
+    confirmDeletion: "确认删除文件夹",
+    delete: "删除",
+    cancel: "取消",
+    settings: "文件夹设置",
+    name: "文件夹名称",
+    deleteFolder: "删除文件夹",
+    cloneFolder: "克隆文件夹",
+    disableFolder: "停用文件夹",
+    enableFolder: "启用文件夹",
+  },
+
+  tab: {
+    title: "标签页（{name}）",
+    confirmDeletion: "确认删除标签页",
+    settings: "标签页设置",
+    name: "标签页名称",
+    requestDomains: "标签页请求域名",
+    requestDomainsHint: "单个域名或多域名（逗号分隔）",
+    domainsFallbackHint: "— 适用于该标签页下所有规则，除非被单独覆盖",
+    deleteTab: "删除标签页",
+    cloneTab: "克隆标签页",
+    requestHeaders: "请求标头",
+    requestHeadersTooltip:
+      "修改发出的 HTTP 请求标头：可设置新值或移除已有标头，支持按 URL 过滤和域名筛选",
+    zeroRequestHeaders: "暂无请求标头规则",
+    responseHeaders: "响应标头",
+    responseHeadersTooltip:
+      "修改服务器返回的 HTTP 响应标头：可设置新值或移除已有标头，支持按 URL 过滤和域名筛选",
+    zeroResponseHeaders: "暂无响应标头规则",
+    blockRequests: "拦截请求",
+    blockRequestsTooltip:
+      "拦截匹配的请求：可选择拦截资源（JS/CSS/图片等）或整页文档，支持按域名筛选",
+    zeroBlockedRequests: "暂无拦截规则",
+    redirectRequests: "重定向请求",
+    redirectRequestsTooltip:
+      "将匹配的请求重定向到指定目标 URL，支持按域名筛选",
+    zeroRedirectRequests: "暂无重定向规则",
+    table: {
+      name: "名称",
+      value: "值",
+      urlFilter: "URL 过滤",
+      domains: "域名",
+      note: "备注",
+      type: "类型",
+      destination: "目标地址",
+    },
+    placeholder: {
+      headerName: "标头名称",
+      headerValue: "标头值",
+      urlFilter: "URL 过滤",
+      domains: "请求域名",
+      note: "备注",
+      url: "URL",
+    },
+    action: {
+      delete: "删除",
+      copyToClipboard: "复制到剪贴板",
+    },
+    toast: {
+      copied: "已复制到剪贴板…",
+      failed: "无法复制到剪贴板…",
+    },
+    dropdown: {
+      set: "设置",
+      remove: "移除",
+      assets: "资源",
+      domain: "域名",
+    },
+  },
+
+  editor: {
+    save: "保存",
+    cancel: "取消",
+  },
+
+  settings: {
+    title: "设置",
+    compactMode: "紧凑模式",
+    compactModeTooltip:
+      "收起左侧栏宽度，为规则编辑区腾出更多空间",
+    new: "新功能",
+    compactDesc:
+      "如果你需要更多空间来编辑规则，紧凑模式会收窄左侧栏宽度。",
+    disableCompact: "关闭紧凑模式",
+    enableCompact: "开启紧凑模式",
+    language: "界面语言",
+    languageDesc: "选择插件界面的显示语言，修改后即时生效。",
+    export: "导出",
+    exportDesc:
+      "将你的规则导出为 .json 文件，用于备份或分享给朋友/同事。勾选想要导出的文件夹，然后点击导出。",
+    import: "导入",
+    importDesc:
+      "选择并导入 ModBox 备份文件，将规则追加到你当前的文件夹、标签页和规则中。",
+    confirmDeletion: "确认删除规则",
+    deleteAll: "删除全部规则",
+    deleteAllDesc:
+      "彻底清空所有规则。此操作不可撤销，请谨慎使用。",
+    deleteAllBtn: "全部删除",
+    about: "关于",
+    aboutDesc:
+      "ModBox 是一个业余项目，旨在为开发者和黑客提供一个测试和调试 HTTP 请求的工具。",
+    linkedIn: "我的 LinkedIn",
+    tipJar: "打赏支持",
+    clear: "清除",
+    append: "追加",
+    exportBtn: "导出",
+    invalidFile: "文件格式无效，请选择有效的 ModBox 备份文件。",
+    parseFailed: "文件解析失败，请确认是有效的 JSON 文件。",
+    exportTooLarge: "导出数据过大，请尝试选择更少的文件夹。",
+    exportFailed: "导出规则失败，请重试。",
+    help: "使用帮助",
+    helpDesc:
+      "查看 ModBox 各项功能的简要说明，帮助你快速上手。",
+    openHelp: "查看帮助",
+    helpContent: {
+      title: "ModBox 使用帮助",
+      overview:
+        "ModBox 是一款 Chrome 扩展，用于修改 HTTP 请求/响应标头、拦截请求和重定向请求。规则按「文件夹 → 标签页」两级组织，方便分组管理。",
+      folders: {
+        title: "文件夹与标签页",
+        body: "文件夹用于分组管理规则集，每个文件夹可包含多个标签页。点击文件夹名称可展开该文件夹下的规则。支持拖拽排序、克隆、导入导出。",
+      },
+      rules: {
+        title: "规则类型",
+        body: "每个标签页支持四种规则：请求标头（修改发出的 HTTP 标头）、响应标头（修改服务器返回的标头）、拦截请求（阻止特定 URL 加载）、重定向请求（将请求导向其他地址）。",
+      },
+      condition: {
+        title: "规则条件",
+        body: "每条规则可设置 URL 过滤（匹配特定 URL 模式）和域名筛选（仅在特定域名下生效）。域名支持逗号分隔多个值。标签页级别的域名会作为该标签页下所有规则的默认域名。",
+      },
+      toggle: {
+        title: "开关控制",
+        body: "每条规则、每个标签页、每个文件夹以及全局都有一个开关。关闭后对应层级的规则将暂停生效。全局开关旁的数字表示当前实际生效的规则数量。",
+      },
+      compact: {
+        title: "紧凑模式",
+        body: "在设置中开启紧凑模式后，左侧栏会变窄，仅显示文件夹首字母缩写，为规则编辑区腾出更多空间。",
+      },
+      exportImport: {
+        title: "导出与导入",
+        body: "在设置面板中可导出选中的文件夹为 JSON 文件，用于备份或分享。也可从 JSON 文件导入规则，新规则会追加到现有规则之后。",
+      },
+    },
+  },
+
+  dropdownMenu: {
+    yes: "是",
+    no: "否",
+  },
+
+  tabDragger: {
+    selectTab: "选择 {name}",
+    dragToMove: "拖拽排序",
+    disableRules: "停用该标签页的规则",
+    enableRules: "启用该标签页的规则",
+  },
+
+  folderDragger: {
+    selectFolder: "选择 {name}",
+    dragToMove: "拖拽排序",
+    disableRules: "停用该文件夹的规则",
+    enableRules: "启用该文件夹的规则",
+  },
+
+  ruleDragger: {
+    dragToMove: "拖拽排序",
+  },
+
+  operation: {
+    set: "设置",
+    setTooltip: "将指定标头设置为新的值，如果标头已存在则覆盖",
+    remove: "移除",
+    removeTooltip: "将该标头从请求或响应中移除",
+  },
+
+  blockType: {
+    assets: "资源",
+    assetsTooltip: "拦截 JS/CSS/图片/XHR 等非页面文档类型的请求",
+    domain: "域名",
+    domainTooltip: "拦截整个域名下的页面文档加载",
+  },
+};
+
+export default zhCN;
diff --git a/src/style.scss b/src/style.scss
index 25f3a8c..ca12c08 100644
--- a/src/style.scss
+++ b/src/style.scss
@@ -507,6 +507,15 @@ hr {
   margin-top: 20px;
 }
 
+.help-content {
+  max-height: 70vh;
+  overflow-y: auto;
+  padding-right: 4px;
+  h3 { font-size: 18px; font-weight: 600; }
+  h4 { font-size: 16px; font-weight: 600; color: #333; }
+  p { font-size: 14px; line-height: 1.6; }
+}
+
 // .row {
 //   display: flex;
 //   gap: 20px;

From f073e8ee2b28dc759bad442b331d523c31387d22 Mon Sep 17 00:00:00 2001
From: yuyan <yuyan@ansss.de>
Date: Fri, 21 Aug 2026 22:36:08 +0800
Subject: [PATCH 2/6] =?UTF-8?q?feat(badge):=20=E8=A7=92=E6=A0=87=E6=94=B9?=
 =?UTF-8?q?=E4=B8=BA=E6=98=BE=E7=A4=BA=E5=BD=93=E5=89=8D=E9=A1=B5=E9=9D=A2?=
 =?UTF-8?q?=E5=91=BD=E4=B8=AD=E7=9A=84=E8=A7=84=E5=88=99=E6=95=B0=E9=87=8F?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- service worker 新增规则匹配器（urlFilter 通配语法 + requestDomains 域名后缀匹配），近似复刻 DNR 条件语义
- 监听 tabs.onActivated / tabs.onUpdated / windows.onFocusChanged / storage.onChanged，切换或刷新页面时重算角标
- 命中 0 条或特殊页面（chrome:// 等）时隐藏角标
- 移除 popup 内直接写角标的逻辑，角标写入收敛到 service worker 单独负责；面板顶部"启用规则总数"保持不变

Generated with Co-Authored-By: FuFu <fufu@ansss.de>
---
 public/scripts/service-worker.js | 222 +++++++++++++++++++++++++++++--
 src/App.vue                      |   6 -
 2 files changed, 213 insertions(+), 15 deletions(-)

diff --git a/public/scripts/service-worker.js b/public/scripts/service-worker.js
index aa1ca4c..93cd7f1 100644
--- a/public/scripts/service-worker.js
+++ b/public/scripts/service-worker.js
@@ -1,19 +1,223 @@
-function setBadge() {
-  chrome.storage.local.get(["totalActiveRules"], (result) => {
-    if(result.totalActiveRules) {
-      const total = parseInt(result.totalActiveRules);
-      chrome.action.setBadgeBackgroundColor({ color: "blue" })
-      chrome.action.setBadgeText({ text: total > 0 ? `${total}`: '' });
+/**
+ * ModBox service worker
+ * 负责扩展角标：显示"当前活动标签页命中的规则数量"，0 命中时隐藏角标。
+ * 角标写入权收敛于此处，popup（App.vue）只负责写 rules 数据。
+ */
+
+/**
+ * Parse a domain list string (comma/newline separated) into a cleaned, deduped array.
+ * 与 src/utils.ts 的 parseDomains 语义保持一致。
+ */
+function parseDomains(domains) {
+  if (!domains) return [];
+  const parts = Array.isArray(domains)
+    ? domains
+    : String(domains).split(/[,\n]/);
+  const cleaned = parts
+    .map((d) => String(d || "").trim().replace(/^https?:\/\//i, ""))
+    .filter((d) => d !== "");
+  return [...new Set(cleaned)];
+}
+
+/**
+ * Host suffix match，对齐 DNR requestDomains 语义：
+ * host 等于域名本身，或以 "." + 域名 结尾（子域）；比较前忽略端口、统一小写。
+ */
+function hostMatchesDomain(host, domain) {
+  if (!host || !domain) return false;
+  const h = host.toLowerCase();
+  const d = domain.toLowerCase();
+  if (!d) return false;
+  return h === d || h.endsWith("." + d);
+}
+
+/**
+ * Convert a DNR urlFilter into a RegExp.
+ * 对齐 Chrome urlFilter 语法：
+ *  - "|" 锚定开头/结尾
+ *  - "||" 锚定"协议或子域边界之后"（任意 scheme 下匹配 host 或其子域路径起点）
+ *  - "*" 通配任意字符
+ *  - 其余字符按字面匹配；URL 整体大小写不敏感（Chrome 实际按 scheme/host 不敏感、path 敏感，
+ *    此处取宽松策略：整串不敏感）
+ */
+function urlFilterToRegExp(urlFilter) {
+  let pattern = "";
+  let i = 0;
+  while (i < urlFilter.length) {
+    const ch = urlFilter[i];
+    if (ch === "*") {
+      pattern += ".*";
+      i++;
+    } else if (ch === "|") {
+      if (urlFilter[i + 1] === "|") {
+        // ||example.com 匹配 "://example.com"、"://sub.example.com" 等
+        pattern += "(?:[^:]*:\\/\\/|\\.)";
+        i += 2;
+      } else {
+        pattern += "^";
+        i++;
+      }
+    } else {
+      pattern += ch.replace(/[.+?^${}()[\]\\]/g, "\\$&");
+      i++;
     }
+  }
+  return new RegExp(pattern, "i");
+}
+
+const urlFilterRegExpCache = new Map();
+
+function getCachedUrlFilterRegExp(urlFilter) {
+  let re = urlFilterRegExpCache.get(urlFilter);
+  if (!re) {
+    re = urlFilterToRegExp(urlFilter);
+    if (urlFilterRegExpCache.size > 500) urlFilterRegExpCache.clear();
+    urlFilterRegExpCache.set(urlFilter, re);
+  }
+  return re;
+}
+
+/**
+ * 判断单条规则的 condition 是否命中给定页面。
+ * pageUrl 为顶层文档 URL；语义近似复刻 buildCondition（src/utils.ts）生成的 DNR 条件：
+ *  - urlFilter 与 requestDomains 是 AND 关系
+ *  - 两者皆空 = 匹配一切
+ *  - document:true 的 block 规则只保留域名条件（urlFilter 被 buildCondition 丢弃），此处同样处理
+ */
+function conditionMatchesPage(condition, fallbackDomains, pageUrl, pageHost) {
+  if (!condition) return false;
+
+  // document:true 的 block 规则在 generateRules 中会丢掉 urlFilter，仅保留域名维度
+  const urlFilter =
+    condition.document === true ? "" : String(condition.urlFilter || "").trim();
+  const domainsRaw =
+    condition.requestDomains && String(condition.requestDomains).trim() !== ""
+      ? condition.requestDomains
+      : fallbackDomains;
+  const domains = parseDomains(domainsRaw);
+
+  const hasUrlFilter = urlFilter !== "";
+  const hasDomains = domains.length > 0;
+
+  if (!hasUrlFilter && !hasDomains) return true; // 空条件 = 匹配一切
+
+  if (hasDomains && !domains.some((d) => hostMatchesDomain(pageHost, d))) {
+    return false;
+  }
+
+  if (hasUrlFilter && !getCachedUrlFilterRegExp(urlFilter).test(pageUrl)) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * 从 storage 里的 rules JSON 统计当前页面命中的启用规则数。
+ * 遍历逻辑与 generateRules 一致：data.active → folder.active → tab.active → 各类规则 active。
+ */
+function countMatchedRules(data, pageUrl, pageHost) {
+  let count = 0;
+
+  if (!data?.active || !Array.isArray(data.folders)) return 0;
+
+  for (const folder of data.folders) {
+    if (!folder?.active || !Array.isArray(folder.tabs)) continue;
+    for (const tab of folder.tabs) {
+      if (!tab?.active) continue;
+      const fallbackDomains = tab.requestDomains;
+
+      const ruleGroups = [
+        tab.requestHeaders,
+        tab.responseHeaders,
+        tab.redirectRequests,
+        tab.blockedRequests,
+      ];
+      for (const group of ruleGroups) {
+        if (!Array.isArray(group)) continue;
+        for (const rule of group) {
+          if (!rule?.active) continue;
+          if (
+            conditionMatchesPage(rule.condition, fallbackDomains, pageUrl, pageHost)
+          ) {
+            count++;
+          }
+        }
+      }
+    }
+  }
+  return count;
+}
+
+/** 更新角标为当前活动标签页的命中数；拿不到 URL 或 0 命中则隐藏角标。 */
+function updateBadge() {
+  chrome.tabs.query({ active: true, currentWindow: true }, (tabs) => {
+    const tab = tabs && tabs[0];
+    const url = tab?.url;
+    chrome.action.setBadgeBackgroundColor({ color: "blue" });
+
+    if (!url || !/^https?:\/\//i.test(url)) {
+      // 特殊页面（chrome:// 等）或拿不到 URL：DNR 规则不会作用于这些页面
+      chrome.action.setBadgeText({ text: "" });
+      return;
+    }
+
+    let pageHost = "";
+    try {
+      pageHost = new URL(url).hostname;
+    } catch (e) {
+      chrome.action.setBadgeText({ text: "" });
+      return;
+    }
+
+    chrome.storage.local.get(["rules"], (result) => {
+      if (chrome.runtime.lastError || !result.rules) {
+        chrome.action.setBadgeText({ text: "" });
+        return;
+      }
+      let data;
+      try {
+        data = JSON.parse(result.rules);
+      } catch (e) {
+        chrome.action.setBadgeText({ text: "" });
+        return;
+      }
+      const matched = countMatchedRules(data, url, pageHost);
+      chrome.action.setBadgeText({ text: matched > 0 ? `${matched}` : "" });
+    });
   });
 }
+
 function handleStartup() {
-  setBadge();
+  updateBadge();
 }
 
 function handleInstalled() {
-  setBadge();
+  updateBadge();
 }
 
 chrome.runtime.onStartup.addListener(handleStartup);
-chrome.runtime.onInstalled.addListener(handleInstalled)
\ No newline at end of file
+chrome.runtime.onInstalled.addListener(handleInstalled);
+
+// 切换标签页 / 页面导航刷新时重算
+chrome.tabs.onActivated.addListener(updateBadge);
+chrome.tabs.onUpdated.addListener((tabId, changeInfo, tab) => {
+  // 只在导航实际发生时重算，避免 title 等无关更新反复触发
+  if (changeInfo.url || changeInfo.status === "loading") {
+    updateBadge();
+  }
+});
+
+// popup 内修改规则后重算
+chrome.storage.onChanged.addListener((changes, areaName) => {
+  if (areaName === "local" && changes.rules) {
+    updateBadge();
+  }
+});
+
+// popup 打开时窗口焦点变化也会切回对应标签页，补一次刷新以保证准确
+chrome.windows.onFocusChanged.addListener((windowId) => {
+  if (windowId !== chrome.windows.WINDOW_ID_NONE) {
+    updateBadge();
+  }
+});
diff --git a/src/App.vue b/src/App.vue
index c8f4d64..48d5ed7 100644
--- a/src/App.vue
+++ b/src/App.vue
@@ -181,12 +181,6 @@ async function save() {
 
     chrome.storage.local.set({ rules: JSON.stringify(data.value) });
     chrome.storage.local.set({ totalActiveRules: `${activeRules.length}` });
-
-    // Update badge
-    chrome.action.setBadgeBackgroundColor({ color: "blue" });
-    chrome.action.setBadgeText({
-      text: totalActiveRules.value > 0 ? `${totalActiveRules.value}` : "",
-    });
   } else {
     window.localStorage.setItem("rules", JSON.stringify(data.value));
   }

From d242cf76befb73b4f91c229e25ee88806d1872ec Mon Sep 17 00:00:00 2001
From: yuyan <yuyan@ansss.de>
Date: Fri, 21 Aug 2026 22:37:27 +0800
Subject: [PATCH 3/6] =?UTF-8?q?fix(help):=20=E5=B8=AE=E5=8A=A9=E5=BC=B9?=
 =?UTF-8?q?=E7=AA=97=E9=AB=98=E5=BA=A6=E6=94=B9=E4=B8=BA=E8=87=AA=E9=80=82?=
 =?UTF-8?q?=E5=BA=94=E5=86=85=E5=AE=B9=E5=B9=B6=E6=92=91=E6=BB=A1=E5=8F=AF?=
 =?UTF-8?q?=E7=94=A8=E7=A9=BA=E9=97=B4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- .help-content 去掉 max-height:70vh 的过小限制，改为 max-height:100%，仅受弹窗遮罩内边距约束
- 弹窗内容补底色与圆角，视觉上与面板一致；宽度维持现状不动

Generated with Co-Authored-By: FuFu <fufu@ansss.de>
---
 src/components/Settings.vue | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/components/Settings.vue b/src/components/Settings.vue
index acf3c0a..e00428b 100644
--- a/src/components/Settings.vue
+++ b/src/components/Settings.vue
@@ -174,7 +174,7 @@
 
       <!-- Help Modal -->
       <div v-if="showHelp" class="panel__modal">
-        <div class="help-content">
+        <div class="help-content help-content--panel">
           <h3 class="mb15">{{ t("settings.helpContent.title") }}</h3>
 
           <p class="mb15">{{ t("settings.helpContent.overview") }}</p>

From 0c10e02ea609a3100d367229202e0c485a82a328 Mon Sep 17 00:00:00 2001
From: yuyan <yuyan@ansss.de>
Date: Fri, 21 Aug 2026 22:37:43 +0800
Subject: [PATCH 4/6] =?UTF-8?q?feat(layout):=20=E5=9B=BA=E5=AE=9A=E9=AB=98?=
 =?UTF-8?q?=E5=BA=A6=E5=B8=83=E5=B1=80=EF=BC=8C=E4=BE=A7=E8=BE=B9=E6=A0=8F?=
 =?UTF-8?q?=E4=B8=8D=E5=86=8D=E9=9A=8F=E8=AF=A6=E6=83=85=E5=8C=BA=E4=B8=8A?=
 =?UTF-8?q?=E4=B8=8B=E6=BB=9A=E5=8A=A8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- .folders 锁定 calc(100vh - 20px)，右侧 folders__detail 内部滚动（overflow-y:auto）
- 侧边栏常驻可见；列表过长时侧边栏自身内部滚动，底部 sticky 设置块随之自然生效
- 帮助弹窗样式同步迁移：.help-content 高度上限放宽为遮罩可用空间
- 兼容 compact 模式收窄侧边栏

Generated with Co-Authored-By: FuFu <fufu@ansss.de>
---
 src/style.scss | 22 ++++++++++++++++++++--
 1 file changed, 20 insertions(+), 2 deletions(-)

diff --git a/src/style.scss b/src/style.scss
index ca12c08..27a4d5c 100644
--- a/src/style.scss
+++ b/src/style.scss
@@ -167,16 +167,22 @@ hr {
 
 .folders {
   display: flex;
+  // 固定高度布局：整体锁定视口高度，详情区内部滚动，侧边栏常驻不随内容滚动
+  height: calc(100vh - 20px);
+  min-height: 500px;
 
   &__list {
     flex-basis: 175px;
     margin-right: 12px;
     position: relative;
+    flex-shrink: 0;
     // transition: all ease 0.3s;
     // overflow: hidden;
-    
+
     &__wrapper {
       width: 175px;
+      max-height: 100%;
+      overflow-y: auto;
     }
 
     &__settings {
@@ -331,6 +337,9 @@ hr {
   }
   &__detail {
     flex: 1;
+    min-width: 0;
+    max-height: 100%;
+    overflow-y: auto;
   }
 
   &--compact &__list {
@@ -341,6 +350,8 @@ hr {
   }
   &--compact &__list__wrapper {
     width: auto;
+    max-height: 100%;
+    overflow-y: auto;
   }
 }
 
@@ -508,12 +519,19 @@ hr {
 }
 
 .help-content {
-  max-height: 70vh;
+  // 自适应内容高度，仅受弹窗遮罩（含 20px padding）约束；超出部分内部滚动
+  max-height: 100%;
   overflow-y: auto;
   padding-right: 4px;
   h3 { font-size: 18px; font-weight: 600; }
   h4 { font-size: 16px; font-weight: 600; color: #333; }
   p { font-size: 14px; line-height: 1.6; }
+
+  &--panel {
+    background: #efefef;
+    border-radius: 6px;
+    padding: 15px;
+  }
 }
 
 // .row {

From e892bb6f6df26bcbf1c71cce6a21457b563662e4 Mon Sep 17 00:00:00 2001
From: yuyan <yuyan@ansss.de>
Date: Fri, 21 Aug 2026 22:50:41 +0800
Subject: [PATCH 5/6] =?UTF-8?q?test(badge):=20=E8=A1=A5=E5=85=85=E8=A7=92?=
 =?UTF-8?q?=E6=A0=87=E5=91=BD=E4=B8=AD=E6=95=B0=E5=8C=B9=E9=85=8D=E5=99=A8?=
 =?UTF-8?q?=E7=9A=84=E5=8D=95=E5=85=83=E6=B5=8B=E8=AF=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 覆盖 parseDomains / hostMatchesDomain / urlFilterToRegExp（* 通配、| 与 || 锚点、转义、大小写）
- conditionMatchesPage：urlFilter 与域名 AND 关系、fallback 域名链、document:true 忽略 urlFilter
- countMatchedRules：四类规则计数、各级 active 开关、脏数据安全
- updateBadge 集成（chrome stub）：命中显示数字、0 命中/特殊页面/无数据/坏 JSON 时隐藏、生命周期监听注册
- 通过 Vite ?raw 导入 service worker 源码并在注入 stub 的沙箱中执行，无需 Node 类型依赖

Generated with Co-Authored-By: FuFu <fufu@ansss.de>
---
 src/service-worker.test.ts | 297 +++++++++++++++++++++++++++++++++++++
 1 file changed, 297 insertions(+)
 create mode 100644 src/service-worker.test.ts

diff --git a/src/service-worker.test.ts b/src/service-worker.test.ts
new file mode 100644
index 0000000..6b33114
--- /dev/null
+++ b/src/service-worker.test.ts
@@ -0,0 +1,297 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+// eslint-disable-next-line
+// @ts-nocheck — 原生 .js?raw 导入无类型声明，测试文件内不做类型检查
+import swSource from '../public/scripts/service-worker.js?raw';
+
+/**
+ * service-worker.js 是给 MV3 service worker 用的纯 JS（无导出）。
+ * 这里用 Function 构造器在注入的 chrome stub 环境中执行，再取出内部函数做单元测试。
+ */
+type SWContext = Record<string, any>;
+
+function loadServiceWorker(chromeStub: any): SWContext {
+  const fn = new Function('chrome', 'URL', 'RegExp', swSource + `;
+    this.__exports = { parseDomains, hostMatchesDomain, conditionMatchesPage, countMatchedRules, updateBadge, urlFilterToRegExp };
+  `);
+  const host = { __exports: null as SWContext | null };
+  fn.call(host, chromeStub, URL, RegExp);
+  return host.__exports as SWContext;
+}
+
+function createChromeStub() {
+  const listeners: Record<string, Function[]> = {};
+  const badge = { backgroundColor: undefined as any, text: undefined as any };
+  const chrome = {
+    runtime: {
+      lastError: null,
+      onStartup: { addListener: (f: Function) => push('onStartup', f) },
+      onInstalled: { addListener: (f: Function) => push('onInstalled', f) },
+    },
+    tabs: {
+      onActivated: { addListener: (f: Function) => push('tabs.onActivated', f) },
+      onUpdated: { addListener: (f: Function) => push('tabs.onUpdated', f) },
+      query: (_q: any, cb: (tabs: any[]) => void) => cb(chrome.__activeTabs),
+    },
+    windows: {
+      WINDOW_ID_NONE: -1,
+      onFocusChanged: { addListener: (f: Function) => push('windows.onFocusChanged', f) },
+    },
+    storage: {
+      local: {
+        get: (_keys: any, cb: (r: any) => void) => cb(chrome.__storage),
+        __data: null as any,
+      },
+      onChanged: { addListener: (f: Function) => push('storage.onChanged', f) },
+    },
+    action: {
+      setBadgeBackgroundColor: (opts: any) => { badge.backgroundColor = opts.color; },
+      setBadgeText: (opts: any) => { badge.text = opts.text; },
+    },
+    __activeTabs: [] as any[],
+    __storage: {} as Record<string, string>,
+  };
+  function push(name: string, f: Function) {
+    (listeners[name] = listeners[name] || []).push(f);
+  }
+  (chrome as any).__listeners = listeners;
+  (chrome as any).__badge = badge;
+  return chrome as any;
+}
+
+describe('service worker badge matcher', () => {
+  let chrome: ReturnType<typeof createChromeStub>;
+  let sw: SWContext;
+
+  beforeEach(() => {
+    vi.stubGlobal('chrome', createChromeStub());
+    // eslint-disable-next-line
+    chrome = (globalThis as any).chrome;
+    sw = loadServiceWorker(chrome);
+  });
+
+  describe('parseDomains', () => {
+    it('matches src/utils.ts semantics: split, clean, dedupe', () => {
+      expect(sw.parseDomains("https://a.com, b.com\nc.com ,a.com")).toEqual(["a.com", "b.com", "c.com"]);
+      expect(sw.parseDomains("")).toEqual([]);
+      expect(sw.parseDomains(null)).toEqual([]);
+      expect(sw.parseDomains(["x.com", " https://y.com "])).toEqual(["x.com", "y.com"]);
+    });
+  });
+
+  describe('hostMatchesDomain', () => {
+    it('matches exact host', () => {
+      expect(sw.hostMatchesDomain("example.com", "example.com")).toBe(true);
+    });
+    it('matches subdomain (suffix)', () => {
+      expect(sw.hostMatchesDomain("sub.example.com", "example.com")).toBe(true);
+      expect(sw.hostMatchesDomain("a.b.example.com", "example.com")).toBe(true);
+    });
+    it('does not match partial label or other domain', () => {
+      expect(sw.hostMatchesDomain("notexample.com", "example.com")).toBe(false);
+      expect(sw.hostMatchesDomain("example.org", "example.com")).toBe(false);
+    });
+    it('ignores case and port', () => {
+      expect(sw.hostMatchesDomain("EXAMPLE.com", "example.com")).toBe(true);
+    });
+  });
+
+  describe('urlFilterToRegExp', () => {
+    it('* is a wildcard', () => {
+      const re = sw.urlFilterToRegExp("https://*.example.com/api");
+      expect(re.test("https://cdn.example.com/api/x")).toBe(true);
+      expect(re.test("https://example.com/api/x")).toBe(false);
+    });
+    it('escapes regex special chars literally', () => {
+      const re = sw.urlFilterToRegExp("/a.b?c=1");
+      expect(re.test("https://x.com/a.b?c=1")).toBe(true);
+      expect(re.test("https://x.com/aXb?c=1")).toBe(false);
+    });
+    it('is case-insensitive', () => {
+      expect(sw.urlFilterToRegExp("/API").test("https://x.com/api")).toBe(true);
+    });
+    it('| anchors the start', () => {
+      expect(sw.urlFilterToRegExp("|https://a.com").test("https://a.com/x")).toBe(true);
+      expect(sw.urlFilterToRegExp("|https://a.com").test("https://b.com/https://a.com")).toBe(false);
+    });
+    it('|| matches after protocol or subdomain boundary', () => {
+      const re = sw.urlFilterToRegExp("||ads.example.com");
+      expect(re.test("https://ads.example.com/x")).toBe(true);
+      expect(re.test("https://sub.ads.example.com/y")).toBe(true);
+      expect(re.test("https://evilads.example.com/y")).toBe(false);
+    });
+  });
+
+  describe('conditionMatchesPage', () => {
+    const page = { pageUrl: "https://www.example.com/path", pageHost: "www.example.com" };
+
+    it('empty condition matches everything', () => {
+      expect(sw.conditionMatchesPage({ urlFilter: "", requestDomains: "" }, undefined, page.pageUrl, page.pageHost)).toBe(true);
+    });
+    it('urlFilter AND domains must both hold', () => {
+      const cond = { urlFilter: "/path", requestDomains: "example.com" };
+      expect(sw.conditionMatchesPage(cond, undefined, page.pageUrl, page.pageHost)).toBe(true);
+      expect(sw.conditionMatchesPage({ ...cond, urlFilter: "/other" }, undefined, page.pageUrl, page.pageHost)).toBe(false);
+      expect(sw.conditionMatchesPage({ ...cond, requestDomains: "other.com" }, undefined, page.pageUrl, page.pageHost)).toBe(false);
+    });
+    it('falls back to tab-level domains', () => {
+      const cond = { urlFilter: "", requestDomains: "" };
+      expect(sw.conditionMatchesPage(cond, "fallback.com", "https://x.fallback.com/", "x.fallback.com")).toBe(true);
+      expect(sw.conditionMatchesPage(cond, "fallback.com", "https://other.com/", "other.com")).toBe(false);
+    });
+    it('rule domains take precedence over fallback', () => {
+      const cond = { urlFilter: "", requestDomains: "rule.com" };
+      expect(sw.conditionMatchesPage(cond, "fallback.com", "https://rule.com/", "rule.com")).toBe(true);
+      expect(sw.conditionMatchesPage(cond, "fallback.com", "https://fallback.com/", "fallback.com")).toBe(false);
+    });
+    it('document:true block rules ignore urlFilter (aligned with buildCondition)', () => {
+      const cond = { urlFilter: "should-be-ignored", requestDomains: "example.com", document: true };
+      expect(sw.conditionMatchesPage(cond, undefined, page.pageUrl, page.pageHost)).toBe(true);
+      expect(sw.conditionMatchesPage(cond, undefined, "https://other.com/", "other.com")).toBe(false);
+    });
+    it('missing condition never matches', () => {
+      expect(sw.conditionMatchesPage(null, undefined, page.pageUrl, page.pageHost)).toBe(false);
+    });
+  });
+
+  describe('countMatchedRules', () => {
+    const mkRule = (condition: any, active = true) => ({ active, condition });
+    const mkData = (rules: any[], opts: { dataActive?: boolean; folderActive?: boolean; tabActive?: boolean } = {}) => ({
+      active: opts.dataActive ?? true,
+      folders: [{
+        name: "F", active: opts.folderActive ?? true,
+        tabs: [{
+          name: "T", active: opts.tabActive ?? true, requestDomains: "tab-fallback.com",
+          requestHeaders: rules, responseHeaders: [], blockedRequests: [], redirectRequests: [],
+        }],
+      }],
+    });
+    const url = "https://tab-fallback.com/page";
+
+    it('counts only active rules across all four rule types', () => {
+      const data = {
+        active: true,
+        folders: [{
+          name: "F", active: true,
+          tabs: [{
+            name: "T", active: true, requestDomains: "",
+            requestHeaders: [mkRule({ urlFilter: "", requestDomains: "" })],
+            responseHeaders: [mkRule({ urlFilter: "", requestDomains: "" })],
+            blockedRequests: [mkRule({ urlFilter: "", requestDomains: "", document: false }), mkRule({ urlFilter: "", requestDomains: "" }, false)],
+            redirectRequests: [mkRule({ urlFilter: "", requestDomains: "" })],
+          }],
+        }],
+      };
+      expect(sw.countMatchedRules(data, url, "tab-fallback.com")).toBe(4);
+    });
+
+    it('respects data/folder/tab/rule active flags', () => {
+      expect(sw.countMatchedRules(mkData([mkRule({ urlFilter: "", requestDomains: "" })], { dataActive: false }), url, "tab-fallback.com")).toBe(0);
+      expect(sw.countMatchedRules(mkData([mkRule({ urlFilter: "", requestDomains: "" })], { folderActive: false }), url, "tab-fallback.com")).toBe(0);
+      expect(sw.countMatchedRules(mkData([mkRule({ urlFilter: "", requestDomains: "" })], { tabActive: false }), url, "tab-fallback.com")).toBe(0);
+      expect(sw.countMatchedRules(mkData([mkRule({ urlFilter: "", requestDomains: "" }, false)]), url, "tab-fallback.com")).toBe(0);
+    });
+
+    it('counts only rules whose domains match the page', () => {
+      const data = mkData([
+        mkRule({ urlFilter: "", requestDomains: "tab-fallback.com" }),
+        mkRule({ urlFilter: "", requestDomains: "nomatch.com" }),
+        mkRule({ urlFilter: "", requestDomains: "" }), // fallback 域名命中
+      ]);
+      expect(sw.countMatchedRules(data, url, "tab-fallback.com")).toBe(2);
+    });
+
+    it('handles malformed data safely', () => {
+      expect(sw.countMatchedRules(null, url, "x.com")).toBe(0);
+      expect(sw.countMatchedRules({}, url, "x.com")).toBe(0);
+      expect(sw.countMatchedRules({ active: true, folders: "bad" }, url, "x.com")).toBe(0);
+    });
+  });
+
+  describe('updateBadge (integration with chrome stub)', () => {
+    const mkRule = (condition: any, active = true) => ({ active, condition });
+
+    function setRules(rulesJson: string) {
+      chrome.__storage = { rules: rulesJson };
+    }
+
+    it('shows matched count for a matching page', async () => {
+      setRules(JSON.stringify({
+        active: true,
+        folders: [{
+          name: "F", active: true,
+          tabs: [{
+            name: "T", active: true, requestDomains: "example.com",
+            requestHeaders: [mkRule({ urlFilter: "", requestDomains: "" })],
+            responseHeaders: [], blockedRequests: [], redirectRequests: [],
+          }],
+        }],
+      }));
+      chrome.__activeTabs = [{ url: "https://www.example.com/" }];
+      sw.updateBadge();
+      await new Promise(r => setTimeout(r, 0));
+      expect(chrome.__badge.text).toBe("1");
+    });
+
+    it('hides badge when zero rules match', async () => {
+      setRules(JSON.stringify({
+        active: true,
+        folders: [{
+          name: "F", active: true,
+          tabs: [{
+            name: "T", active: true, requestDomains: "other.com",
+            requestHeaders: [mkRule({ urlFilter: "", requestDomains: "" })],
+            responseHeaders: [], blockedRequests: [], redirectRequests: [],
+          }],
+        }],
+      }));
+      chrome.__activeTabs = [{ url: "https://example.com/" }];
+      sw.updateBadge();
+      await new Promise(r => setTimeout(r, 0));
+      expect(chrome.__badge.text).toBe("");
+    });
+
+    it('hides badge on non-http(s) pages (chrome:// etc.)', async () => {
+      setRules(JSON.stringify({
+        active: true,
+        folders: [{
+          name: "F", active: true,
+          tabs: [{
+            name: "T", active: true, requestDomains: "",
+            requestHeaders: [mkRule({ urlFilter: "", requestDomains: "" })],
+            responseHeaders: [], blockedRequests: [], redirectRequests: [],
+          }],
+        }],
+      }));
+      chrome.__activeTabs = [{ url: "chrome://settings/" }];
+      sw.updateBadge();
+      await new Promise(r => setTimeout(r, 0));
+      expect(chrome.__badge.text).toBe("");
+    });
+
+    it('hides badge when no rules stored yet', async () => {
+      chrome.__storage = {};
+      chrome.__activeTabs = [{ url: "https://example.com/" }];
+      sw.updateBadge();
+      await new Promise(r => setTimeout(r, 0));
+      expect(chrome.__badge.text).toBe("");
+    });
+
+    it('hides badge when stored rules are corrupted JSON', async () => {
+      chrome.__storage = { rules: "{not json" };
+      chrome.__activeTabs = [{ url: "https://example.com/" }];
+      sw.updateBadge();
+      await new Promise(r => setTimeout(r, 0));
+      expect(chrome.__badge.text).toBe("");
+    });
+
+    it('registers all lifecycle listeners on load', () => {
+      const l = chrome.__listeners;
+      expect(l['onInstalled']).toHaveLength(1);
+      expect(l['onStartup']).toHaveLength(1);
+      expect(l['tabs.onActivated']).toHaveLength(1);
+      expect(l['tabs.onUpdated']).toHaveLength(1);
+      expect(l['storage.onChanged']).toHaveLength(1);
+      expect(l['windows.onFocusChanged']).toHaveLength(1);
+    });
+  });
+});

From 817daeb76a623c22ac13389602012476e55fcaae Mon Sep 17 00:00:00 2001
From: yuyan <yuyan@ansss.de>
Date: Fri, 21 Aug 2026 23:07:36 +0800
Subject: [PATCH 6/6] =?UTF-8?q?fix(help):=20=E5=B8=AE=E5=8A=A9=E5=BC=B9?=
 =?UTF-8?q?=E7=AA=97=E6=94=B9=E4=B8=BA=20fixed=20=E9=93=BA=E6=BB=A1=20popu?=
 =?UTF-8?q?p=20=E8=A7=86=E5=8F=A3=EF=BC=8C=E7=9C=9F=E6=AD=A3=E6=92=91?=
 =?UTF-8?q?=E5=A4=A7=E6=98=BE=E7=A4=BA=E5=8C=BA=E5=9F=9F?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

根因：.panel__modal 是 absolute 定位，只能盖住所在的那张小卡片，
help-content 的 max-height:100% 因此被限制在卡片内，视觉上毫无变化。
新增 panel__modal--fullscreen（position:fixed）铺满整个 popup 视口，
帮助内容随之占满可用空间；其余确认类弹窗保持 absolute 不受影响。

Generated with Co-Authored-By: FuFu <fufu@ansss.de>
---
 src/components/Settings.vue | 2 +-
 src/style.scss              | 7 +++++++
 2 files changed, 8 insertions(+), 1 deletion(-)

diff --git a/src/components/Settings.vue b/src/components/Settings.vue
index e00428b..47d4782 100644
--- a/src/components/Settings.vue
+++ b/src/components/Settings.vue
@@ -173,7 +173,7 @@
       </div>
 
       <!-- Help Modal -->
-      <div v-if="showHelp" class="panel__modal">
+      <div v-if="showHelp" class="panel__modal panel__modal--fullscreen">
         <div class="help-content help-content--panel">
           <h3 class="mb15">{{ t("settings.helpContent.title") }}</h3>
 
diff --git a/src/style.scss b/src/style.scss
index 27a4d5c..a011275 100644
--- a/src/style.scss
+++ b/src/style.scss
@@ -518,6 +518,13 @@ hr {
   margin-top: 20px;
 }
 
+// 帮助弹窗专用：absolute 版 modal 只能盖住所在的小卡片，
+// 改为 fixed 铺满整个 popup 视口，内部 help-content 的 max-height:100% 才有意义。
+// 注意需放在 .panel 之后以覆盖其 position；其余确认弹窗不受影响仍为 absolute。
+.panel__modal--fullscreen {
+  position: fixed;
+}
+
 .help-content {
   // 自适应内容高度，仅受弹窗遮罩（含 20px padding）约束；超出部分内部滚动
   max-height: 100%;