lan/HMCL
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

将 Localization.md 翻译至英语 (#4669)

Browse Source
This commit is contained in:
Glavo
2025-10-24 11:55:14 +08:00
committed by GitHub
parent a921a11be6
commit fd7f909561
3 changed files with 347 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
buildSrc/src/main/java/org/jackhuang/hmcl/gradle/docs/Document.java
View File

@@ -103,12 +103,8 @@ public record Document(DocumentFileTree directory,
if (line == null)
throw new IOException("Missing end line for macro: " + macroName);
else if (line.startsWith("<!-- #END")) {
if (line.equals(endLine)) {
else if (line.equals(endLine)) {
break;
} else {
throw new IOException("Invalid macro end line: " + line);
}
} else {
lines.add(line);
}

337
docs/Localization.md Normal file
View File

@@ -0,0 +1,337 @@
# Localization
<!-- #BEGIN LANGUAGE_SWITCHER -->
**English** | [中文](Localization_zh.md)
<!-- #END LANGUAGE_SWITCHER -->
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.
## Supported languages
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 | |
| Chinese (Simplified) | `zh-Hans` | `zh` | `_zh` | `zh_cn` | **Primary** | [Glavo](https://github.com/Glavo) |
| Chinese (Traditional) | `zh-Hant` | `zh-Hant` | `_zh_Hant` | `zh_tw` <br/> `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 | |
<details>
<summary>About Language Tags</summary>
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.
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 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`.
</details>
<details>
<summary>About Localization Keys and File Suffixes</summary>
Localization file suffixes and keys are used to name [localization resources](#localization-resources).
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 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.
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.
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),
and use the more specific `zh-Hans`/`zh-Hant` as the key for the resource with fewer users.
</details>
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 with maintenance.
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 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 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.
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,
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.
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 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 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_<localization file suffix>.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.
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 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 of HMCL will complete the remaining steps for you.
## Localization Resources
All documentation and localization resource files follow the naming rule `<resource name><localization file suffix>.<extension>`.
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`
In addition to localized files, HMCL also supports localizing certain text fields in JSON. Localized text in JSON uses the following format:
```json5
{
"<Localization Key 1>": "<Localized Text 1>",
"<Localization Key 2>": "<Localized Text 2>",
// ...
"<Localization Key N>": "<Localized Text N>"
}
```
For example, for the following text field:
```json
{
"meow": "Meow"
}
```
It can be rewritten as 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.
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.
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.
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 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).
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 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.
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.
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. `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. `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`
3. `zh-TW`
4. `zh`
5. `zh-CN`
6. `und`
- `zh-HK`:
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-TW`
5. `zh`
6. `zh-CN`
7. `und`
## Automatic Synchronization of Documentation Content
<!-- #BEGIN BLOCK -->
<!-- #PROPERTY PROCESS_LINK=false -->
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
<!-- #BEGIN LANGUAGE_SWITCHER -->
<!-- #END LANGUAGE_SWITCHER -->
```
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).
<!-- #END BLOCK -->

12
docs/Localization_zh.md
View File

@@ -1,6 +1,8 @@
# 本地化
<!-- TODO: 本文档需要进一步完善。为了便于修改，我们暂时不将本文件翻译至其他语言，在完善后再在独立 PR 中提供其他语言的译文。 -->
<!-- #BEGIN LANGUAGE_SWITCHER -->
[English](Localization.md) | **中文**
<!-- #END LANGUAGE_SWITCHER -->
HMCL 为多种语言提供本地化支持。
@@ -107,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` 文件会遵循[资源回退机制](#资源回退机制)查询缺失的译文。
@@ -287,6 +289,8 @@ HMCL 总是会将 `zh-CN` 加入所有中文环境的搜索列表中，将 `zh-T
## 自动同步文档内容
<!-- #BEGIN BLOCK -->
<!-- #PROPERTY PROCESS_LINK=false -->
为了简化文档的维护，HMCL 使用了一套宏机制自动维护文档的部分内容。在命令行中执行
```bash
@@ -305,8 +309,8 @@ HMCL 总是会将 `zh-CN` 加入所有中文环境的搜索列表中，将 `zh-T
随后执行 `./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)。
<!-- #END BLOCK -->