scriptscat · Nikitamce · Jul 22, 2026 · Jul 23, 2026
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,6 +1,6 @@
 # 贡献指南 / Contributing Guide
 
-> EN summary: file path = doc ID = published URL, no `id:`/`sidebar_position:` frontmatter, no number-prefixed filenames, `title:` is the only page-title source (no body `# H1`), images live in a sibling `<doc-name>.assets/` folder, and every `docs/**/*.md` needs an `i18n/en/docusaurus-plugin-content-docs/current/**/*.md` mirror. Run `pnpm run check` before opening a PR — it enforces all of this. See [REFACTOR_PROPOSAL.md](./REFACTOR_PROPOSAL.md) for the full rationale.
+> EN summary: file path = doc ID = published URL, no `id:`/`sidebar_position:` frontmatter, no number-prefixed filenames, `title:` is the only page-title source (no body `# H1`), images live in a sibling `<doc-name>.assets/` folder, and every `docs/**/*.md` needs a mirror in each locale docs tree unless an explicit single-source fallback is configured. Run `pnpm run check` before opening a PR — it enforces all of this. See [REFACTOR_PROPOSAL.md](./REFACTOR_PROPOSAL.md) for the full rationale.
 
 本文档记录本仓库的文档结构约定，帮助人类贡献者和 AI Agent 在不读遍全部历史讨论的情况下，正确地新增/修改文档。
 
@@ -23,13 +23,13 @@
 2. frontmatter 只写 `title:`（必需）和可选的 `sidebar_label:`；不要写 `id:` 或 `sidebar_position:`。
 3. 正文**不要**再写一个 `# 标题` 作为 H1——`title:` 会自动渲染为页面标题。
 4. 在 `sidebars.js` 对应的数组里加一行 `"section/xxx"`（除非这是一个故意不出现在侧边栏的隐藏页面，如 `use/install_comple`）。
-5. 在 `i18n/en/docusaurus-plugin-content-docs/current/<section>/xxx.md` 创建英文镜像，路径和文件名必须完全一致。
+5. 在 `i18n/<locale>/docusaurus-plugin-content-docs/current/<section>/xxx.md` 为各非默认 locale 创建镜像，路径和文件名必须完全一致；`scripts/check-config.json` 中声明的单一来源 fallback 路径除外。
 6. 图片放在 `docs/<section>/xxx.assets/` 下，用 `./xxx.assets/foo.png` 引用；纯 UI 截图等语言无关的图片，英文版可以用 `@site/docs/<section>/xxx.assets/foo.png` 直接复用中文版的图片，不必重复存一份二进制文件。
-7. 跑一次 `pnpm run build && pnpm run check`，确认三项检查全部通过。
+7. 跑一次 `pnpm run build && pnpm run check`，确认全部检查通过。
 
 ## 新增一条更新日志
 
-`change/` 下的版本文件（`v1.x.md`）不使用数字前缀排序；在 `sidebars.js` 的 `change` 数组里手动插入新版本号（数组顺序即侧边栏顺序，新版本插在最前面）。`change/beta-changelog.md` 是 Beta 版本的单独更新日志。
+`change/` 下的版本文件（`v1.x.md`）不使用数字前缀排序；在 `sidebars.js` 的 `change` 数组里手动插入新版本号（数组顺序即侧边栏顺序，新版本插在最前面）。`change/beta-changelog.md` 是 Beta 版本的单独更新日志。更新中文源文时仍需同步英文版本；俄语路由由 Docusaurus 直接回退到英文文档树，不要在 `i18n/ru/.../change/` 中恢复一份会漂移的副本。
 
 ## 加载不变的 URL（改动前必须确认不受影响）
 
@@ -43,22 +43,24 @@
 
 ## 翻译对照表
 
