maboloshi/github-chinese · error · Error

[GitHub 中文化插件] 词库文件 locals.js 未加载

Error message

[GitHub 中文化插件] 词库文件 locals.js 未加载

What it means

checkI18NLoaded() is a fail-fast startup guard in the userscript. The script body relies on an externally @require'd locals.js that defines the global I18N translation dictionary (see // @require at the top of the .user.js). If that required file did not load before the script body executes, typeof I18N === 'undefined', the script alerts the user and throws, refusing to run with a missing vocabulary rather than partially translating the page.

Source

Thrown at main(nju.edu).user.js:143

        // 当前运行时状态
        pageConfig: null,        // 当前页面配置（null 表示无有效页面）
        currentURL: window.location.href, // 当前页面URL
        transEngine: 'iflyrec',  // 当前翻译引擎
        mutationObserver: null,  // DOM变化观察器
        urlChangeHandler: null,  // 存储URL变化处理器
        dynamicMenus: {},        // 动态菜单ID记录
        initDone: false,
    };

    /* =========================== 安全检查 =========================== */

    /**
     * 检查词库文件是否加载 — 未加载则抛出错误阻止继续执行
     */
    function checkI18NLoaded() {
        if (typeof I18N === 'undefined') {
            alert('GitHub 汉化插件：词库文件 locals.js 未加载，脚本无法运行！');
            throw new Error('[GitHub 中文化插件] 词库文件 locals.js 未加载');
        }
    }

    /**
     * 错误边界 — 包装函数，捕获异常避免阻断页面正常使用
     * @param {Function} fn - 要执行的函数
     * @param {string} label - 错误标签
     * @returns {Function} 包装后的函数
     */
    function safe(fn, label) {
        return function (...args) {
            try {
                return fn.apply(this, args);
            } catch (e) {
                console.error(`[GitHub 中文化插件] ${label} 出错:`, e);
            }
        };
    }

View on GitHub (pinned to 1db777260a)

Solutions

1. Open https://mirror.nju.edu.cn/github-chinese/locals.js in a browser; if it does not return JavaScript, the mirror is down/blocked — switch to the raw.githubusercontent variant (main.user.js) or wait for recovery.
2. In your userscript manager settings enable 'Download @require resources' / remote network access, then force the script to re-fetch resources (edit+save the metadata or reinstall) so locals.js is pulled again.
3. If the mirror is persistently unreachable, download locals.js locally and change the @require to a file:/// path, first enabling the manager's 'allow access to local files' option (see README §local-file require).
4. Reinstall the full script including the // ==UserScript== metadata block so the @require directive is honored.

Example fix

// before
// @require      https://mirror.nju.edu.cn/github-chinese/locals.js
// after — mirror unreachable, point @require at the gh-pages source instead
// @require      https://raw.githubusercontent.com/mabolashi/github-chinese/gh-pages/locals.js?v1.9.4.4

// Run in the same page context, before calling init():
if (typeof I18N === 'undefined' || !I18N || typeof I18N !== 'object') {
    console.error('[github-chinese] locals.js not loaded — aborting init');
    return; // leave the page untranslated instead of throwing
}

function isI18NPresent(v: unknown): v is Record<string, unknown> {
    return typeof v === 'object' && v !== null;
}

try {
    checkI18NLoaded();
    init();
} catch (e) {
    // Fatal guard: log and degrade gracefully rather than crash the page.
    console.warn('[github-chinese] skipped:', e instanceof Error ? e.message : e);
}

When it happens

Trigger: The @require https://mirror.nju.edu.cn/github-chinese/locals.js (line 15) fails to load — the NJU mirror is unreachable, blocked, returns a non-JS error page, or the userscript manager disabled remote @require fetches — so when the IIFE reaches checkI18NLoaded() at line 165 the global I18N is still undefined. Also fires when a user copies only the script body without the metadata header, so the manager never processes the @require directive.

Common situations: Users on networks where mirror.nju.edu.cn is firewalled or rate-limited; the NJU mirror being temporarily down; Tampermonkey/Violentmonkey with 'download @require resources' or network access disabled; installing the script by pasting the body instead of the full metadata block; a manager update that cleared cached @require resources.

Related errors

• [GitHub 中文化插件] 词库文件 locals.js 未加载
• [GitHub 中文化插件] 詞庫文件 locals.js 未加載

AI-assisted analysis of maboloshi/github-chinese@1db777260a (2026-08-13). Data as JSON: /api/errors/0460a41885b84aa3. Report an issue: GitHub.