Skip to content
Get packs

Guide · Agent skill

How to use the Claude Desktop Chinese Localization agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

claude-desktop-zh-localize is an agent skill for maintainers of the claude-desktop-zh-cn project, a local Chinese patch for Claude Desktop. When you share a screenshot with untranslated English and ask the agent to translate it, the skill tells the agent where each text lives, which translation layer to write to, and how to check that the new phrases will actually be translated. This guide explains what the skill does, how to install it, how to trigger it, and which safety warnings to read before running it.

Claude Desktop Chinese Localizationjavaht/claude-desktop-zh-cn · MIT

Quick start

  1. 1Get the ZIP and unzip it. Download the skill ZIP from this page and unzip it. You should end up with a claude-desktop-zh-localize folder containing SKILL.md, scripts/ and references/.
  2. 2Place the folder or upload it. Copy the folder to ~/.claude/skills/ or to a project's .claude/skills/ folder, or upload the ZIP under Settings, Capabilities, Skills.
  3. 3Prepare the requirements. Install Python 3 and Node.js, have a local Claude Desktop at /Applications/Claude.app, and have the claude-desktop-zh-cn repository available.
  4. 4Send a screenshot request. Share the screenshot with the untranslated English and say it is not translated, naming the screen if possible.
  5. 5Review the changes and run the check. Review the translations and regex rules the agent wrote, then run verify_mapping.py with the English strings to confirm all three locales match.

What is an agent skill and what does this one do?

An agent skill is a folder containing a SKILL.md file and optional scripts and reference documents. An AI agent such as Claude loads the skill when a request matches the skill's description, then follows its instructions and can run its scripts.

This skill covers one job: adding missing Chinese text to Claude Desktop's interface inside the claude-desktop-zh-cn project. It supports Simplified Chinese (zh-CN), Traditional Chinese for Taiwan (zh-TW) and Traditional Chinese for Hong Kong (zh-HK). It describes three translation layers: an i18n key-value glossary, a hardcoded text glossary, and dynamic regular expressions for text with numbers, dates or variables.

  • Layer 1: resources/frontend-zh-{zh-CN,zh-TW,zh-HK}.json, for text that uses the app's standard react-intl keys.
  • Layer 2: resources/frontend-hardcoded-zh-*.json, for text in the front-end bundle that is not translated through i18n.
  • Layer 3: the G=[...] array in scripts/patch_claude_zh_cn.py and the matching template in scripts/install_windows.ps1, for dynamic text. Both must be changed together.
  • Verification: scripts/verify_mapping.py checks whether new phrases hit the mapping in all three locales.

How do you install the skill?

Download the skill ZIP from this page and unzip it. Put the resulting claude-desktop-zh-localize folder in one of two places: your user skills folder at ~/.claude/skills/, or the .claude/skills/ folder inside a specific project if you want the skill available only there.

You can also upload the ZIP in the Claude apps. Open Settings, go to Capabilities, then Skills, and add it there.

  • Personal install: ~/.claude/skills/claude-desktop-zh-localize/
  • Project install: <your-project>/.claude/skills/claude-desktop-zh-localize/
  • Claude apps: Settings → Capabilities → Skills → upload the ZIP

How do you trigger the skill with a natural request?

You do not need to name the skill. The description is written for requests like the ones maintainers actually send: a screenshot of Claude Desktop plus a note that some text is still in English. Phrases the skill is written to match include 这些没汉化 (these are not translated) and 帮我汉化一下 (please translate this for me), as well as requests to add Simplified or Traditional Chinese for a new version of the UI.

Give the agent the screenshot and the exact English strings if you can. Naming the screen or the setting (for example, the settings page or the sidebar) helps the agent search the right language file.

  • 这些没汉化，帮我看看 (These are not translated, take a look)
  • 帮我汉化一下设置页面的英文 (Please translate the English on the settings page)
  • 为新版 UI 增加繁体中文翻译 (Add Traditional Chinese translations for the new UI)

What does the agent do step by step?

The skill sets a fixed workflow. The agent first finds the i18n key for each English value by exact match in the installed app's en-US.json file, with a case-insensitive substring search as a fallback. It then writes translations for zh-CN, zh-TW and zh-HK following the glossary in the skill, and writes each translation to both the react-intl files and the hardcoded files. Finally it runs the verification script.

Example of the key lookup the skill uses:

  • Dynamic sentences with numbers or dates must get a regex rule in both the macOS Python engine and the Windows PowerShell template.
  • Hardcoded entries must match straight and curly quotes separately.
  • Source text identical to its translation is dropped silently, so the translation must differ from the English.
import json en = json.load(open("/Applications/Claude.app/Contents/Resources/ion-dist/i18n/en-US.json")) for text in ["Theme", "Chat font"]: print(text, {k for k, v in en.items() if v == text})

How do you check that new translations work?

After adding entries, run the mapping check with the English strings you added. The script reports hits for all three locales and flags obsolete keys. It exits with code 1 if any phrase is not matched. It reads /Applications/Claude.app by default; set CLAUDE_APP=/path/to/Claude.app to point it elsewhere.

To test a regex rule before editing the project, the skill suggests a quick Node check. For a syntax check of the patch scripts, it uses Python's compile step. A full end-to-end dry run is optional and takes about five minutes.

  • Mapping check: python3 skills/claude-desktop-zh-localize/scripts/verify_mapping.py with the English strings as arguments
  • Syntax check: python3 -m py_compile scripts/patch_claude_zh_cn.py scripts/patch_linux_asar.py
  • Optional dry run: python3 scripts/patch_claude_zh_cn.py --user-home "$HOME" --dry-run
node -e 'const G=[[/^Past (\d+) months?$/,"过去 $1 个月"]];for(const s of ["Past 3 months","Past 1 month"]){const m=s.match(G[0][0]);console.log(s,"->",m?G[0][1].replace("$1",m[1]):"NO MATCH")}'

What are the known pitfalls?

The skill lists pitfalls that happened in real maintenance work. The most damaging is a common English word added to the hardcoded glossary. Hardcoded replacement matches every quoted occurrence of that word in the JavaScript, including icon names and data values, so a single word can break pages. The skill says such words must go in the react-intl layer instead.

Other pitfalls cover macOS and Windows engines falling out of sync, text split by links, and login locale resets. The skill also warns that a manual codesign --force --deep --sign - can remove the virtualization entitlement and make the patch fail; use the patch's own resign_app step instead.

  • Never add generic words or data identifiers to the hardcoded glossary.
  • Keep macOS and Windows regex rules in sync.
  • Quit Claude before changing Claude-3p/config.json, because the app rewrites the locale on startup.
  • Do not sign the app manually; use the patch's resign_app.

How do you do the optional visual check?

For a visual check, the skill points to references/computer-use-verification.md. It walks through reinstalling the patch, opening Claude Desktop and capturing each page to compare it with the expected Chinese text. This step needs computer-use access, and the Accessibility and Screen Recording permissions must be granted by the user. The reference says the agent must stop and ask for permission rather than switch to AppleScript or another automation method to get around a denied permission.

  • Use it after adding many entries, or when a user reports that a page is still in English.
  • The user must grant the permissions themselves.

What people use it for

  • Adding Simplified and Traditional Chinese translations for new menus or settings labels in a new Claude Desktop UI version.
  • Drafting consistent zh-CN, zh-TW and zh-HK terms from the built-in glossary, such as session, project and settings.
  • Writing regex rules for dynamic text such as counts and dates, then testing them with the Node snippet before they go into the project.
  • Checking that new phrases are matched by the mapping script before opening a pull request.

Frequently asked questions

Is the claude-desktop-zh-localize skill free to use?

The skill is released under the MIT licence, as stated on this page. The source does not mention prices, so check the project's licence file for the terms that apply to reuse.

What do I need to run this skill?

You need Python 3, Node.js for the regex check snippet, a local install of Claude Desktop at /Applications/Claude.app, and the claude-desktop-zh-cn repository with its patch scripts. Git and GitHub CLI (gh) are needed only if you ask the agent to commit and open a pull request, and computer-use access is needed only for the optional visual check.

Can an ordinary user just get Chinese text in Claude Desktop with this skill?

Not really. The skill is a maintainer workflow that edits the installed app bundle and assumes the project repository. If you only want Chinese text, use the claude-desktop-zh-cn patch itself, and read its warnings first.

Why does the skill say a translation can be silently ignored?

Entries whose source text equals the translation are dropped, so an English word you want to keep needs a real translation instead. The skill's pitfalls list also says long text with braces or line breaks cannot go into the online DOM mapping and needs a regex rule.

Will the skill run commands on my computer without asking?

The skill runs scripts, including the mapping check and the patch scripts that edit the installed app. The skill says it does not commit by default, and only commits when you ask. Read the warnings before running it against a live app, because a wrong hardcoded word can break pages or force a reinstall.

What should I do if a page still shows English after patching?

Check that the key exists in en-US.json and that the translation is in the frontend-zh files, then rerun the patch script, since the skill says changes to resources require a rerun. If the interface falls back to English after a locale change, quit the app, fix the config and start it again. The visual check reference can help locate the page.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you maintain claude-desktop-zh-cn and need to add consistent Chinese translations for new Claude Desktop UI text and verify them before release. Pick something else if you only want Chinese text in the app, since this workflow edits the installed app and needs the project repository and a careful review of each change.

Download the skill