diff --git a/docs/contributing.md b/docs/contributing.md
index 7108309..ce2bae5 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -20,12 +20,17 @@ pnpm install
 
 # 启动开发（先以 debug 构建原生模块，再启动 Electron）
 pnpm dev
+
+# 启动开发时向程序传递参数
+pnpm dev -- [参数]...
 ```
 
 只做界面开发、想跳过 Rust 编译时，可设置 `SKIP_NATIVE_BUILD=true`。
 
 ## 构建
 
+基础命令
+
 ```bash
 pnpm build         # 完整构建：清理 → 原生模块 → 类型检查 → electron-vite
 pnpm build:win     # 打包 Windows
@@ -33,6 +38,19 @@ pnpm build:mac     # 打包 macOS
 pnpm build:linux   # 打包 Linux
 ```
 
+高级命令
+
+```bash
+# 上面的构建命令默认会构建当前平台和架构的全部 target。可以通过下面的方法指定只打包某些 target
+pnpm build:win nsis       # 打包 Windows 的 nsis 格式
+pnpm build:mac dmg        # 打包 macOS 的 dmg 格式
+pnpm build:linux tar.gz   # 打包 Linux 的 tar.gz 格式
+# 全部 target 的列表详见 https://www.electron.build/docs/targets
+
+# 仅构建未打包的程序目录，常用于本地测试（在 dist/xxx-unpacked 目录）
+pnpm build:unpack
+```
+
 ## 常用脚本
 
 ```bash
@@ -61,6 +79,33 @@ shared/             跨进程共享的类型与默认配置
 - **原生类型**：从 `@splayer/*` 导入，切勿手写 `native/*/index.d.ts`。
 - **提交信息**：使用单行中文标题，无特殊说明不附正文。
 
