JSON is the most common format for app data, configuration and translation strings (i18n locale files). A locale file maps keys to strings, as in "menu.file": "文件", and the code finds each string by its key. So the keys must not change, and the structure and formatting should stay as they are, which keeps the converted file easy to compare with the original.
For localisers, this is the zh-CN to zh-TW or zh-HK step. With Taiwan and Convert regional terms, the examples below turn 软件设置 into 軟體設定 and 打印机 into 印表機, while the keys and the number 3 stay the same. Script conversion is not full localisation, though. It handles the characters and the vocabulary in OpenCC’s dictionary, and a reviewer still needs to read the strings in context.
What is converted
- String values, including strings in arrays and nested objects.
- Chinese written as
\uescapes, such as\u70b9\u51fb\u4fdd\u5b58(点击保存, click Save). - Keys (optional, off by default).
What stays the same
- Keys, numbers,
true,false,null, and the structure of objects and arrays. - Indentation and formatting. Strings that change are re-encoded, and every other byte is kept.
Encoding and compatibility
The JSON standard requires UTF-8 for data exchanged between systems, and most tools read JSON as UTF-8 by default. A GBK or Big5 original is detected, and the output is always UTF-8. The BOM follows the original file, so a file without one does not get one.
Conversion examples
| Original | Result |
|---|---|
| {"title": "软件设置"} | {"title": "軟體設定"} |
| {"menu.file": "文件", "menu.help": "帮助"} | {"menu.file": "檔案", "menu.help": "幫助"} |
| {"msg": "内存不足,请关闭后台程序"} | {"msg": "記憶體不足,請關閉後臺程式"} |
| {"count": 3, "enabled": true, "label": "打印机"} | {"count": 3, "enabled": true, "label": "印表機"} |
| {"tip": "\u70b9\u51fb\u4fdd\u5b58"} | {"tip": "點選儲存"} |
Real output from OpenCC (s2twp).
How to use
- Drop locale files such as messages.zh-CN.json onto the page, or click Choose files. Several locale files can be converted at once.
- Choose S→T, then Taiwan or Hong Kong under Standard, and keep Convert regional terms on so that interface wording is replaced with local terms.
- Check the change count and the preview on the card. Invalid JSON gets its own warning.
- Download the file. By default the language code is replaced, so with the Taiwan standard messages.zh-CN.json becomes messages.zh-Hant-TW.json.
Things to check
- Regional terms are replaced from a dictionary, without understanding the meaning. 文件 always becomes 檔案 (file), even where it means an official document, and 点击保存 (click Save) becomes 點選儲存. Have someone who knows local usage read the strings before release.
- Each string value is converted as a whole. A value that holds a Chinese path or URL, such as /分类/软件, is converted too, so watch out for such fields.
- ASCII placeholders such as {name} and %s are never changed; placeholders written in Chinese are converted.
- A file named only zh-CN.json comes out as zh-CN.zh-Hant-TW.json, because the code is only replaced when it follows another part of the name. Rename it to fit your project, for example zh-TW.json.
FAQ
Are keys converted?
Not by default, because code looks strings up by key and a changed key would no longer be found. If your Chinese keys need converting too, turn on “JSON: convert keys too” under Advanced options by format.
Are \u escapes handled?
Yes. Escapes are decoded before converting. A string that changes is written back as plain UTF-8 characters, and a string that does not change keeps its original escapes.
Will the file be reformatted?
No. Indentation, spacing, line breaks and key order stay the same, and unchanged parts are kept byte for byte, so a Git diff shows only the strings that changed.
What about JSON with comments?
Comments and trailing commas are not valid JSON, so the card shows “Not valid JSON; not converted”. You can then click Convert as plain text, but any Chinese in the keys is converted as well.
Which settings should I use for a Hong Kong locale?
Choose S→T, Hong Kong under Standard, and keep Convert regional terms on. OpenCC's Hong Kong vocabulary replaces only a few words. 鼠标 (mouse) becomes 滑鼠, while 软件 (software) becomes 軟件, the form Hong Kong uses.