告别繁琐操作！GitHub 中文化插件快捷键控制翻译全攻略

2026-02-05 05:20:33作者：柯茵沙

你是否曾在使用 GitHub 时，因频繁切换翻译状态而感到效率低下？是否希望通过简单的键盘操作就能掌控翻译功能的开关？本文将带你深入了解如何为 GitHub 中文化插件添加自定义快捷键控制，让你的开发体验更加流畅高效。

读完本文后，你将能够：

理解 GitHub 中文化插件的工作原理
掌握添加自定义快捷键的方法
学会修改和扩展翻译功能
解决常见的快捷键冲突问题

插件工作原理概述

GitHub 中文化插件（main.user.js）通过监听页面变化并应用翻译规则，将 GitHub 界面转换为中文。其核心功能包括：

页面类型检测：通过 URL 和页面元素识别当前页面类型（仓库、个人资料等）
翻译规则应用：根据页面类型应用对应的静态翻译和正则翻译规则
动态内容监听：使用 MutationObserver 监控页面变化并实时翻译
功能开关控制：通过菜单命令启用/禁用正则翻译和描述翻译功能

核心代码结构

插件的主要逻辑集中在 main.user.js 中，关键函数包括：

init(): 初始化插件，设置事件监听和菜单
traverseNode(): 遍历 DOM 节点并应用翻译
transText(): 执行文本翻译
registerMenuCommand(): 注册用户菜单命令

翻译规则存储在 locals.js 中，包含静态翻译词条和正则表达式翻译规则。

快捷键功能设计与实现

要添加快捷键控制，我们需要实现以下功能：

快捷键事件监听
翻译状态切换逻辑
用户反馈机制

步骤 1：定义快捷键配置

首先，在配置区域添加快捷键设置：

// ==UserScript==
// @name         GitHub 中文化插件
// @namespace    https://github.com/maboloshi/github-chinese
// @description  中文化 GitHub 界面的部分菜单及内容
// @version      1.9.3-2025-10-17
// @author       沙漠之子
// @license      GPL-3.0
// @match        https://github.com/*
// @grant        GM_registerMenuCommand
// @grant        GM_setValue
// @grant        GM_getValue
// @grant        GM_notification
// ==/UserScript==

(function() {
    'use strict';
    
    // 全局配置区（添加快捷键设置）
    const CONFIG = {
        // ... 现有配置 ...
        shortcuts: {
            toggleTranslation: {
                key: 't',
                altKey: true,
                ctrlKey: true,
                description: "切换翻译功能 (Ctrl+Alt+T)"
            }
        }
    };
    
    const FeatureSet = {
        enable_RegExp: GM_getValue("enable_RegExp", true),
        enable_transDesc: GM_getValue("enable_transDesc", true),
        enable_translation: GM_getValue("enable_translation", true) // 新增翻译总开关
    };
    
    // ... 其余代码 ...
})();

步骤 2：实现快捷键监听函数

添加一个处理键盘事件的函数，用于检测快捷键组合：

function handleKeyboardShortcuts(e) {
    // 忽略输入框中的按键
    if (['INPUT', 'TEXTAREA', 'SELECT'].includes(e.target.tagName)) {
        return;
    }
    
    // 检查是否按下了翻译切换快捷键 (Ctrl+Alt+T)
    if (e.ctrlKey && e.altKey && e.key.toLowerCase() === CONFIG.shortcuts.toggleTranslation.key) {
        e.preventDefault();
        toggleTranslation();
    }
}

function toggleTranslation() {
    FeatureSet.enable_translation = !FeatureSet.enable_translation;
    GM_setValue("enable_translation", FeatureSet.enable_translation);
    
    // 立即应用更改
    if (FeatureSet.enable_translation) {
        traverseNode(document.body); // 开启翻译，重新翻译整个页面
    } else {
        location.reload(); // 关闭翻译，刷新页面恢复原状
    }
    
    GM_notification(`翻译功能已${FeatureSet.enable_translation ? '开启' : '关闭'}`);
}

