github-chinese: A Userscript That Translates GitHub's Interface, With Trade-Offs

What It Solves and Who It Is For

github-chinese addresses a simple, persistent annoyance: GitHub's interface is English-only, and non-native speakers often lose time hunting for buttons or menu items. The project translates interface elements like menus, titles, buttons, and even relative timestamps into Simplified Chinese. It is aimed at Chinese-speaking developers who prefer to read GitHub in their own language, whether for daily work or for learning. The README also mentions support for Traditional Chinese via a separate readme, so the scope extends beyond just simplified characters. This is not a full localization of page content; it is a UI overlay that changes visible text while leaving code, file names, and repository content untouched. For a developer who knows GitHub well, the value is marginal. For someone new to the platform or less fluent in English, it can remove a real barrier.

The Mechanism: Regex, Per-Page Dictionaries, and Mutation Watching

The script works by injecting a dictionary of Chinese translations and applying them to the DOM. According to the release notes, it uses regex-based matching for text nodes and has evolved to a per-page dictionary model, where different page types (repository, issue, search, etc.) have their own sets of rules. This is more precise than a global find-and-replace, because it avoids translating code blocks or user-generated content. The core loop is a MutationObserver that watches for DOM changes, because GitHub loads content dynamically via AJAX and, more recently, Turbo. The script parses the current URL to determine which page it is on, then applies the relevant translation rules. It also handles Shadow DOM for time elements, which are notoriously hard to reach. The maintainers have split functions like watchUpdate into smaller pieces, and they introduced a safe() error boundary to catch failures in individual translation calls without killing the whole script. This is a pragmatic design: GitHub's frontend changes often, so isolating errors is essential.

Getting It Running: Installation and Local Debugging

Installation is straightforward for a userscript. You need a script manager like Tampermonkey or Violentmonkey for Chrome or Firefox, or Macaque or Stay for Safari. The README provides three sources: a GitHub-hosted development version, a Nanjing University mirror, and a GreasyFork stable version. For Chrome-based browsers, you must enable Developer Mode in the extensions page and allow the script manager to run userscripts. After installing, a page refresh activates the script. For local debugging, the README shows how to modify the @require path to point to a local dictionary file, like file:///D:/github-chinese/locals.js, and it explains the Tampermonkey setting that allows external script access to local files. This is useful for testing changes without waiting for a release. The development version updates its dictionary weekly via GitHub Actions, while the stable version syncs weekly but is described as more stable. That split is a practical way to balance freshness with reliability.

The React Problem: A Constant Compatibility Battle

The most telling part of the project is its changelog. Between 2026-06-16 and 2026-06-20, there were four consecutive patch releases, all labeled as compatibility fixes for GitHub's transition to React. Version 1.9.4.1 notes that GitHub's React change caused the header search box to disappear, and the temporary fix was to ignore the entire header navigation, which meant it could not be translated. Later patches narrowed the ignore scope to restore translations for the search popup and dropdown menus. This is a genuine failure mode: the script is fragile against GitHub's frontend framework changes. The maintainers are responsive, but users on the stable channel may wait days for a fix. The changelog also records a conflict with the Dark Reader extension that broke time display, fixed in v1.8.1. If you use multiple userscripts or extensions that alter GitHub's DOM, expect conflicts. The script is not a passive translation layer; it actively modifies the DOM, so it competes with other tools.

Security and Performance: What the Changelog Reveals

The changelog shows a security fix in version 1.9.4: a translated API response was inserted via innerHTML, which could allow XSS. The fix replaced it with textContent, a safer method. This is a good sign, but it also means the script makes remote requests for translation. The project description mentions machine translation for repository descriptions, which implies external API calls. The README does not specify which service is used, but the changelog references the iFlytek (讯飞) engine. This is a privacy consideration: your repository names and descriptions may be sent to a third-party service. Performance-wise, the maintainers have optimized the code by reducing DOM traversals and caching global rules. The introduction of a MissedTermsManager, which records untranslated terms and allows export, is a clever way to crowdsource dictionary improvements. However, that feature is only visible in developer mode, so normal users do not see it. The script's size and regex complexity may add noticeable overhead on heavy pages, but the changelog suggests ongoing efforts to minimize that.

Maintenance and Upgrade Cost

The project is under active maintenance, with a clear versioning scheme: a major.minor.patch plus a date suffix that represents the dictionary release. The dictionary is updated automatically by GitHub Actions on a schedule. This means you get new translations without manual intervention, but it also means the script can change behavior without your consent. The stable channel is designed to be safer, but it still requires updating the userscript itself when GitHub breaks something. The license is GPL-3.0, a copyleft license that allows personal use but imposes obligations if you redistribute modified versions. The README includes a warning that the project has never been published to GitCode, so users should verify they are downloading from official sources. There is also a vscode-extension directory, suggesting support for VS Code's integrated browser, but the README points to a separate readme for details. Overall, the maintenance cost is low for end users, but the project's survival depends on the maintainer's willingness to keep patching GitHub's changes. If GitHub makes a radical change to its DOM, the script could break entirely, and there is no guarantee of a fix.

Alternatives and a Final Verdict

The main alternative is the built-in translation features of browsers, such as Chrome's automatic translation, or dedicated extensions like Google Translate. These tools translate the entire page, including code blocks, which is often undesirable. They also do not handle dynamically loaded content as well, and they can interfere with GitHub's layout. The closest open-source predecessor is 52cik/github-hans, which this project is based on. The difference is that github-chinese uses per-page dictionaries and regex, which gives finer control and avoids translating code. However, that precision comes at the cost of constant maintenance. For a user who wants a one-time fix, this is not it. For a user who is willing to follow updates and occasionally report issues, it is a functional solution. The project's own changelog is the best documentation of its fragility. Before adopting it, check the latest release notes to see if there are known issues with your browser or GitHub's current layout. If you are comfortable with that uncertainty, install the stable version from GreasyFork and keep an eye on the issues page.

Editorial conclusion

Adopt github-chinese if you are a Chinese-speaking GitHub user who wants a free, community-maintained UI translation and can tolerate occasional breakage after GitHub updates. Do not adopt it if you need guaranteed stability or if you rely on the original English labels for technical precision. Before installing, verify that your browser's userscript manager supports the required APIs (GM_addStyle and onurlchange) and check the latest release notes for known issues with the current GitHub layout. The project is actively patched, but the dependency on GitHub's DOM means you must be ready to update or switch to the stable channel when issues arise.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository