GitHub Desktop Chinese Localization Plugin

Problem Background

GitHub Desktop is a popular graphical Git client, but it does not officially provide a Chinese language interface. For developers or teams accustomed to a Chinese environment, the English-only UI can hinder familiarity and operational efficiency. Manually modifying the official installation package is complex and error-prone, creating a need for a reliable, reversible method to localize the interface without compromising application stability.

How It Works

This skill automates the localization process through a script, with the following core workflow:

• Automatic Path and Mode Detection:
• The script first detects the operating system (Windows, macOS, or Linux) and automatically locates the GitHub Desktop installation directory.
• It identifies two common resource packaging modes:
  • loose mode: Resource files are stored as loose files in the resources\app directory (e.g., main.js).
  • asar mode: All resources are compressed into a single resources\app.asar file.
• Core Localization Execution:
• Intelligent Dictionary Loading: It uses a built-in Chinese-English dictionary mapping. The dictionary format requires one entry per line and supports version constraints via declarations like # @gh-version: 3.*.
• Hybrid Matching Replacement Strategy: To ensure accuracy, a two-layer matching approach is used:
  1. Literal Match First: It prioritizes exact matches of complete string literals enclosed in identical quotes (e.g., ("Submit") or ('Cancel')), which is the safest mode.
  2. Substring Fallback: For source strings longer than 10 characters containing spaces (typically long UI text), if the literal match fails, it falls back to substring matching. This strategy effectively translates concatenated or dynamically generated text while minimizing the risk of false positives on variable names or comments.
• Safe Replacement Order: The script strictly replaces strings in descending order of source string length. This prevents shorter strings (e.g., "a" or "go") from breaking matches in longer strings (e.g., "a long sentence") if processed first.
• End-to-End Safety and Verification Mechanisms:
• Automatic Backup and Rollback: It backs up target files before modification. The script retains the 5 most recent backups and automatically cleans older ones. During rollback, it also backs up the current file with a .pre_rollback_* suffix, providing a double safeguard.
• Post-Deployment Syntax Check: If node is available in the environment, the script automatically runs node --check on all modified .js files after replacement. It issues warnings if syntax errors are found, preventing application crashes due to improper substitution.
• Clear Process Checkpoints: After each critical step—dependency check, detection, dictionary loading, unpacking, backup, and replacement—the script checks the output and exit code. Upon failure (printing [ERROR] or a non-zero exit code), it immediately aborts and reports the specific reason to the user, such as a missing asar tool or a detection failure requiring manual --src specification.

Caveats and Limitations

• Mode Dependencies: For asar mode, the global installation of @electron/asar (via npm install -g @electron/asar) is mandatory before execution. The script automatically checks for this dependency.
• Customization and Override: While a built-in dictionary is provided, users can add or override translation entries via a custom dictionary file. Note that duplicate entries are automatically deduplicated, and custom dictionaries must follow the format recognized by the script.
• Runtime Environment: It is strongly recommended to completely exit GitHub Desktop before running the localization. Modifying core application files while it is running may lead to unpredictable conflicts or data corruption.
• Inherent Risks of File Modification: Despite backups and syntax checks, directly modifying application files carries inherent risks. It is advisable to first test on a backed-up copy or in a test environment.
• Limitations: This plugin focuses exclusively on replacing UI text strings and cannot handle images, layouts, or more complex internationalization (i18n) issues.