步骤 3：注册快捷键事件监听

在初始化函数中添加事件监听器：

function init() {
    // ... 现有初始化代码 ...
    
    // 注册快捷键事件
    document.addEventListener('keydown', handleKeyboardShortcuts);
    
    // 检查翻译功能状态
    if (!FeatureSet.enable_translation) {
        console.log("翻译功能当前处于关闭状态");
    }
    
    // ... 其余初始化代码 ...
}

步骤 4：修改翻译函数添加开关控制

修改 traverseNode 函数，添加翻译总开关控制：

function traverseNode(rootNode) {
    // 如果翻译功能已关闭，直接返回
    if (!FeatureSet.enable_translation) return;
    
    const start = performance.now();
    
    // ... 其余代码保持不变 ...
}

步骤 5：添加菜单选项

在 registerMenuCommand 函数中添加快捷键说明：

function registerMenuCommand() {
    const createMenuCommand = (config) => {
        // ... 现有代码 ...
    };
    
    const menuConfigs = [
        {
            label: "翻译功能",
            key: "enable_translation",
            callback: newFeatureState => {
                if (newFeatureState) {
                    traverseNode(document.body);
                } else {
                    // 这里可以选择重新加载页面或恢复原始文本
                    GM_notification("翻译功能已关闭，请刷新页面生效");
                }
            }
        },
        // ... 现有菜单项 ...
        {
            label: `快捷键: ${CONFIG.shortcuts.toggleTranslation.description}`,
            key: "shortcut_info",
            callback: null // 仅作为信息展示，无切换功能
        }
    ];
    
    menuConfigs.forEach(config => createMenuCommand(config));
}

功能测试与冲突解决

添加快捷键功能后，需要进行充分测试以确保稳定性和兼容性：

测试步骤

基本功能测试：
- 安装修改后的脚本 main.user.js
- 按下 Ctrl+Alt+T，确认翻译功能能正常开关
- 检查菜单中"翻译功能"选项状态是否同步更新
冲突测试：
- 在不同页面（仓库、issues、PR等）测试快捷键
- 在文本输入框中测试快捷键是否被正确忽略
- 与浏览器默认快捷键对比，确保无冲突
性能测试：
- 监控页面加载时间变化
- 检查控制台是否有错误或警告

常见问题解决

快捷键不生效：
- 检查是否有其他扩展占用了相同快捷键
- 确认浏览器设置中未禁用用户脚本的键盘事件
翻译状态不同步：
- 清除浏览器缓存和 GM_setValue 存储的数据
- 检查 GM_setValue 和 GM_getValue 调用是否正确
页面刷新问题：
- 如果不需要完全刷新，可以实现更复杂的恢复机制
- 修改 toggleTranslation 函数，实现不刷新页面恢复英文

高级自定义选项

自定义快捷键组合

用户可以根据个人习惯修改快捷键组合，例如改为 Alt+T：

shortcuts: {
    toggleTranslation: {
        key: 't',
        altKey: true,
        ctrlKey: false,  // 将ctrlKey设为false
        description: "切换翻译功能 (Alt+T)"
    }
}

添加更多快捷键功能

可以扩展快捷键功能，例如添加仅翻译描述的快捷键：

// 添加新的快捷键配置
shortcuts: {
    // ... 现有配置 ...
    translateDescription: {
        key: 'd',
        altKey: true,
        ctrlKey: true,
        description: "翻译描述 (Ctrl+Alt+D)"
    }
}

// 在handleKeyboardShortcuts中添加
if (e.ctrlKey && e.altKey && e.key.toLowerCase() === CONFIG.shortcuts.translateDescription.key) {
    e.preventDefault();
    if (FeatureSet.enable_transDesc && CONFIG.DESC_SELECTORS[pageConfig.currentPageType]) {
        transDesc(CONFIG.DESC_SELECTORS[pageConfig.currentPageType]);
        GM_notification("已尝试翻译描述内容");
    } else {
        GM_notification("描述翻译功能未启用");
    }
}