-| 中文 | English |
-|---|---|
-| 脚本猫 | ScriptCat |
-| 用户脚本 | user script |
-| 后台脚本 | background script |
-| 定时脚本 | scheduled script |
-| 油猴 | Tampermonkey |
+| 中文 | English | Русский |
+|---|---|---|
+| 脚本猫 | ScriptCat | ScriptCat |
+| 用户脚本 | user script | пользовательский скрипт |
+| 后台脚本 | background script | фоновый скрипт |
+| 定时脚本 | scheduled script | скрипт по расписанию |
+| 定时任务 | scheduled task | задача по расписанию |
+| 油猴 | Tampermonkey | Tampermonkey |
 
 英文标题结构应尽量与中文一一对应（标题层级、顺序一致），这样跨语言的锚点链接更容易对齐；注意 Docusaurus 生成的锚点是基于**渲染后的英文标题文本**，不是中文锚点的直接翻译（例如 `## Scheduled Script (\`@crontab\`)` 生成的锚点是 `#scheduled-script-crontab`，需要用构建产物核实，不要凭感觉猜。
 
 ## 本地检查命令
 
 ```bash
-pnpm run build          # 构建两个语言版本，onBrokenLinks/onBrokenAnchors 设置为 throw
-pnpm run check           # 依次跑 url 一致性 / i18n 覆盖率 / frontmatter 规范三项检查
+pnpm run build          # 构建 zh-Hans/en/ru，onBrokenLinks/onBrokenAnchors 设置为 throw
+pnpm run check           # 依次跑 URL / fallback 产物 / i18n 覆盖率 / frontmatter 检查
 pnpm run check:urls       # 单独跑 URL 不变契约检查
-pnpm run check:i18n       # 单独跑中英文档配对检查
+pnpm run check:fallbacks  # 单独检查 production build 中的 locale 单一来源 fallback
+pnpm run check:i18n       # 单独跑所有 locale 的文档配对及 fallback 例外检查
 pnpm run check:frontmatter # 单独跑 title/id/sidebar_position/H1 规范检查
 ```
diff --git a/docusaurus.config.js b/docusaurus.config.js
@@ -3,6 +3,35 @@
 
 import { themes as prismThemes } from "prism-react-renderer";
 
+const { defaultLocale, i18nDocFallbacks = {} } = require("./scripts/check-config.json");
+const currentLocale = process.env.DOCUSAURUS_CURRENT_LOCALE ?? defaultLocale;
+const docsFallbackLocale = i18nDocFallbacks[currentLocale]?.sourceLocale;
+const docsPath = docsFallbackLocale
+  ? `i18n/${docsFallbackLocale}/docusaurus-plugin-content-docs/current`
+  : "docs";
+
+const metadataByLocale = {
+  "zh-Hans": {
+    keywords:
+      "scriptcat,userscript,browser extension,浏览器扩展,用户脚本,后台脚本,脚本猫,tampermonkey,violentmonkey,greasemonkey,javascript,自动化脚本,网页增强",
+    description:
+      "ScriptCat 是一个可以执行自定义脚本的浏览器扩展，支持用户脚本、后台脚本等多种脚本类型。提供强大的脚本管理、同步、订阅等功能。",
+  },
+  en: {
+    keywords:
+      "scriptcat,userscript,browser extension,user scripts,background scripts,scheduled scripts,userscript manager,tampermonkey,violentmonkey,greasemonkey,javascript,browser automation",
+    description:
+      "ScriptCat is an open-source browser extension for user scripts, background scripts, and scheduled scripts, with powerful management, sync, and subscription features.",
+  },
+  ru: {
+    keywords:
+      "scriptcat,userscript,расширение браузера,пользовательские скрипты,фоновые скрипты,скрипты по расписанию,менеджер пользовательских скриптов,tampermonkey,violentmonkey,greasemonkey,javascript,автоматизация браузера",
+    description:
+      "ScriptCat — открытое расширение браузера для пользовательских, фоновых скриптов и скриптов по расписанию с удобным управлением, синхронизацией и подписками.",
+  },
+};
+const metadata = metadataByLocale[currentLocale] ?? metadataByLocale[defaultLocale];
+
 /** @type {import('@docusaurus/types').Config} */
 const config = {
   title: "ScriptCat",
@@ -47,8 +76,8 @@ const config = {
   // metadata like html lang. For example, if your site is Chinese, you may want
   // to replace "en" with "zh-Hans".
   i18n: {
-    defaultLocale: "zh-Hans",
-    locales: ["zh-Hans", "en"],
+    defaultLocale,
+    locales: ["zh-Hans", "en", "ru"],
     localeConfigs: {
       "zh-Hans": {
         label: "简体中文",
@@ -60,6 +89,11 @@ const config = {
         direction: "ltr",
         htmlLang: "en",
       },
+      ru: {
+        label: "Русский",
+        direction: "ltr",
+        htmlLang: "ru",
+      },
     },
   },
 
@@ -69,6 +103,11 @@ const config = {
       /** @type {import('@docusaurus/preset-classic').Options} */
       ({
         docs: {
+          // Docusaurus normally falls back to the default (Chinese) docs tree.
+          // For configured locales, use another locale as the base tree while
+          // still letting localized files override it. check:i18n restricts
+          // which paths may rely on this fallback.
+          path: docsPath,
           sidebarPath: require.resolve("./sidebars.js"),
           // Please change this to your repo.
           // Remove this to remove the "edit this page" links.
@@ -100,13 +139,11 @@ const config = {
       metadata: [
         {
           name: "keywords",
-          content:
-            "scriptcat,userscript,browser extension,浏览器扩展,用户脚本,后台脚本,脚本猫,tampermonkey,violentmonkey,greasemonkey,javascript,自动化脚本,网页增强",
+          content: metadata.keywords,
         },
         {
           name: "description",
-          content:
-            "ScriptCat 是一个可以执行自定义脚本的浏览器扩展，支持用户脚本、后台脚本等多种脚本类型。提供强大的脚本管理、同步、订阅等功能。",
+          content: metadata.description,
         },
       ],
       navbar: {

diff --git a/i18n/en/code.json b/i18n/en/code.json
@@ -27,6 +27,10 @@
     "message": "Find these updates useful? Star us on GitHub to support our work",
     "description": "GitHub star bar subtitle on changelog page"
   },
+  "homepage.meta.keywords": {
+    "message": "ScriptCat,user scripts,browser extension,userscript,Tampermonkey,Violentmonkey,background scripts,scheduled scripts,browser automation,ad blocker,script store",
+    "description": "Homepage SEO keywords"
+  },
   "homepage.meta.title": {
     "message": "ScriptCat - Powerful Browser Script Engine",
     "description": "Homepage meta title for SEO"

diff --git a/i18n/en/docusaurus-plugin-content-docs/current/change/index.md b/i18n/en/docusaurus-plugin-content-docs/current/change/index.md
@@ -12,7 +12,7 @@ import SponsorBlock from '@site/src/components/SponsorBlock/en.mdx';
 
 For Beta version changelog, please see [Beta Changelog](./beta-changelog.md)
 
-⚠️ Please note that if you are using Windows 8/7/XP, or your browser kernel version is lower than 120, you need to manually install the [legacy version of ScriptCat](https://github.com/scriptscat/scriptcat/releases). v0.16.x is the last version that supports Manifest V2. Installation steps can be found at: [Install Extension by Loading Unpacked](/docs/use/use/#load-unpacked-extension-installation).
+⚠️ Please note that if you are using Windows 8/7/XP, or your browser kernel version is lower than 120, you need to manually install the [legacy version of ScriptCat](https://github.com/scriptscat/scriptcat/releases). v0.16.x is the last version that supports Manifest V2. Installation steps can be found at: [Install Extension by Loading Unpacked](/use/use.md#load-unpacked-extension-installation).
 
 <a name="1.4.0"></a>