From 2bb5a4605a8b71526ef1c49c8c9fe682bab5934e Mon Sep 17 00:00:00 2001 From: Glavo Date: Mon, 13 Oct 2025 21:47:45 +0800 Subject: [PATCH 01/10] update --- docs/Localization_zh.md | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/docs/Localization_zh.md b/docs/Localization_zh.md index 1df59934623..3e6009606c8 100644 --- a/docs/Localization_zh.md +++ b/docs/Localization_zh.md @@ -1,7 +1,5 @@ # 本地化 - - HMCL 为多种语言提供本地化支持。 本文档介绍了 HMCL 对这些语言的支持状态，并给想要为 HMCL 的本地化工作做出贡献的贡献者提供了一份指南。 @@ -13,7 +11,7 @@ HMCL 为多种语言提供本地化支持。 | 语言 | 语言标签 | 首选本地化键 | 首选本地化文件后缀 | [游戏语言文件](https://minecraft.wiki/w/Language) | 支持状态 | 志愿者 | |---------|-----------|-----------|------------|---------------------------------------------|--------|-------------------------------------------| | 英语 | `en` | `default` | (空) | `en_us` | **主要** | [Glavo](https://github.com/Glavo) | -| 英语 (颠倒) | `en-Qabs` | `en-Qabs` | `en_Qabs` | `en_ud` | 自动 | | +| 英语 (颠倒) | `en-Qabs` | `en-Qabs` | `en_Qabs` | `en_ud` | 自动生成 | | | 中文 (简体) | `zh-Hans` | `zh` | `_zh` | `zh_cn` | **主要** | [Glavo](https://github.com/Glavo) | | 中文 (繁体) | `zh-Hant` | `zh-Hant` | `_zh_Hant` | `zh_tw`
`zh_hk` | **主要** | [Glavo](https://github.com/Glavo) | | 中文 (文言) | `lzh` | `lzh` | `_lzh` | `lzh` | 次要 | | @@ -25,21 +23,22 @@ HMCL 为多种语言提供本地化支持。
关于语言标签 -HMCL 使用符合 IETF BCP 47 规范的语言标签。 +HMCL 使用符合 IETF BCP 47 规范的语言标签。此外，我们在选择语言标签时遵循以下原则: + +* 对于 ISO 639 标准中定义的语言，如果同时存在两字母语言代码和三字母语言代码，那么应当优先选择两字母语言代码。 -对于 ISO 639 标准中定义的语言，如果同时存在两字母语言代码和三字母语言代码，那么应当优先选择两字母语言代码。 + 例如，对于英语，我们使用 `en` 而不是 `eng` 作为语言代码。 -例如，对于英语，我们使用 `en` 而不是 `eng` 作为语言代码。 +* 对于 Minecraft 所定义的非标准语言，应当优先使用语言文件的 `language.code` 中定义的代码，而非游戏语言文件的名称 + (但对于存在两字母代码的语言，应当将三字母语言代码替换为对应的两字母语言代码)。 -对于 Minecraft 所定义的非标准语言，应当优先使用语言文件的 `language.code` 中定义的代码，而非游戏语言文件的名称 -(但对于存在两字母代码的语言，应当将三字母语言代码替换为对应的两字母语言代码)。 -这是因为 Minecraft 有时候会用现实中实际存在的国家/地区代码来表示虚构语言 (比如说海盗英语的语言文件为 `en_pt`，但 `PT` 其实是葡萄牙的国家代码)。 + 这是因为 Minecraft 有时候会用现实中实际存在的国家/地区代码来表示虚构语言 (比如说海盗英语的语言文件为 `en_pt`，但 `PT` 其实是葡萄牙的国家代码)。 -例如，对于颠倒的英语，我们使用 `en-Qabs` 作为语言代码，而不是 `en-UD`。 + 例如，对于颠倒的英语，我们使用 `en-Qabs` 作为语言代码，而不是 `en-UD`。 -此外，语言代码中应当尽可能选择地区中立的语言标签。 +* 此外，语言代码中应当尽可能选择地区中立的语言标签。 -例如，对于简体中文和繁体中文，我们使用 `zh-Hans`和 `zh-Hant` 作为语言代码，而不是 `zh-CN` 和 `zh-TW`。 + 例如，对于简体中文和繁体中文，我们使用 `zh-Hans`和 `zh-Hant` 作为语言代码，而不是 `zh-CN` 和 `zh-TW`。
From bd3927ee2169179cb5f0ff3061356180cd6a380e Mon Sep 17 00:00:00 2001 From: Glavo Date: Mon, 13 Oct 2025 22:03:17 +0800 Subject: [PATCH 02/10] =?UTF-8?q?=E5=B0=86=20Localization.md=20=E7=BF=BB?= =?UTF-8?q?=E8=AF=91=E8=87=B3=E8=8B=B1=E8=AF=AD?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/Localization.md | 252 ++++++++++++++++++++++++++++++++++++++++ docs/Localization_zh.md | 5 + 2 files changed, 257 insertions(+) create mode 100644 docs/Localization.md diff --git a/docs/Localization.md b/docs/Localization.md new file mode 100644 index 00000000000..91787910ebf --- /dev/null +++ b/docs/Localization.md @@ -0,0 +1,252 @@ +# Localization + + +**English** | [中文](Localization_zh.md) + + +HMCL provides localization support for multiple languages. + +This document describes the status of language support in HMCL and provides a guide for contributors who want to help with localization. + +| Language | Language Tag | Preferred Localization Key | Preferred Localization File Suffix | [Game Language File](https://minecraft.wiki/w/Language) | Support Status | Volunteers | +|-----------------------|--------------|----------------------------|------------------------------------|---------------------------------------------------------|----------------|-------------------------------------------| +| English | `en` | `default` | (empty) | `en_us` | **Primary** | [Glavo](https://github.com/Glavo) | +| English (Upside Down) | `en-Qabs` | `en-Qabs` | `en_Qabs` | `en_ud` | Auto | | +| Chinese (Simplified) | `zh-Hans` | `zh` | `_zh` | `zh_cn` | **Primary** | [Glavo](https://github.com/Glavo) | +| Chinese (Traditional) | `zh-Hant` | `zh-Hant` | `_zh_Hant` | `zh_tw`
`zh_hk` | **Primary** | [Glavo](https://github.com/Glavo) | +| Chinese (Classical) | `lzh` | `lzh` | `_lzh` | `lzh` | Secondary | | +| Japanese | `ja` | `ja` | `_ja` | `ja_jp` | Secondary | | +| Spanish | `es` | `es` | `_es` | `es_es` | Secondary | [3gf8jv4dv](https://github.com/3gf8jv4dv) | +| Russian | `ru` | `ru` | `_ru` | `ru_ru` | Secondary | [3gf8jv4dv](https://github.com/3gf8jv4dv) | +| Ukrainian | `uk` | `uk` | `_uk` | `uk_ua` | Secondary | | + +
+About Language Tags + +HMCL uses language tags that conform to the IETF BCP 47 standard. In addition, we follow these principles when choosing language tags: + +* For languages defined in the ISO 639 standard, if both two-letter and three-letter language codes exist, the two-letter code should be preferred. + + For example, for English, we use `en` instead of `eng` as the language code. + +* For non-standard languages defined by Minecraft, the code defined in the language file's `language.code` should be preferred over the game language file name + (but for languages with a two-letter code, the three-letter code should be replaced with the corresponding two-letter code). + + This is because Minecraft sometimes uses real-world country/region codes to represent fictional languages (for example, Pirate English uses the language file `en_pt`, but `PT` is actually the country code for Portugal). + + For example, for Upside Down English, we use `en-Qabs` as the language code instead of `en-UD`. + +* In addition, language tags should be as region-neutral as possible. + + For example, for Simplified Chinese and Traditional Chinese, we use `zh-Hans` and `zh-Hant` as language codes, instead of `zh-CN` and `zh-TW`. + +
+ +
+About Localization Keys and File Suffixes + +Localization file suffixes and keys are used to name [localization resources](#localization-resources). + +Generally, the localization key is the language code corresponding to the localization resource, and the localization file suffix is obtained by replacing `-` in the language code with `_` and adding a leading underscore. + +As a special case, for the default resource, the localization key is `default` and the localization file suffix is empty. + +Due to the existence of the [resource fallback mechanism](#resource-fallback-mechanism), if there is no resource that exactly matches the current language environment, HMCL will derive a search list based on the current language tag and search for resources in order according to this list. + +We recommend always providing the default resource (with the `default` localization key and an empty file suffix) when providing localization resources, to ensure that all users can load resources properly. + +We also recommend using broader language tags for localization resources whenever possible, so that users are less likely to fall back to the default resource. + +For example, if you provide a Simplified Chinese localization resource, we recommend using `zh` as the localization key instead of the more specific `zh-Hans`, so that it applies to all Chinese users and avoids falling back to the default resource for them. + +If you want to provide both Simplified and Traditional Chinese resources, it is recommended to use the broader `zh` as the localization key for the resource with a higher user share, making it the default Chinese resource, and use the more specific `zh-Hans`/`zh-Hant` as the localization key for the resource with a lower user share. + +
+ +HMCL requires all Pull Requests that update documentation or localization resources to also update the resources for all **primary** supported languages. +If the PR author is not familiar with the relevant languages, they can request translations in the comments, +and maintainers will help translate these texts before merging the PR. + +For **secondary** supported languages, we cannot guarantee that these localization resources will always be updated in sync. +We need collaborators who are proficient in these languages to help us maintain them. + +We record volunteers who are willing to help maintain these language localization resources in the documentation. +If contributors wish to have newly added localized texts translated into these languages in a timely manner, +they can @ these volunteers in the PR to seek help. + +If you are willing to help us maintain localization resources for certain languages, please open a PR +and add your GitHub username to the volunteer list above. +We greatly appreciate your help. + +## Adding Support for New Languages + +HMCL welcomes anyone to participate in translation and contribution. However, maintaining translations for more languages requires additional maintenance effort, so we have some requirements for newly added languages. +Please confirm the following requirements before contributing: + +- We prioritize [languages officially supported by Minecraft](https://minecraft.wiki/w/Language). + Unless there are special reasons, we will not support languages that are not officially supported by Minecraft. +- We hope to provide long-term maintenance support for all languages. + Since the maintainers of this project are proficient in only a limited number of languages, to avoid new language support becoming outdated due to lack of maintainers, + we hope to find people proficient in the language to help us maintain the newly added localization files in the long term. + If there may be a lack of long-term maintainers, we will be more cautious about whether to add support for that language. + +We recommend that contributors submit a [feature request Issue](https://github.com/HMCL-dev/HMCL/issues/new?template=feature.yml) before providing a new language translation, +discuss with other contributors first, and determine the future maintenance plan before starting the translation work. + +### Getting Started with Translation + +If you want to add support for a new language in HMCL, start by translating [`I18N.properties`](../HMCL/src/main/resources/assets/lang/I18N.properties). +The vast majority of HMCL's texts are in this file; translating it will localize the entire interface. + +This is a Java Properties file, which is very simple in format. +Before translating, please read the introduction to this format: [Properties file](https://en.wikipedia.org/wiki/.properties). + +As the first step, look up the two-letter or three-letter language tag for your language from [this table](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes). +For example, the language tag for English is `en`. + +After determining the language tag, create a file named `I18N_.properties` (e.g., `I18N_en.properties`) next to the [`I18N.properties` file](../HMCL/src/main/resources/assets/lang). +You can then start translating in this file. + +The `I18N.properties` file follows the [resource fallback mechanism](#resource-fallback-mechanism) to look up missing translations. +This means you can translate entry by entry, and any untranslated entries will automatically fall back to English. + +After translating part of the file, you can [build HMCL yourself](./README_zh.md#编译), and your translations will be included in the compiled HMCL. +If your computer's default environment is not this language, you can set the environment variable `HMCL_LANGUAGE` to the language tag you just found, +and HMCL will automatically switch to that language. + +At this point, you can push the file to GitHub and submit a PR to HMCL. +The maintainers will handle the remaining steps for you. + +## Localization Resources + +All documentation and localization resource files follow the naming rule `.`. + +For example, for `README.md`, the localized versions for different languages are named as follows: + +- English: `README.md` +- Chinese (Simplified): `README_zh.md` +- Chinese (Traditional): `README_zh_Hant.md` +- Chinese (Classical): `README_lzh.md` + +```json5 +{ + "<本地化键 1>": "<本地化文本 1>", + "<本地化键 2>": "<本地化文本 2>", + // ... + "<本地化键 N>": "<本地化文本 N>" +} +``` + +For example, for the following text field: + +```json +{ + "meow": "Meow" +} +``` + +it can be rewritten as a localized text: + +```json +{ + "meow": { + "default": "Meow", + "zh": "喵呜", + "zh-Hant": "喵嗚" + } +} +``` + +## Resource Fallback Mechanism + +For missing resources in a certain language, HMCL supports a resource fallback mechanism, which derives a search list based on different language tags and searches for resources in order according to this list. + +For example, if the current environment's language tag is `en-US`, HMCL will search for the corresponding localized resources in the following order: + +1. `en-US` +2. `en` +3. `und` + +For resources that can be merged (such as `.properties` files), HMCL will merge resources according to the priority of this list; for resources that are difficult to merge (such as font files), HMCL will load the highest-priority resource found in this list. + +If the current language uses a three-letter ISO 639 code, but a corresponding two-letter code also exists, HMCL will map it to the two-letter code before searching for resources. + +For example, if the current environment's language tag is `eng-US`, HMCL will map it to `en-US` and then search for localized resources according to the above rules. + +If the current language is a sublanguage of an [ISO 639 macrolanguage](https://en.wikipedia.org/wiki/ISO_639_macrolanguage), HMCL will also search for resources corresponding to the macrolanguage. + +### Additional Rules for Chinese + +For Chinese (and its sub-language tags, such as Classical Chinese (`lzh`), Mandarin (`cmn`), Cantonese (`yue`), etc.), HMCL provides additional support. + +If the current environment's language is Chinese (or its sub-languages) and the script is not specified, HMCL will infer the default script based on the language and region tags. + +For the language `lzh` or regions `TW`, `HK`, or `MO`, the default script is Traditional Chinese (`Hant`); +for other languages and regions, the default script is Simplified Chinese (`Hans`). + +In addition, HMCL will add `zh-CN` to the search list for all Chinese environments, and add `zh-TW` to the search list for all Traditional Chinese environments, +to cover more scenarios. + +Below are the localization resource search lists for several common Chinese environments. + +- `zh-CN`: + 1. `zh-Hans-CN` + 2. `zh-Hans` + 3. `zh-CN` + 4. `zh` + 5. `und` +- `zh-SG`: + 1. `zh-Hans-SG` + 2. `zh-Hans` + 3. `zh-SG` + 4. `zh-CN` + 5. `zh` + 6. `und` +- `zh-TW`: + 1. `zh-Hant-TW` + 2. `zh-Hant` + 3. `zh-TW` + 4. `zh` + 5. `zh-CN` + 6. `und` +- `zh-HK`: + 1. `zh-Hant-HK` + 2. `zh-Hant` + 3. `zh-HK` + 4. `zh-TW` + 5. `zh` + 6. `zh-CN` + 7. `und` +- `lzh`: + 1. `lzh-Hant` + 2. `lzh` + 3. `zh-Hant` + 4. `zh` + 5. `und` + +## Automatic Synchronization of Documentation Content + +To simplify documentation maintenance, HMCL uses a macro mechanism to automatically maintain parts of the documentation content. Run the following command in the terminal + +```bash +./gradlew updateDocuments +``` + +This will automatically update all documentation content. + +For example, to create links for switching between different language versions of the same document, add the following content under the document title: + +```markdown + +[English](Localization.md) | **中文** + +``` + +After running `./gradlew updateDocuments`, these two lines will be automatically replaced with language switcher links like this: + +```markdown +**English** | +中文 ([简体](README_zh.md), [繁體](README_zh.md), [文言](README_zh.md)) | [日本語](README_zh.md) | [español](README_zh.md) | [русский](README_zh.md) | [українська](README_zh.md) +``` + +For more about macros, see [MacroProcessor.java](../buildSrc/src/main/java/org/jackhuang/hmcl/gradle/docs/MacroProcessor.java). diff --git a/docs/Localization_zh.md b/docs/Localization_zh.md index 3e6009606c8..7e6dba62f21 100644 --- a/docs/Localization_zh.md +++ b/docs/Localization_zh.md @@ -1,5 +1,9 @@ # 本地化 + +[English](Localization.md) | **中文** + + HMCL 为多种语言提供本地化支持。 本文档介绍了 HMCL 对这些语言的支持状态，并给想要为 HMCL 的本地化工作做出贡献的贡献者提供了一份指南。 @@ -246,6 +250,7 @@ HMCL 的维护者会替你完成其他步骤。 ```markdown +[English](Localization.md) | **中文** ``` From 0d5cc2eafc2618bfc0656a110d42a1859a62128f Mon Sep 17 00:00:00 2001 From: Glavo Date: Mon, 13 Oct 2025 22:06:17 +0800 Subject: [PATCH 03/10] update --- docs/Localization.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/Localization.md b/docs/Localization.md index 91787910ebf..cd34bfedcf4 100644 --- a/docs/Localization.md +++ b/docs/Localization.md @@ -130,10 +130,10 @@ For example, for `README.md`, the localized versions for different languages are ```json5 { - "<本地化键 1>": "<本地化文本 1>", - "<本地化键 2>": "<本地化文本 2>", + "": "", + "": "", // ... - "<本地化键 N>": "<本地化文本 N>" + "": "" } ``` From 5a145aec2b61386754fe45cd9cbef96b62ccb686 Mon Sep 17 00:00:00 2001 From: Glavo Date: Mon, 13 Oct 2025 22:08:55 +0800 Subject: [PATCH 04/10] update --- docs/Localization.md | 5 ++--- docs/Localization_zh.md | 3 +-- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/Localization.md b/docs/Localization.md index cd34bfedcf4..0a5e39dac0d 100644 --- a/docs/Localization.md +++ b/docs/Localization.md @@ -110,7 +110,7 @@ You can then start translating in this file. The `I18N.properties` file follows the [resource fallback mechanism](#resource-fallback-mechanism) to look up missing translations. This means you can translate entry by entry, and any untranslated entries will automatically fall back to English. -After translating part of the file, you can [build HMCL yourself](./README_zh.md#编译), and your translations will be included in the compiled HMCL. +After translating part of the file, you can [build HMCL yourself](./README.md#compilation), and your translations will be included in the compiled HMCL. If your computer's default environment is not this language, you can set the environment variable `HMCL_LANGUAGE` to the language tag you just found, and HMCL will automatically switch to that language. @@ -245,8 +245,7 @@ For example, to create links for switching between different language versions o After running `./gradlew updateDocuments`, these two lines will be automatically replaced with language switcher links like this: ```markdown -**English** | -中文 ([简体](README_zh.md), [繁體](README_zh.md), [文言](README_zh.md)) | [日本語](README_zh.md) | [español](README_zh.md) | [русский](README_zh.md) | [українська](README_zh.md) +**English** (**Standard**, [uʍoᗡ ǝpᴉsd∩](README_en_Qabs.md)) | 中文 ([简体](README_zh.md), [繁體](README_zh_Hant.md), [文言](README_lzh.md)) | [日本語](README_ja.md) | [español](README_es.md) | [русский](README_ru.md) | [українська](README_uk.md) ``` For more about macros, see [MacroProcessor.java](../buildSrc/src/main/java/org/jackhuang/hmcl/gradle/docs/MacroProcessor.java). diff --git a/docs/Localization_zh.md b/docs/Localization_zh.md index 7e6dba62f21..c731325d513 100644 --- a/docs/Localization_zh.md +++ b/docs/Localization_zh.md @@ -257,8 +257,7 @@ HMCL 的维护者会替你完成其他步骤。 随后执行 `./gradlew updateDocuments`，这两行内容会被自动替换为类似这样的跳转链接: ```markdown -**English** | -中文 ([简体](README_zh.md), [繁體](README_zh.md), [文言](README_zh.md)) | [日本語](README_zh.md) | [español](README_zh.md) | [русский](README_zh.md) | [українська](README_zh.md) +**English** (**Standard**, [uʍoᗡ ǝpᴉsd∩](README_en_Qabs.md)) | 中文 ([简体](README_zh.md), [繁體](README_zh_Hant.md), [文言](README_lzh.md)) | [日本語](README_ja.md) | [español](README_es.md) | [русский](README_ru.md) | [українська](README_uk.md) ``` 关于宏的更多内容，请见 [MacroProcessor.java](../buildSrc/src/main/java/org/jackhuang/hmcl/gradle/docs/MacroProcessor.java)。 From 322bb9a349dabdfd0af8fb801d992165dfa3c002 Mon Sep 17 00:00:00 2001 From: Glavo Date: Mon, 13 Oct 2025 22:10:29 +0800 Subject: [PATCH 05/10] update --- docs/Localization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Localization.md b/docs/Localization.md index 0a5e39dac0d..f0d4ec4d7a4 100644 --- a/docs/Localization.md +++ b/docs/Localization.md @@ -11,7 +11,7 @@ This document describes the status of language support in HMCL and provides a gu | Language | Language Tag | Preferred Localization Key | Preferred Localization File Suffix | [Game Language File](https://minecraft.wiki/w/Language) | Support Status | Volunteers | |-----------------------|--------------|----------------------------|------------------------------------|---------------------------------------------------------|----------------|-------------------------------------------| | English | `en` | `default` | (empty) | `en_us` | **Primary** | [Glavo](https://github.com/Glavo) | -| English (Upside Down) | `en-Qabs` | `en-Qabs` | `en_Qabs` | `en_ud` | Auto | | +| English (Upside Down) | `en-Qabs` | `en-Qabs` | `en_Qabs` | `en_ud` | Auto-Generated | | | Chinese (Simplified) | `zh-Hans` | `zh` | `_zh` | `zh_cn` | **Primary** | [Glavo](https://github.com/Glavo) | | Chinese (Traditional) | `zh-Hant` | `zh-Hant` | `_zh_Hant` | `zh_tw`
`zh_hk` | **Primary** | [Glavo](https://github.com/Glavo) | | Chinese (Classical) | `lzh` | `lzh` | `_lzh` | `lzh` | Secondary | | From 72eba701a847c4196c941de3c164f30a20bf7d50 Mon Sep 17 00:00:00 2001 From: Glavo Date: Thu, 23 Oct 2025 20:43:15 +0800 Subject: [PATCH 06/10] update --- docs/Localization.md | 246 ++++++++++++++++++++++++---------------- docs/Localization_zh.md | 8 +- 2 files changed, 156 insertions(+), 98 deletions(-) diff --git a/docs/Localization.md b/docs/Localization.md index f0d4ec4d7a4..6f08d4cb2e9 100644 --- a/docs/Localization.md +++ b/docs/Localization.md @@ -3,42 +3,42 @@ **English** | [中文](Localization_zh.md) - HMCL provides localization support for multiple languages. -This document describes the status of language support in HMCL and provides a guide for contributors who want to help with localization. +This document describes HMCL's support status for these languages and provides a guide for contributors who want to help with HMCL localization. + +## Supported languages + +Currently, HMCL supports the following languages: -| Language | Language Tag | Preferred Localization Key | Preferred Localization File Suffix | [Game Language File](https://minecraft.wiki/w/Language) | Support Status | Volunteers | -|-----------------------|--------------|----------------------------|------------------------------------|---------------------------------------------------------|----------------|-------------------------------------------| -| English | `en` | `default` | (empty) | `en_us` | **Primary** | [Glavo](https://github.com/Glavo) | -| English (Upside Down) | `en-Qabs` | `en-Qabs` | `en_Qabs` | `en_ud` | Auto-Generated | | -| Chinese (Simplified) | `zh-Hans` | `zh` | `_zh` | `zh_cn` | **Primary** | [Glavo](https://github.com/Glavo) | -| Chinese (Traditional) | `zh-Hant` | `zh-Hant` | `_zh_Hant` | `zh_tw`
`zh_hk` | **Primary** | [Glavo](https://github.com/Glavo) | -| Chinese (Classical) | `lzh` | `lzh` | `_lzh` | `lzh` | Secondary | | -| Japanese | `ja` | `ja` | `_ja` | `ja_jp` | Secondary | | -| Spanish | `es` | `es` | `_es` | `es_es` | Secondary | [3gf8jv4dv](https://github.com/3gf8jv4dv) | -| Russian | `ru` | `ru` | `_ru` | `ru_ru` | Secondary | [3gf8jv4dv](https://github.com/3gf8jv4dv) | -| Ukrainian | `uk` | `uk` | `_uk` | `uk_ua` | Secondary | | +| Language | Language Tag | Preferred Localization Key | Preferred Localization File Suffix | [Game Language Files](https://minecraft.wiki/w/Language) | Support Status | Volunteers | +|-----------------------|--------------|----------------------------|------------------------------------|----------------------------------------------------------|----------------|-------------------------------------------| +| English | `en` | `default` | (empty) | `en_us` | **Primary** | [Glavo](https://github.com/Glavo) | +| English (Upside-down) | `en-Qabs` | `en-Qabs` | `en_Qabs` | `en_ud` | Automatic | | +| Chinese (Simplified) | `zh-Hans` | `zh` | `_zh` | `zh_cn` | **Primary** | [Glavo](https://github.com/Glavo) | +| Chinese (Traditional) | `zh-Hant` | `zh-Hant` | `_zh_Hant` | `zh_tw`
`zh_hk` | **Primary** | [Glavo](https://github.com/Glavo) | +| Classical Chinese | `lzh` | `lzh` | `_lzh` | `lzh` | Secondary | | +| Japanese | `ja` | `ja` | `_ja` | `ja_jp` | Secondary | | +| Spanish | `es` | `es` | `_es` | `es_es` | Secondary | [3gf8jv4dv](https://github.com/3gf8jv4dv) | +| Russian | `ru` | `ru` | `_ru` | `ru_ru` | Secondary | [3gf8jv4dv](https://github.com/3gf8jv4dv) | +| Ukrainian | `uk` | `uk` | `_uk` | `uk_ua` | Secondary | |
About Language Tags -HMCL uses language tags that conform to the IETF BCP 47 standard. In addition, we follow these principles when choosing language tags: +HMCL uses language tags that conform to the IETF BCP 47 standard. -* For languages defined in the ISO 639 standard, if both two-letter and three-letter language codes exist, the two-letter code should be preferred. +When choosing language tags, we follow these principles: - For example, for English, we use `en` instead of `eng` as the language code. +1. For languages defined in the ISO 639 standard, if a tag has already been registered in the [IANA Language Subtag Registry](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry), we always use the registered tag. -* For non-standard languages defined by Minecraft, the code defined in the language file's `language.code` should be preferred over the game language file name - (but for languages with a two-letter code, the three-letter code should be replaced with the corresponding two-letter code). + For example, for English, we use `en` instead of `eng` as the language code. - This is because Minecraft sometimes uses real-world country/region codes to represent fictional languages (for example, Pirate English uses the language file `en_pt`, but `PT` is actually the country code for Portugal). +2. For non-standard languages defined by Minecraft, the code defined in the language file's `language.code` should be preferred over the game language file's name. - For example, for Upside Down English, we use `en-Qabs` as the language code instead of `en-UD`. + This is because Minecraft sometimes uses real-world country/region codes to represent fictional languages (for example, Pirate English uses the language file `en_pt`, but `PT` is actually the country code for Portugal). -* In addition, language tags should be as region-neutral as possible. - - For example, for Simplified Chinese and Traditional Chinese, we use `zh-Hans` and `zh-Hant` as language codes, instead of `zh-CN` and `zh-TW`. + For example, for Upside-down English, we use `en-Qabs` as the language code instead of `en-UD`.
@@ -47,86 +47,92 @@ HMCL uses language tags that conform to the IETF BCP 47 standard. In addition, w Localization file suffixes and keys are used to name [localization resources](#localization-resources). -Generally, the localization key is the language code corresponding to the localization resource, and the localization file suffix is obtained by replacing `-` in the language code with `_` and adding a leading underscore. +Generally, the localization key is the language code for the resource, and the localization file suffix is obtained by replacing `-` with `_` in the language code and adding a leading underscore. -As a special case, for the default resource, the localization key is `default` and the localization file suffix is empty. +As a special case, for default resources, the localization key is `default` and the file suffix is empty. -Due to the existence of the [resource fallback mechanism](#resource-fallback-mechanism), if there is no resource that exactly matches the current language environment, HMCL will derive a search list based on the current language tag and search for resources in order according to this list. +Due to the existence of the [resource fallback mechanism](#resource-fallback-mechanism), +if there is no resource that exactly matches the current locale, HMCL will derive a search list from the current language tag and search for resources in order. -We recommend always providing the default resource (with the `default` localization key and an empty file suffix) when providing localization resources, to ensure that all users can load resources properly. +We recommend always providing a default resource (with the `default` key and empty file suffix) when providing localization resources, +to ensure all users can load resources properly. -We also recommend using broader language tags for localization resources whenever possible, so that users are less likely to fall back to the default resource. +We also recommend using broader language tags for localization resources whenever possible, so users are less likely to fall back to the default resource. -For example, if you provide a Simplified Chinese localization resource, we recommend using `zh` as the localization key instead of the more specific `zh-Hans`, so that it applies to all Chinese users and avoids falling back to the default resource for them. +For example, if you provide a Simplified Chinese localization resource, we recommend using `zh` as the localization key instead of the more specific `zh-Hans`, +so it will apply to all Chinese users and avoid falling back to the default resource for them. -If you want to provide both Simplified and Traditional Chinese resources, it is recommended to use the broader `zh` as the localization key for the resource with a higher user share, making it the default Chinese resource, and use the more specific `zh-Hans`/`zh-Hant` as the localization key for the resource with a lower user share. +If you want to provide both Simplified and Traditional Chinese resources, it is recommended to use the broader `zh` as the key for the resource with more users (as the default Chinese resource), +and use the more specific `zh-Hans`/`zh-Hant` as the key for the resource with fewer users. -HMCL requires all Pull Requests that update documentation or localization resources to also update the resources for all **primary** supported languages. -If the PR author is not familiar with the relevant languages, they can request translations in the comments, +HMCL requires all pull requests that update documentation and localization resources to also update the resources for all **primary** supported languages. +If the PR author is not familiar with the relevant languages, they can request translation help in the comments, and maintainers will help translate these texts before merging the PR. For **secondary** supported languages, we cannot guarantee that these localization resources will always be updated in sync. -We need collaborators who are proficient in these languages to help us maintain them. +We need collaborators who are proficient in these languages to help with maintenance. -We record volunteers who are willing to help maintain these language localization resources in the documentation. -If contributors wish to have newly added localized texts translated into these languages in a timely manner, -they can @ these volunteers in the PR to seek help. +We will record volunteers willing to help maintain these language resources in the documentation. +If contributors want to have new localization texts translated into these languages in a timely manner, +they can @ these volunteers in the PR for help. -If you are willing to help us maintain localization resources for certain languages, please open a PR +If you are willing to help maintain localization resources for any language, please open a PR and add your GitHub username to the volunteer list above. We greatly appreciate your help. -## Adding Support for New Languages +## Adding Support for a New Language -HMCL welcomes anyone to participate in translation and contribution. However, maintaining translations for more languages requires additional maintenance effort, so we have some requirements for newly added languages. +HMCL welcomes anyone to participate in translation and contribution. However, maintaining translations for more languages requires more maintenance effort, so we have some requirements for newly added languages. Please confirm the following requirements before contributing: - We prioritize [languages officially supported by Minecraft](https://minecraft.wiki/w/Language). - Unless there are special reasons, we will not support languages that are not officially supported by Minecraft. + Unless there are special reasons, we do not provide support for languages not yet supported by Minecraft. - We hope to provide long-term maintenance support for all languages. - Since the maintainers of this project are proficient in only a limited number of languages, to avoid new language support becoming outdated due to lack of maintainers, + Since the maintainers of this project are proficient in only a limited number of languages, to avoid support for new languages quickly becoming outdated due to lack of maintainers, we hope to find people proficient in the language to help us maintain the newly added localization files in the long term. - If there may be a lack of long-term maintainers, we will be more cautious about whether to add support for that language. + If there may be a lack of long-term maintainers, we will be more cautious about adding support for that language. -We recommend that contributors submit a [feature request Issue](https://github.com/HMCL-dev/HMCL/issues/new?template=feature.yml) before providing a new language translation, +We recommend that contributors submit a [feature request](https://github.com/HMCL-dev/HMCL/issues/new?template=feature.yml) before providing a new language translation, discuss with other contributors first, and determine the future maintenance plan before starting the translation work. ### Getting Started with Translation -If you want to add support for a new language in HMCL, start by translating [`I18N.properties`](../HMCL/src/main/resources/assets/lang/I18N.properties). -The vast majority of HMCL's texts are in this file; translating it will localize the entire interface. +If you want to add support for a new language to HMCL, please start by translating [`I18N.properties`](../HMCL/src/main/resources/assets/lang/I18N.properties). +The vast majority of HMCL's texts are in this file, and translating it will translate the entire interface. This is a Java Properties file, which is very simple in format. Before translating, please read the introduction to this format: [Properties file](https://en.wikipedia.org/wiki/.properties). -As the first step, look up the two-letter or three-letter language tag for your language from [this table](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes). +As the first step of translation, please look up the two- or three-letter language tag for your language in [this table](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry). For example, the language tag for English is `en`. -After determining the language tag, create a file named `I18N_.properties` (e.g., `I18N_en.properties`) next to the [`I18N.properties` file](../HMCL/src/main/resources/assets/lang). -You can then start translating in this file. +After determining the language tag, please create a file named `I18N_.properties` (e.g., `I18N_en.properties`) next to the [`I18N.properties` file](../HMCL/src/main/resources/assets/lang). +Then you can start translating in this file. -The `I18N.properties` file follows the [resource fallback mechanism](#resource-fallback-mechanism) to look up missing translations. -This means you can translate entry by entry, and any untranslated entries will automatically fall back to English. +The `I18N.properties` file follows the [resource fallback mechanism](#资源回退机制) to look up missing translations. +That is, you can translate entry by entry, and any untranslated entries will automatically fall back to English. -After translating part of the file, you can [build HMCL yourself](./README.md#compilation), and your translations will be included in the compiled HMCL. -If your computer's default environment is not this language, you can set the environment variable `HMCL_LANGUAGE` to the language tag you just found, +After translating part of the file, you can [build HMCL yourself](./README_zh.md#编译), and your translations will be included in the compiled HMCL. +If your computer's default environment is not the target language, you can set the environment variable `HMCL_LANGUAGE` to the language tag you just found from the table, and HMCL will automatically switch to that language. At this point, you can push the file to GitHub and submit a PR to HMCL. -The maintainers will handle the remaining steps for you. +The maintainers of HMCL will complete the remaining steps for you. ## Localization Resources All documentation and localization resource files follow the naming rule `.`. -For example, for `README.md`, the localized versions for different languages are named as follows: +For example, for `README.md`, the localized versions in different languages are named as follows: - English: `README.md` - Chinese (Simplified): `README_zh.md` - Chinese (Traditional): `README_zh_Hant.md` -- Chinese (Classical): `README_lzh.md` +- Classical Chinese: `README_lzh.md` + +In addition to localized files, HMCL also supports localizing certain text fields in JSON. Localized text in JSON uses the following format: ```json5 { @@ -145,7 +151,7 @@ For example, for the following text field: } ``` -it can be rewritten as a localized text: +It can be rewritten as localized text: ```json { @@ -161,47 +167,91 @@ it can be rewritten as a localized text: For missing resources in a certain language, HMCL supports a resource fallback mechanism, which derives a search list based on different language tags and searches for resources in order according to this list. -For example, if the current environment's language tag is `en-US`, HMCL will search for the corresponding localized resources in the following order: +Before searching, we first refine the language tag through the following steps. -1. `en-US` -2. `en` -3. `und` +1. Normalize Language Codes -For resources that can be merged (such as `.properties` files), HMCL will merge resources according to the priority of this list; for resources that are difficult to merge (such as font files), HMCL will load the highest-priority resource found in this list. + If the language code subtag in the current language tag is not registered in the IANA Language Subtag Registry, HMCL will try to map it to a registered tag. -If the current language uses a three-letter ISO 639 code, but a corresponding two-letter code also exists, HMCL will map it to the two-letter code before searching for resources. + For example, HMCL will replace the language code `eng` with `en`. -For example, if the current environment's language tag is `eng-US`, HMCL will map it to `en-US` and then search for localized resources according to the above rules. +2. Map Macrolanguages to Individual Languages -If the current language is a sublanguage of an [ISO 639 macrolanguage](https://en.wikipedia.org/wiki/ISO_639_macrolanguage), HMCL will also search for resources corresponding to the macrolanguage. + If the current language code is an [ISO 639 macrolanguage](https://en.wikipedia.org/wiki/ISO_639_macrolanguage), and the macrolanguage usually refers to a specific individual language, HMCL will replace it with that individual language. -### Additional Rules for Chinese + For example, `zh` (Chinese) usually actually refers to `cmn` (Mandarin), so we replace the language code `zh` with `cmn`. + +3. Derive Script + + If the current language tag does not specify a script, HMCL will try to derive the script according to the following rules in order: + + 1. If the current language tag specifies a variant, and the variant is registered in the IANA Language Subtag Registry, and all its `Prefix` entries in the registry contain the same script, then set the current script to that script. -For Chinese (and its sub-language tags, such as Classical Chinese (`lzh`), Mandarin (`cmn`), Cantonese (`yue`), etc.), HMCL provides additional support. + For example, if the current variant is `pinyin` (Chinese Pinyin), the script will be set to `Latn` (Latin). -If the current environment's language is Chinese (or its sub-languages) and the script is not specified, HMCL will infer the default script based on the language and region tags. + 2. If the current language code is assigned a `Suppress-Script` in the IANA Language Subtag Registry, set the current script to that script. -For the language `lzh` or regions `TW`, `HK`, or `MO`, the default script is Traditional Chinese (`Hant`); -for other languages and regions, the default script is Simplified Chinese (`Hans`). + For example, if the current language code is `en` (English), the script will be set to `Latn` (Latin); if the code is `ru` (Russian), the script will be set to `Cyrl` (Cyrillic). + + 3. If the current language code is `lzh` (Classical Chinese), set the script to `Hant` (Traditional Chinese). + + 4. If the current language code is `zh` or a sublanguage of `zh`, check if the current region code is one of `TW`, `HK`, or `MO`. If true, set the script to `Hant` (Traditional Chinese); otherwise, set it to `Hans` (Simplified Chinese). + +After refining the language code, HMCL will derive a list of language tags based on this language tag. + +For example, for the language tag `en-US`, HMCL will refine it to `en-Latn-US` and derive the following search list: + +1. `en-Latn-US` +2. `en-Latn` +3. `en-US` +4. `en` +5. `und` + +For the language tag `zh-CN`, HMCL will refine it to `cmn-Hans-CN` and derive the following search list: + +1. `cmn-Hans-CN` +2. `cmn-Hans` +3. `cmn-CN` +4. `cmn` +5. `zh-Hans-CN` +6. `zh-Hans` +7. `zh-CN` +8. `zh` +9. `und` + +For resources that can be merged (such as `.properties` files), HMCL will merge resources according to the priority of this list; for resources that are difficult to merge (such as font files), HMCL will load the highest-priority resource found in this list. -In addition, HMCL will add `zh-CN` to the search list for all Chinese environments, and add `zh-TW` to the search list for all Traditional Chinese environments, -to cover more scenarios. +If the current language uses a three-letter ISO 639 code, but there is also a corresponding two-letter code, HMCL will map it to the two-letter code before searching for resources. + +For example, if the current environment's language tag is `eng-US`, HMCL will map it to `en-US` and then search for localization resources according to the above rules. + +### Additional Rules for Chinese + +HMCL always adds `zh-CN` to the search list for all Chinese environments, and adds `zh-TW` to the search list for all Traditional Chinese environments. Below are the localization resource search lists for several common Chinese environments. - `zh-CN`: - 1. `zh-Hans-CN` - 2. `zh-Hans` - 3. `zh-CN` - 4. `zh` - 5. `und` + 1. `cmn-Hans-CN` + 2. `cmn-Hans` + 3. `cmn-CN` + 4. `cmn` + 5. `zh-Hans-CN` + 6. `zh-Hans` + 7. `zh-CN` + 8. `zh` + 9. `und` - `zh-SG`: - 1. `zh-Hans-SG` - 2. `zh-Hans` - 3. `zh-SG` - 4. `zh-CN` - 5. `zh` - 6. `und` + 1. `cmn-Hans-SG` + 2. `cmn-Hans` + 3. `cmn-SG` + 4. `cmn` + 5. `zh-Hans-SG` + 6. `zh-Hans` + 7. `zh-SG` + 8. `zh-CN` + 9. `zh` + 10. `und` - `zh-TW`: 1. `zh-Hant-TW` 2. `zh-Hant` @@ -210,23 +260,29 @@ Below are the localization resource search lists for several common Chinese envi 5. `zh-CN` 6. `und` - `zh-HK`: - 1. `zh-Hant-HK` - 2. `zh-Hant` - 3. `zh-HK` - 4. `zh-TW` - 5. `zh` - 6. `zh-CN` - 7. `und` + 1. `cmn-Hant-HK` + 2. `cmn-Hant` + 3. `cmn-HK` + 4. `cmn` + 5. `zh-Hant-HK` + 6. `zh-Hant` + 7. `zh-HK` + 8. `zh-TW` + 9. `zh` + 10. `zh-CN` + 11. `und` - `lzh`: 1. `lzh-Hant` 2. `lzh` 3. `zh-Hant` - 4. `zh` - 5. `und` + 4. `zh-TW` + 5. `zh` + 6. `zh-CN` + 7. `und` ## Automatic Synchronization of Documentation Content -To simplify documentation maintenance, HMCL uses a macro mechanism to automatically maintain parts of the documentation content. Run the following command in the terminal +To simplify documentation maintenance, HMCL uses a macro mechanism to automatically maintain parts of the documentation content. Run the following command in the terminal: ```bash ./gradlew updateDocuments @@ -238,14 +294,14 @@ For example, to create links for switching between different language versions o ```markdown -[English](Localization.md) | **中文** +**English** | [中文](Localization_zh.md) ``` -After running `./gradlew updateDocuments`, these two lines will be automatically replaced with language switcher links like this: +After running `./gradlew updateDocuments`, these two lines will be automatically replaced with language switcher links like the following: ```markdown **English** (**Standard**, [uʍoᗡ ǝpᴉsd∩](README_en_Qabs.md)) | 中文 ([简体](README_zh.md), [繁體](README_zh_Hant.md), [文言](README_lzh.md)) | [日本語](README_ja.md) | [español](README_es.md) | [русский](README_ru.md) | [українська](README_uk.md) ``` -For more about macros, see [MacroProcessor.java](../buildSrc/src/main/java/org/jackhuang/hmcl/gradle/docs/MacroProcessor.java). +For more about macros, see [MacroProcessor.java](../buildSrc/src/main/java/org/jackhuang/hmcl/gradle/docs/MacroProcessor.java). \ No newline at end of file diff --git a/docs/Localization_zh.md b/docs/Localization_zh.md index f57d23c854e..8ae062a3749 100644 --- a/docs/Localization_zh.md +++ b/docs/Localization_zh.md @@ -1,6 +1,8 @@ # 本地化 - + +[English](Localization.md) | **中文** + HMCL 为多种语言提供本地化支持。 @@ -299,14 +301,14 @@ HMCL 总是会将 `zh-CN` 加入所有中文环境的搜索列表中，将 `zh-T ```markdown +[English](Localization.md) | **中文** ``` 随后执行 `./gradlew updateDocuments`，这两行内容会被自动替换为类似这样的跳转链接: ```markdown -**English** | -中文 ([简体](README_zh.md), [繁體](README_zh.md), [文言](README_zh.md)) | [日本語](README_zh.md) | [español](README_zh.md) | [русский](README_zh.md) | [українська](README_zh.md) +**English** (**Standard**, [uʍoᗡ ǝpᴉsd∩](README_en_Qabs.md)) | 中文 ([简体](README_zh.md), [繁體](README_zh_Hant.md), [文言](README_lzh.md)) | [日本語](README_ja.md) | [español](README_es.md) | [русский](README_ru.md) | [українська](README_uk.md) ``` 关于宏的更多内容，请见 [MacroProcessor.java](../buildSrc/src/main/java/org/jackhuang/hmcl/gradle/docs/MacroProcessor.java)。 From 9225005a1e8304fc21cacedc13758f6078f750aa Mon Sep 17 00:00:00 2001 From: Glavo Date: Thu, 23 Oct 2025 20:57:55 +0800 Subject: [PATCH 07/10] update --- docs/Localization.md | 36 ++++++++++++++++++++++++------------ docs/Localization_zh.md | 3 +++ 2 files changed, 27 insertions(+), 12 deletions(-) diff --git a/docs/Localization.md b/docs/Localization.md index 6f08d4cb2e9..9218e91978a 100644 --- a/docs/Localization.md +++ b/docs/Localization.md @@ -3,6 +3,7 @@ **English** | [中文](Localization_zh.md) + HMCL provides localization support for multiple languages. This document describes HMCL's support status for these languages and provides a guide for contributors who want to help with HMCL localization. @@ -14,10 +15,10 @@ Currently, HMCL supports the following languages: | Language | Language Tag | Preferred Localization Key | Preferred Localization File Suffix | [Game Language Files](https://minecraft.wiki/w/Language) | Support Status | Volunteers | |-----------------------|--------------|----------------------------|------------------------------------|----------------------------------------------------------|----------------|-------------------------------------------| | English | `en` | `default` | (empty) | `en_us` | **Primary** | [Glavo](https://github.com/Glavo) | -| English (Upside-down) | `en-Qabs` | `en-Qabs` | `en_Qabs` | `en_ud` | Automatic | | +| English (Upside Down) | `en-Qabs` | `en-Qabs` | `en_Qabs` | `en_ud` | Automatic | | | Chinese (Simplified) | `zh-Hans` | `zh` | `_zh` | `zh_cn` | **Primary** | [Glavo](https://github.com/Glavo) | | Chinese (Traditional) | `zh-Hant` | `zh-Hant` | `_zh_Hant` | `zh_tw`
`zh_hk` | **Primary** | [Glavo](https://github.com/Glavo) | -| Classical Chinese | `lzh` | `lzh` | `_lzh` | `lzh` | Secondary | | +| Chinese (Classical) | `lzh` | `lzh` | `_lzh` | `lzh` | Secondary | | | Japanese | `ja` | `ja` | `_ja` | `ja_jp` | Secondary | | | Spanish | `es` | `es` | `_es` | `es_es` | Secondary | [3gf8jv4dv](https://github.com/3gf8jv4dv) | | Russian | `ru` | `ru` | `_ru` | `ru_ru` | Secondary | [3gf8jv4dv](https://github.com/3gf8jv4dv) | @@ -30,15 +31,17 @@ HMCL uses language tags that conform to the IETF BCP 47 standard. When choosing language tags, we follow these principles: -1. For languages defined in the ISO 639 standard, if a tag has already been registered in the [IANA Language Subtag Registry](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry), we always use the registered tag. +1. For languages defined in the ISO 639 standard, if a tag has already been registered in the [IANA Language Subtag Registry](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry), + we always use the registered tag. For example, for English, we use `en` instead of `eng` as the language code. 2. For non-standard languages defined by Minecraft, the code defined in the language file's `language.code` should be preferred over the game language file's name. - This is because Minecraft sometimes uses real-world country/region codes to represent fictional languages (for example, Pirate English uses the language file `en_pt`, but `PT` is actually the country code for Portugal). + This is because Minecraft sometimes uses real-world country/region codes to represent joke languages + (for example, Pirate English uses the language file `en_pt`, but `PT` is actually the country code for Portugal). - For example, for Upside-down English, we use `en-Qabs` as the language code instead of `en-UD`. + For example, for Upside down English, we use `en-Qabs` as the language code instead of `en-UD`. @@ -52,22 +55,27 @@ Generally, the localization key is the language code for the resource, and the l As a special case, for default resources, the localization key is `default` and the file suffix is empty. Due to the existence of the [resource fallback mechanism](#resource-fallback-mechanism), -if there is no resource that exactly matches the current locale, HMCL will derive a search list from the current language tag and search for resources in order. +if there is no resource that exactly matches the current locale, +HMCL will derive a search list from the current language tag and search for resources in order. We recommend always providing a default resource (with the `default` key and empty file suffix) when providing localization resources, to ensure all users can load resources properly. -We also recommend using broader language tags for localization resources whenever possible, so users are less likely to fall back to the default resource. +We also recommend using broader language tags for localization resources whenever possible, +so users are less likely to fall back to the default resource. -For example, if you provide a Simplified Chinese localization resource, we recommend using `zh` as the localization key instead of the more specific `zh-Hans`, +For example, if you provide a Simplified Chinese localization resource, +we recommend using `zh` as the localization key instead of the more specific `zh-Hans`, so it will apply to all Chinese users and avoid falling back to the default resource for them. -If you want to provide both Simplified and Traditional Chinese resources, it is recommended to use the broader `zh` as the key for the resource with more users (as the default Chinese resource), +If you want to provide both Simplified and Traditional Chinese resources, +it is recommended to use the broader `zh` as the key for the resource with more users (as the default Chinese resource), and use the more specific `zh-Hans`/`zh-Hant` as the key for the resource with fewer users. -HMCL requires all pull requests that update documentation and localization resources to also update the resources for all **primary** supported languages. +HMCL requires all pull requests that update documentation and localization resources to also update the resources +for all **primary** supported languages. If the PR author is not familiar with the relevant languages, they can request translation help in the comments, and maintainers will help translate these texts before merging the PR. @@ -84,7 +92,8 @@ We greatly appreciate your help. ## Adding Support for a New Language -HMCL welcomes anyone to participate in translation and contribution. However, maintaining translations for more languages requires more maintenance effort, so we have some requirements for newly added languages. +HMCL welcomes anyone to participate in translation and contribution. +However, maintaining translations for more languages requires more maintenance effort, so we have some requirements for newly added languages. Please confirm the following requirements before contributing: - We prioritize [languages officially supported by Minecraft](https://minecraft.wiki/w/Language). @@ -282,6 +291,8 @@ Below are the localization resource search lists for several common Chinese envi ## Automatic Synchronization of Documentation Content + + To simplify documentation maintenance, HMCL uses a macro mechanism to automatically maintain parts of the documentation content. Run the following command in the terminal: ```bash @@ -304,4 +315,5 @@ After running `./gradlew updateDocuments`, these two lines will be automatically **English** (**Standard**, [uʍoᗡ ǝpᴉsd∩](README_en_Qabs.md)) | 中文 ([简体](README_zh.md), [繁體](README_zh_Hant.md), [文言](README_lzh.md)) | [日本語](README_ja.md) | [español](README_es.md) | [русский](README_ru.md) | [українська](README_uk.md) ``` -For more about macros, see [MacroProcessor.java](../buildSrc/src/main/java/org/jackhuang/hmcl/gradle/docs/MacroProcessor.java). \ No newline at end of file +For more about macros, see [MacroProcessor.java](../buildSrc/src/main/java/org/jackhuang/hmcl/gradle/docs/MacroProcessor.java). + \ No newline at end of file diff --git a/docs/Localization_zh.md b/docs/Localization_zh.md index 8ae062a3749..d11bfcf722f 100644 --- a/docs/Localization_zh.md +++ b/docs/Localization_zh.md @@ -289,6 +289,8 @@ HMCL 总是会将 `zh-CN` 加入所有中文环境的搜索列表中，将 `zh-T ## 自动同步文档内容 + + 为了简化文档的维护，HMCL 使用了一套宏机制自动维护文档的部分内容。在命令行中执行 ```bash @@ -312,3 +314,4 @@ HMCL 总是会将 `zh-CN` 加入所有中文环境的搜索列表中，将 `zh-T ``` 关于宏的更多内容，请见 [MacroProcessor.java](../buildSrc/src/main/java/org/jackhuang/hmcl/gradle/docs/MacroProcessor.java)。 + \ No newline at end of file From 4505e8a6ee39eb310223f38ff61f147b72d20611 Mon Sep 17 00:00:00 2001 From: Glavo Date: Thu, 23 Oct 2025 21:24:57 +0800 Subject: [PATCH 08/10] update --- docs/Localization.md | 58 +++++++++++++++++++++++++++-------------- docs/Localization_zh.md | 3 +-- 2 files changed, 39 insertions(+), 22 deletions(-) diff --git a/docs/Localization.md b/docs/Localization.md index 9218e91978a..6a2dc09d423 100644 --- a/docs/Localization.md +++ b/docs/Localization.md @@ -97,9 +97,12 @@ However, maintaining translations for more languages requires more maintenance e Please confirm the following requirements before contributing: - We prioritize [languages officially supported by Minecraft](https://minecraft.wiki/w/Language). + Unless there are special reasons, we do not provide support for languages not yet supported by Minecraft. - We hope to provide long-term maintenance support for all languages. - Since the maintainers of this project are proficient in only a limited number of languages, to avoid support for new languages quickly becoming outdated due to lack of maintainers, + + Since the maintainers of this project are proficient in only a limited number of languages, + to avoid support for new languages quickly becoming outdated due to lack of maintainers, we hope to find people proficient in the language to help us maintain the newly added localization files in the long term. If there may be a lack of long-term maintainers, we will be more cautious about adding support for that language. @@ -117,14 +120,16 @@ Before translating, please read the introduction to this format: [Properties fil As the first step of translation, please look up the two- or three-letter language tag for your language in [this table](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry). For example, the language tag for English is `en`. -After determining the language tag, please create a file named `I18N_.properties` (e.g., `I18N_en.properties`) next to the [`I18N.properties` file](../HMCL/src/main/resources/assets/lang). +After determining the language tag, please create a file named `I18N_.properties` (e.g., `I18N_en.properties`) next to the [`I18N.properties` file](../HMCL/src/main/resources/assets/lang). Then you can start translating in this file. -The `I18N.properties` file follows the [resource fallback mechanism](#资源回退机制) to look up missing translations. +The `I18N.properties` file follows the [resource fallback mechanism](#resource-fallback-mechanism) to look up missing translations. That is, you can translate entry by entry, and any untranslated entries will automatically fall back to English. -After translating part of the file, you can [build HMCL yourself](./README_zh.md#编译), and your translations will be included in the compiled HMCL. -If your computer's default environment is not the target language, you can set the environment variable `HMCL_LANGUAGE` to the language tag you just found from the table, +After translating part of the file, you can [build HMCL yourself](./README.md#compilation), +and your translations will be included in the compiled HMCL. +If your computer's default environment is not the target language, +you can set the environment variable `HMCL_LANGUAGE` to the language tag you just found from the table, and HMCL will automatically switch to that language. At this point, you can push the file to GitHub and submit a PR to HMCL. @@ -139,7 +144,7 @@ For example, for `README.md`, the localized versions in different languages are - English: `README.md` - Chinese (Simplified): `README_zh.md` - Chinese (Traditional): `README_zh_Hant.md` -- Classical Chinese: `README_lzh.md` +- Chinese (Classical): `README_lzh.md` In addition to localized files, HMCL also supports localizing certain text fields in JSON. Localized text in JSON uses the following format: @@ -174,19 +179,22 @@ It can be rewritten as localized text: ## Resource Fallback Mechanism -For missing resources in a certain language, HMCL supports a resource fallback mechanism, which derives a search list based on different language tags and searches for resources in order according to this list. +For missing resources in a certain language, HMCL supports a resource fallback mechanism, +which derives a search list based on different language tags and searches for resources in order according to this list. Before searching, we first refine the language tag through the following steps. 1. Normalize Language Codes - If the language code subtag in the current language tag is not registered in the IANA Language Subtag Registry, HMCL will try to map it to a registered tag. + If the language code subtag in the current language tag is not registered in the IANA Language Subtag Registry, + HMCL will try to map it to a registered tag. For example, HMCL will replace the language code `eng` with `en`. 2. Map Macrolanguages to Individual Languages - If the current language code is an [ISO 639 macrolanguage](https://en.wikipedia.org/wiki/ISO_639_macrolanguage), and the macrolanguage usually refers to a specific individual language, HMCL will replace it with that individual language. + If the current language code is an [ISO 639 macrolanguage](https://en.wikipedia.org/wiki/ISO_639_macrolanguage), + and the macrolanguage usually refers to a specific individual language, HMCL will replace it with that individual language. For example, `zh` (Chinese) usually actually refers to `cmn` (Mandarin), so we replace the language code `zh` with `cmn`. @@ -194,17 +202,21 @@ Before searching, we first refine the language tag through the following steps. If the current language tag does not specify a script, HMCL will try to derive the script according to the following rules in order: - 1. If the current language tag specifies a variant, and the variant is registered in the IANA Language Subtag Registry, and all its `Prefix` entries in the registry contain the same script, then set the current script to that script. + 1. If the current language tag specifies a variant, and the variant is registered in the IANA Language Subtag Registry, + and all its `Prefix` entries in the registry contain the same script, then set the current script to that script. For example, if the current variant is `pinyin` (Chinese Pinyin), the script will be set to `Latn` (Latin). 2. If the current language code is assigned a `Suppress-Script` in the IANA Language Subtag Registry, set the current script to that script. - For example, if the current language code is `en` (English), the script will be set to `Latn` (Latin); if the code is `ru` (Russian), the script will be set to `Cyrl` (Cyrillic). + For example, if the current language code is `en` (English), the script will be set to `Latn` (Latin); + if the code is `ru` (Russian), the script will be set to `Cyrl` (Cyrillic). - 3. If the current language code is `lzh` (Classical Chinese), set the script to `Hant` (Traditional Chinese). + 3. If the current language code is `lzh` (Classical Chinese), set the script to `Hant` (Traditional Chinese Characters). - 4. If the current language code is `zh` or a sublanguage of `zh`, check if the current region code is one of `TW`, `HK`, or `MO`. If true, set the script to `Hant` (Traditional Chinese); otherwise, set it to `Hans` (Simplified Chinese). + 4. If the current language code is `zh` or a sublanguage of `zh`, check if the current region code is one of `TW`, `HK`, or `MO`. + If true, set the script to `Hant` (Traditional Chinese Characters); + otherwise, set it to `Hans` (Simplified Chinese Characters). After refining the language code, HMCL will derive a list of language tags based on this language tag. @@ -228,15 +240,20 @@ For the language tag `zh-CN`, HMCL will refine it to `cmn-Hans-CN` and derive th 8. `zh` 9. `und` -For resources that can be merged (such as `.properties` files), HMCL will merge resources according to the priority of this list; for resources that are difficult to merge (such as font files), HMCL will load the highest-priority resource found in this list. +For resources that can be merged (such as `.properties` files), +HMCL will merge resources according to the priority of this list; for resources that are difficult to merge (such as font files), +HMCL will load the highest-priority resource found in this list. -If the current language uses a three-letter ISO 639 code, but there is also a corresponding two-letter code, HMCL will map it to the two-letter code before searching for resources. +If the current language uses a three-letter ISO 639 code, but there is also a corresponding two-letter code, +HMCL will map it to the two-letter code before searching for resources. -For example, if the current environment's language tag is `eng-US`, HMCL will map it to `en-US` and then search for localization resources according to the above rules. +For example, if the current environment's language tag is `eng-US`, +HMCL will map it to `en-US` and then search for localization resources according to the above rules. ### Additional Rules for Chinese -HMCL always adds `zh-CN` to the search list for all Chinese environments, and adds `zh-TW` to the search list for all Traditional Chinese environments. +HMCL always adds `zh-CN` to the search list for all Chinese environments, +and adds `zh-TW` to the search list for all Traditional Chinese environments. Below are the localization resource search lists for several common Chinese environments. @@ -293,7 +310,8 @@ Below are the localization resource search lists for several common Chinese envi -To simplify documentation maintenance, HMCL uses a macro mechanism to automatically maintain parts of the documentation content. Run the following command in the terminal: +To simplify documentation maintenance, HMCL uses a macro mechanism to automatically maintain parts of the documentation content. +Run the following command in the terminal: ```bash ./gradlew updateDocuments @@ -301,11 +319,11 @@ To simplify documentation maintenance, HMCL uses a macro mechanism to automatica This will automatically update all documentation content. -For example, to create links for switching between different language versions of the same document, add the following content under the document title: +For example, to create links for switching between different language versions of the same document, +add the following content under the document title: ```markdown -**English** | [中文](Localization_zh.md) ``` diff --git a/docs/Localization_zh.md b/docs/Localization_zh.md index d11bfcf722f..dc2d889637f 100644 --- a/docs/Localization_zh.md +++ b/docs/Localization_zh.md @@ -109,7 +109,7 @@ HMCL 的绝大多数文本都位于这个文件中，翻译此文件就能翻译 作为翻译的第一步，请从[这张表格](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry)中查询这个语言对应的两字母或三字母语言标签。 例如，英语的语言标签为 `en`。 -在确定了语言标签后，请在 [`I18N.properties` 文件旁](../HMCL/src/main/resources/assets/lang)创建 `I18N_<语言标签>.properites` (例如 `I18N_en.properties`) 文件。 +在确定了语言标签后，请在 [`I18N.properties` 文件旁](../HMCL/src/main/resources/assets/lang)创建 `I18N_<本地化文件后缀>.properites` (例如 `I18N_en.properties`) 文件。 随后，你就可以开始在这个文件中进行翻译工作了。 `I18N.properties` 文件会遵循[资源回退机制](#资源回退机制)查询缺失的译文。 @@ -303,7 +303,6 @@ HMCL 总是会将 `zh-CN` 加入所有中文环境的搜索列表中，将 `zh-T ```markdown -[English](Localization.md) | **中文** ``` From 1bf9becabbf4ee9db66c63cc7cee81f50011c92c Mon Sep 17 00:00:00 2001 From: Glavo Date: Thu, 23 Oct 2025 21:28:04 +0800 Subject: [PATCH 09/10] update --- .../java/org/jackhuang/hmcl/gradle/docs/Document.java | 8 ++------ docs/Localization.md | 4 ++-- docs/Localization_zh.md | 4 ++-- 3 files changed, 6 insertions(+), 10 deletions(-) diff --git a/buildSrc/src/main/java/org/jackhuang/hmcl/gradle/docs/Document.java b/buildSrc/src/main/java/org/jackhuang/hmcl/gradle/docs/Document.java index e2c39ad8a53..f7d674d910e 100644 --- a/buildSrc/src/main/java/org/jackhuang/hmcl/gradle/docs/Document.java +++ b/buildSrc/src/main/java/org/jackhuang/hmcl/gradle/docs/Document.java @@ -103,12 +103,8 @@ public static Document load(DocumentFileTree directory, Path file, String name, if (line == null) throw new IOException("Missing end line for macro: " + macroName); - else if (line.startsWith(" - + To simplify documentation maintenance, HMCL uses a macro mechanism to automatically maintain parts of the documentation content. Run the following command in the terminal: @@ -334,4 +334,4 @@ After running `./gradlew updateDocuments`, these two lines will be automatically ``` For more about macros, see [MacroProcessor.java](../buildSrc/src/main/java/org/jackhuang/hmcl/gradle/docs/MacroProcessor.java). - \ No newline at end of file + diff --git a/docs/Localization_zh.md b/docs/Localization_zh.md index dc2d889637f..394b2c718eb 100644 --- a/docs/Localization_zh.md +++ b/docs/Localization_zh.md @@ -290,7 +290,7 @@ HMCL 总是会将 `zh-CN` 加入所有中文环境的搜索列表中，将 `zh-T ## 自动同步文档内容 - + 为了简化文档的维护，HMCL 使用了一套宏机制自动维护文档的部分内容。在命令行中执行 ```bash @@ -313,4 +313,4 @@ HMCL 总是会将 `zh-CN` 加入所有中文环境的搜索列表中，将 `zh-T ``` 关于宏的更多内容，请见 [MacroProcessor.java](../buildSrc/src/main/java/org/jackhuang/hmcl/gradle/docs/MacroProcessor.java)。 - \ No newline at end of file + From 6e62b4d328c5f945ef884f156abc7702e5c71346 Mon Sep 17 00:00:00 2001 From: Glavo Date: Thu, 23 Oct 2025 21:30:09 +0800 Subject: [PATCH 10/10] update --- docs/Localization_zh.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Localization_zh.md b/docs/Localization_zh.md index 394b2c718eb..549896808c9 100644 --- a/docs/Localization_zh.md +++ b/docs/Localization_zh.md @@ -109,7 +109,7 @@ HMCL 的绝大多数文本都位于这个文件中，翻译此文件就能翻译 作为翻译的第一步，请从[这张表格](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry)中查询这个语言对应的两字母或三字母语言标签。 例如，英语的语言标签为 `en`。 -在确定了语言标签后，请在 [`I18N.properties` 文件旁](../HMCL/src/main/resources/assets/lang)创建 `I18N_<本地化文件后缀>.properites` (例如 `I18N_en.properties`) 文件。 +在确定了语言标签后，请在 [`I18N.properties` 文件旁](../HMCL/src/main/resources/assets/lang)创建 `I18N_<本地化文件后缀>.properties` (例如 `I18N_en.properties`) 文件。 随后，你就可以开始在这个文件中进行翻译工作了。 `I18N.properties` 文件会遵循[资源回退机制](#资源回退机制)查询缺失的译文。