SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsclaude-localize

claude-localize

Office & productivity

View repository

Updated 10-27 17:13

About this skill

Claude Desktop Chinese localization (claude-localize)

Localize the Claude Desktop desktop client installed on this machine into Simplified Chinese, and restore the original English version at any time.

The core idea is adaptivity. Claude Desktop updates very frequently, and tools with hardcoded paths and regexes break on every update. This skill instead usesruntime probing: first read the i18n directory structure, language loading mechanism, and translation coverage of the currently installed version, then decide how to patch. So even if Claude changes its internal structure, you (the Claude running this skill) can assess and adjust on the spot, rather than blindly applying old steps.

Currently implemented:macOS. For Windows see references/windows.md(planned).

How it works (and why it is done this way)

Claude Desktop's interface text is split into two layers:

  1. Frontend UI(Electron rendering layer): the text is in Contents/Resources/ion-dist/i18n/{locale}.json, and the key isa hash of the English source text. At runtime, the corresponding file is loaded dynamically according to the current locale. Because the key is a content hash, as long as the English source text has not changed, the old translation still matches—this makes "built-in carefully proofread translations + translate only new additions" possible.
  2. Desktop/native layer(menus, tray, native dialogs): in Contents/Resources/{locale}.json and {locale}.lproj/Localizable.strings。

There are three keys to localization (details in references/mechanism.md）：

  1. Write the Chinese translations into the locale file that the app actually loads. The locale that actually takes effect is determined by the account/server (when logged into an English account it is often en-US), and the app willwrite it backinto config.json—so merely setting config.locale=zh-CN does not work and will be overwritten. Therefore this skill directlyoverwrites en-US.json(as well as zh-CN.json/zh.json), untranslated keys still fall back to English; the original English is saved as en-US.original.json for restoration and repeated patching.
  2. Claude's developer mode must be enabled(Settings → Developer). Otherwise the app may load the remote claude.ai web version, and the local translation files will not be read at all.
  3. Desktop/native layer: write Contents/Resources/zh-CN.json and .lproj/Localizable.strings。

About the language whitelist (important, once caused a white screen): New versions of Claude still have a "supported locale list" array (["en-US","de-DE",…]), it is just that it moved from index-*.js into a content-hashed chunk(such as assets/v1/ccc72bfa9-*.js). Early on, scanning only index-*.js would miss it and mistakenly conclude that "no JS changes are needed", causing zh-CN to never be registered as a real locale and the localization to rely entirely on overwriting en-US.json to hold it up—once the locale negotiated by a given machine has no corresponding i18n file, it 404s, the rendering layer is never ready → white screen(see references/mechanism.md under "white screen after localization"). Now the skill scans all *.js to find that array and inject zh-CN, and writes i18n files for the entire set of Chinese aliases, with a self-check before swapping in, completely eliminating white screens at the root.

Because modifying files inside the app bundle invalidates the macOS code signature,re-signing is required(macOS 15+ also requires hardened runtime + disabling library validation, otherwise the modified Electron app won't launch). This step is already wrapped by the script.

The deterministic work (backup, merging JSON, injecting the whitelist, re-signing, changing config, verification) is all in scripts/patch_macos.py ;the only thing that requires you (the model) to think is translating the newly added strings。

Pre-flight confirmation

Before starting, briefly confirm with the user:

  • This will modify /Applications/Claude.app，requires entering the system administrator password once(in the apply/restore swap-in step, a native macOS password prompt will appear).
  • will firstfully back upthe original to ~/Library/Application Support/ClaudeCN/backups/, and you can restore restore at any time.
  • After localization, Claude will restart automatically.
  • Enabling developer mode is a prerequisite: first have the user turn on Settings → Developer → Developer Mode inside Claude, otherwise the app loads the remote web version and the local localization won't take effect.

Workflow

Run all commands in the skill directory with python3 scripts/patch_macos.py <子命令> (the script will automatically locate Claude.app; for non-standard paths use --app to specify).

1. Detect

python3 scripts/patch_macos.py detect

Read the JSON output, focusing on:

  • version: the current Claude version.
  • i18n_dir / assets_dir: if it is null, the structure has changed—stop, go read references/mechanism.md for adaptive troubleshooting, don't force it.
  • whitelist.needs_js_patch: whether zh-CN still needs to be injected into the "supported locale list" array.locale_list_files lists the JS files that hit that array (in the current version it's in a chunk, e.g. ccc72bfa9-*.js），scanned_js is the total number scanned.needs_js_patch:true means the array was found and is missing zh-CN, and apply will inject it;false and locale_list_files being non-empty means it already contains zh-CN.
  • coverage: the coverage of the built-in proofread translations for the current version (pct) and the number pending translation (untranslated）。
  • patched: whether it has already been localized.has_backup: whether a backup already exists.

2. Prepare the increment (prepare)

python3 scripts/patch_macos.py prepare

It will write "the newly added keys in the current version that the built-in proofread translations don't yet cover" to .work/untranslated.json(in the form {"哈希key": "English source"}). The output includes untranslated_count。

If untranslated_count is 0, skip step 3 and apply directly.

3. Translate the increment (you do this)

Read .work/untranslated.json, translate each English value into natural, idiomatic Simplified Chinese,keep the keys unchanged, and write the result to .work/delta-zh.json(the same {key: 中文} structure).

Translation requirements (very important, otherwise the UI will break):

  • First read the glossary in assets/glossary.md to ensure terminology is consistent with the existing translations (e.g. the fixed translations for Artifacts, Connectors, Cowork, MCP, etc.).
  • Preserve placeholders and markup：{name}、{count}、%s、{0}, ICU plural syntax {count, plural, ...}, HTML tags <b>...</b>, Markdown, line breaks \n, and the leading/trailing spaces of the original text.
  • Keep sentences concise and in line with Chinese software conventions; use short words for UI buttons/menus (e.g. "Copy"→"复制").
  • When the volume is large, you can translate in batches, or use sub-agents to translate in parallel; but be sure to merge them into one complete delta-zh.json。

After translatingit is strongly recommendedto merge delta-zh.json back into assets/zh-CN.base.json(see "Let the baseline translation grow itself" below), so that next time you run it you won't have to retranslate—especially worthwhile for maintainers.

Want it fast rather than complete? You can skip translation and apply directly: untranslated keys fall back to English, and the coverage rate is the pctreported by detect (depending on how well the current Claude version matches the built-in baseline translation; versions already covered by the baseline can reach ~100%). Letting users see the Chinese interface first and filling in the rest later is also a reasonable choice.

4. Apply

python3 scripts/patch_macos.py apply

It in turn: backs up (if the version has changed it automatically backs up again, and never downgrades) → copies the app to a temporary directory → merges the translations (en-US fallback + refined base + this run's delta) and writes them into the frontend/desktop/statsig → detects and injects the whitelist as needed → re-signs → closes Claude →pops up a password promptswaps the localized version into /Applications → writes locale=zh-CN → restarts Claude.

The output JSON contains ok、coverage_pct、whitelist processing results.

5. Verify and report

  • Look at the apply output ok: true。
  • Have the user confirm that Claude's interface is in Chinese after restarting.This step also incidentally verifies this version's loading mechanism—if it doesn't take effect, go read the "Troubleshooting" section of references/mechanism.md .
  • Give the user a brief Chinese report: version, coverage rate, whether developer mode is needed, and how to restore.

Restore the original English version

The user only needs to say "restore Claude to English / restore the original version" to trigger it; or run directly:

python3 scripts/patch_macos.py restore

Restore from backup (also pops up a password prompt once), clears the locale configuration and restarts Claude. The backup is in ~/Library/Application Support/claude-localize/backups/(the old GUI's ClaudeCN/backups/ is also automatically recognized and reused), independent of the app and not lost with updates; the directory includes 请勿删除_README.txt。

Even if the backup is accidentally deleted it won't get stuck: Claude.app can be freely reinstalled from claude.ai to restore the official original version; and chat history and login are both stored in ~/Library/Application Support/Claude/(separate from the app), so reinstalling won't lose them. When restore can't find a backup, it directly gives this hint instead of erroring out and getting stuck.

Anti-downgrade protection: if the current Claude is no longer in the state localized by this tool, and the backup is an older version (usually meaning Claude has updated itself), restore willabort and prompt, to avoid downgrading Claude. If you really need to go back to the backup version, add --force。

About Claude's automatic updates (important)

Claude Desktop uses Squirrel.Mac for automatic updates, and during updates itverifies the code signature. The localized app is re-signed by us with ad-hoc signing, and the signing identity does not match Anthropic's official one, therefore:

  • During localization, Claude's automatic updates will basically be skipped/fail(the official signature of the update package does not match the current ad-hoc signature). This is safe—Claude just stays on the current version, with no damage and no data loss.
  • Want to upgrade to a new version: first restore back to the official English version → let Claude update automatically → then run the localization once more. The skill is adaptive: it will read the new version's structure, translate the newly added text, and reapply.
  • This is exactly the value of making it a skill: after each Claude update, a single "localize Claude" command can re-adapt it, with no need to wait for the author to manually release a new version.

Let the baseline translation grow on its own (recommended by maintainers)

After translating an increment once, merge it into the built-in baseline, so that coverage increases monotonically and duplicate work is avoided:

python3 - <<'PY'
import json, pathlib
base = pathlib.Path("assets/zh-CN.base.json")
work = pathlib.Path(".work/delta-zh.json")
b = json.loads(base.read_text()); d = json.loads(work.read_text())
b.update(d)
base.write_text(json.dumps(b, ensure_ascii=False, indent=2, sort_keys=True))
print(f"基准从 {len(b)-len(d)} 增长到 {len(b)} 条")
PY

If this skill is also the "translation engine" of the ClaudeCN GUI project, the updated assets/zh-CN.base.json can be fed back into the GUI's translations/zh-CN.json to be repackaged and released.

When the structure changes / an error occurs

Do not rigidly follow the steps.references/mechanism.md records the complete mechanism of Claude Desktop i18n and theadaptive troubleshooting checklist(i18n directory not found, locale file names changed, the whitelist appeared again, unable to start after signing, etc.). Read it first, then use the raw information from detect to judge, and if necessary directly read the index-*.js inside the app for on-the-spot analysis.

Platform

  • macOS: this file + scripts/patch_macos.py。
  • Windows: see references/windows.md(planned—the principle is the same, the differences are in the privilege escalation method takeown/icacls, no re-signing needed, and the locale configuration in %APPDATA%\Claude\config.json）。