+## 国际化
+
+本项目使用 [vue-i18n](https://vue-i18n.intlify.dev/) 进行国际化
+
+### Visual Studio Code 系列
+
+推荐使用 [i18n Ally](https://marketplace.visualstudio.com/items?itemName=Lokalise.i18n-ally) 插件
+
+1. 安装插件
+2. 打开本项目，打开 `.vscode` 文件夹（若找不到，需要打开显示隐藏文件）
+3. 编辑或新建 `settings.json` 文件，编辑或新增 `i18n-ally.localesPaths`，值为 `./src/i18n/locales/`，就像这样
+   ```json
+   {
+     "i18n-ally.localesPaths": "./src/i18n/locales/"
+   }
+   ```
+
+### JetBrains 系列
+
+推荐使用 [Easy i18n](https://plugins.jetbrains.com/plugin/16316-easy-i18n) 插件
+
+1. 安装插件
+2. 打开本项目，在 **设置 → 工具 → Easy i18n** 中配置此插件
+3. 在 **Modules Configuration → Add new module**，输入 SPlayer-Next（或任意名称），点击右侧的加号，新建模块
+4. 在下方的配置中，找到 **Preset** 选择 **VUE_I18N**。在 **Resource Configuration** 的 **Path template** 中填写 `$PROJECT_DIR$/src/i18n/locales/{locale}.json`
+5. (可选) 在上方的 **Common Configuration** 的 **Preview locale** 中填写 `zh-CN`
+
 ## 提交 Pull Request
 
 1. 从 `dev` 分支切出特性分支进行开发；
diff --git a/docs/troubleshooting/debug.md b/docs/troubleshooting/debug.md
index 060e0c7..865419f 100644
--- a/docs/troubleshooting/debug.md
+++ b/docs/troubleshooting/debug.md
@@ -36,6 +36,10 @@
 
 请附上：操作系统与版本、SPlayer-Next 版本（开发版附 Commit ID）、Console 完整错误日志、可复现的操作步骤。
 
+> [!IMPORTANT]
+>
+> 如果是 Linux，请先查看 [Linux Wayland 兼容性](./wayland)。报告故障时附带桌面环境、发行版、所使用的安装包格式（官方包）或构建脚本（第三方包）
+
 ## 重置应用
 
 ::: warning 注意
@@ -52,5 +56,5 @@ rd /s /q "%APPDATA%\SPlayer-Next"
 rm -rf ~/Library/Application\ Support/SPlayer-Next
 
 # Linux
-rm -rf ~/.config/SPlayer-Next
+rm -rf "${XDG_CONFIG_HOME:-$HOME/.config}/SPlayer-Next"
 ```
diff --git a/docs/troubleshooting/macos-damaged.md b/docs/troubleshooting/macos-damaged.md
index d706e6d..a1c1b0f 100644
--- a/docs/troubleshooting/macos-damaged.md
+++ b/docs/troubleshooting/macos-damaged.md
@@ -1,4 +1,4 @@
-# Mac 系统应用显示已损坏
+# macOS 应用显示已损坏
 
 在 macOS 上打开 SPlayer-Next 时，可能会遇到“应用已损坏，无法打开”的提示。这通常是 macOS 的安全机制导致的，而非应用本身损坏。
 
@@ -18,17 +18,25 @@
 
 ## 解决方案
 
-### 方法一：移除隔离属性（推荐）
+### 方法一：安全移除隔离属性（推荐）
 
 打开 **终端**，执行：
 
 ```bash
-sudo xattr -r -d com.apple.quarantine /Applications/SPlayer-Next.app
+sudo xattr -rd com.apple.quarantine /Applications/SPlayer-Next.app
 ```
 
 输入管理员密码后，重新打开应用即可。
 
-### 方法二：右键打开
+### 方法二：强制移除所有属性（不推荐）
+
+打开 **终端**，执行：
+
+```bash
+sudo xattr -cr /Applications/SPlayer-Next.app
+```
+
+### 方法三：右键打开
 
 1. 在 Finder 中找到 `SPlayer-Next.app`；
 2. 按住 `Control` 键点击应用图标；
@@ -42,7 +50,7 @@ sudo xattr -r -d com.apple.quarantine /Applications/SPlayer-Next.app
 如果使用 M1/M2/M3 芯片的 Mac，请尽量下载 **ARM（arm64）** 版本的安装包。若下载了 x64 版本，可能需要 Rosetta 2 转译：
 
 ```bash
-softwareupdate --install-rosetta
+softwareupdate --install-rosetta --agree-to-license
 ```
 
 ## 仍然无法解决？
diff --git a/docs/troubleshooting/macos.md b/docs/troubleshooting/macos.md
index 6f77e84..bcd9d55 100644
--- a/docs/troubleshooting/macos.md
+++ b/docs/troubleshooting/macos.md
@@ -14,7 +14,7 @@
 2. 或在终端执行：
 
    ```bash
-   xattr -cr /Applications/SPlayer-Next.app
+   sudo xattr -rd com.apple.quarantine /Applications/SPlayer-Next.app
    ```
 
 若提示“应用已损坏”，请参考 [Mac 应用显示已损坏](/troubleshooting/macos-damaged)。
@@ -22,8 +22,8 @@
 ### Gatekeeper 持续阻止
 
 ```bash
-# 移除隔离属性
-sudo xattr -r -d com.apple.quarantine /Applications/SPlayer-Next.app
+# 强制移除所有属性
+sudo xattr -cr /Applications/SPlayer-Next.app
 ```
 
 ## 系统集成
diff --git a/docs/troubleshooting/wayland.md b/docs/troubleshooting/wayland.md
index 36b1e5c..c54d69a 100644
--- a/docs/troubleshooting/wayland.md
+++ b/docs/troubleshooting/wayland.md
@@ -2,11 +2,9 @@
 
 在 Wayland 会话下，部分**窗口相关功能**可能受限，个别环境甚至会出现画面闪烁、花屏乃至系统卡死。这是 Electron / Chromium 在 Wayland 下的通用情况，并非应用本身的缺陷。
 
-## 首选方案：切回 XWayland
+## 使用 Xwayland
 
-遇到花屏、闪烁、卡死或悬浮窗异常时，最稳妥的办法是让应用以 **X11（XWayland）** 模式运行——在启动参数中加入 `--ozone-platform=x11`。
-
-> SPlayer-Next 默认即以 XWayland 运行；若你或发行版启用了原生 Wayland 并遇到问题，用此参数可强制回退。
+遇到花屏、闪烁、卡死或悬浮窗异常时，最稳妥的办法是让应用以 **X11（Xwayland）** 模式运行——在启动参数中加入 `--ozone-platform=x11`。
 
 开发环境：
 
@@ -24,25 +22,19 @@ pnpm dev -- --ozone-platform=x11
 
 **其他桌面环境**
 
-1. 找到 SPlayer-Next 的 `.desktop` 文件（通常在 `/usr/share/applications/` 下）；
+1. 找到 SPlayer-Next 的 `.desktop` 文件（通常在 `/usr/share/applications/` 下，文件名为 `top.imsyy.splayer_next.desktop`）；
 2. 复制到 `~/.local/share/applications/`；
 3. 用文本编辑器打开，找到 `Exec=` 开头的行，在可执行文件后追加 `--ozone-platform=x11`，例如：
-   ```
-   Exec=/opt/SPlayer-Next/splayer-next --ozone-platform=x11 %U
+   ```desktop
+   Exec=/opt/SPlayer-Next/SPlayer-Next --ozone-platform=x11 %U
    ```
 4. 保存退出。
 
-## 原生 Wayland（可选）
-
-原生 Wayland 渲染更清晰、HiDPI / 分数缩放表现更好，但下面的窗口能力会更受限，且个别环境可能出现闪屏 / 卡死——**遇到问题请按上文回退 X11**。
-
-启用方式（命令行）：
-
-```bash
-ELECTRON_OZONE_PLATFORM_HINT=auto ./SPlayer-Next-*.AppImage
-# 或
-./SPlayer-Next-*.AppImage --ozone-platform-hint=auto
-```
+> [!IMPORTANT]
+>
+> 即使切换回 Xwayland，全局快捷键仍可能无法正常生效。
+>
+> 部分桌面环境对此有支持。如 KDE Plasma Wayland 可以在 **系统设置 → 应用程序权限 → 旧式 X11 应用程序支持** 中，将 **监听按键** 设置为 「**和上面一样，加上按住 Ctrl、Alt、Meta 等修饰键时按下的任何按键**」
 
 ## 已知的窗口限制
 
@@ -55,25 +47,89 @@ Wayland 出于安全考虑，不允许应用读取 / 设置全局屏幕坐标，
 | 窗口置顶（always-on-top）                | 支持有限，悬浮窗可能无法保持置顶                  |
 | 鼠标穿透（click-through）                | 可能不生效                                        |
 | 悬停判定（全局光标位置）                 | Wayland 限制读取全局光标，悬停隐藏 / 交互可能不准 |
-| 全局快捷键                               | Wayland 下通常无法注册全局快捷键                  |
+| 全局快捷键                               | Wayland 下可能无法注册全局快捷键                  |
 
 > 具体表现因发行版与合成器（GNOME Mutter、KDE KWin、wlroots 等）而异。
 
-## 桌面歌词的 KWin 窗口规则
+## 桌面歌词的窗口规则
+
+桌面歌词窗口使用固定的窗口标题 **`SPlayer-Next - Desktop Lyric`** 以方便窗口规则匹配。
 
-桌面歌词窗口使用固定的窗口标题 **`SPlayer-Next - Desktop Lyric`**。在 KDE（KWin）下可通过**窗口规则**按标题匹配，手动补齐 Wayland 下缺失的行为（如保持置顶等）：
+在 KDE（KWin）下可通过**窗口规则**按标题匹配，手动补齐 Wayland 下缺失的行为（如保持置顶等）：
 
 1. 打开 **系统设置 → 窗口管理 → 窗口规则**，新建一条规则；
-2. 在 **窗口匹配** 中，将 **窗口标题** 设为 `SPlayer-Next - Desktop Lyric`（精确或包含匹配）；
+2. 在 **窗口匹配** 中，将 **窗口类** 设为 `top.imsyy.splayer_next`（精确匹配），将 **窗口标题** 设为 `SPlayer-Next - Desktop Lyric`（精确匹配）；
 3. 添加需要的属性，例如：
-   - **保持在其他窗口之上**：设为「强制 / 是」；
-   - 可选 **无标题栏与边框**、固定 **位置** 与 **大小**；
+   - **窗口置顶**：设为 **强制**、**是**；
+   - 可选 **图层**：设为 **强制**、**叠加**（全屏游戏时窗口也在上方）；
+   - 可选 **虚拟桌面**：设为 **强制**、**所有桌面**（窗口同时处于所有虚拟桌面）；
+   - 可选 **跳过任务栏**、**跳过虚拟桌面切换器**、**跳过窗口切换器**：设为 **强制**、**是**（优化一些细节体验）；
+   - 可选固定 **位置** 与 **大小**；
 4. 应用并保存。
 
+其它 DE/WM 也可参考此配置方法自行配置。
+
+<details>
+
+<summary>可直接导入的规则</summary>
+
+> 这里提供了一些可直接导入的规则。欢迎 PR 补充你的 DE/WM
+
+KWin 规则
+
+> 编者用的规则，我觉得挺好用的。如有更好的规则欢迎 PR
+
+```ini
+[SPlayer Next 桌面歌词]
+Description=SPlayer Next 桌面歌词
+above=true
+aboverule=2
+desktops=\\0
+desktopsrule=2
+layer=overlay
+layerrule=2
+skippager=true
+skippagerrule=2
+skipswitcher=true
+skipswitcherrule=2
+skiptaskbar=true
+skiptaskbarrule=2
+title=SPlayer-Next - Desktop Lyric
+titlematch=1
+wmclass=top.imsyy.splayer_next
+wmclassmatch=1
+```
+
+Niri 窗口规则
+
+> 编者日常不使用 Niri，未经充分测试。如有更好的规则欢迎 PR
+
+```kdl
+window-rule {
+    match app-id="top.imsyy.splayer_next" title="SPlayer-Next - Desktop Lyric"
+    open-floating true
+    default-layer "overlay"
+}
+```
+
+</details>
+
 ## 第三方 / 外部 API 替代
 
 如果在 Wayland 下内置悬浮窗体验不佳，可改用桌面环境原生的**面板 / 挂件类**第三方歌词组件：它们通过 SPlayer-Next 的 [外部 API（HTTP）](/api) 或 [WebSocket API](/socket) 获取当前播放与歌词，再由桌面环境自身负责显示，从而绕开 Electron 悬浮窗在 Wayland 下的限制。
 
 ## 报障信息
 
-如遇问题，请在 Issue 中附上：发行版、桌面环境与合成器、是否启用了原生 Wayland，以及具体的窗口异常现象。
+如遇问题，请在 Issue 中附上：发行版、桌面环境与合成器、本程序是原生 Wayland 还是 Xwayland，以及具体的窗口异常现象。
+
+> [!TIP]
+>
+> 要判断一个窗口是原生 Wayland 还是 Xwayland 主要有以下两种方式
+>
+> - xprop
+>
+>   安装在终端中执行 `xprop`，然后点击对应的窗口。若什么事情都没发生，则该窗口是原生 Wayland；若终端中出现了该窗口的详细信息，则该窗口是 Xwayland
+>
+> - xeyes
+>
+>   安装并打开 `xeyes`，应该会打开一个窗口，上面有 “一双眼睛”。在 Xwayland 窗口中，它的视线会跟随鼠标（一直看向鼠标所在的位置）；在原生 Wayland 窗口中，它保持不动