Internationalization Support
Info
This documentation is AI-generated. You can help improve it by submitting an Issue.
提示
If the issue remains unresolved, visit GitHub Issues to search or submit new feedback, or join QQ group 694413711 for community support.
Contributions to this tutorial are always welcome.
How to Correctly Set HTML Page Language
Setting priority: Please refer to Page Language Setting Priority.
- Correctly set the Default Content Language in theme settings
- For posts, categories, tags, and pages that differ from the Default Content Language, go to the corresponding settings and correctly set their metadata.
Canonical Casing
When setting the Default Content Language and page language metadata, use canonical casing: lowercase language, title-case script, and uppercase region, such as zh-Hans-CN, zh-Hans, zh-CN, and en-US.
How to Modify Fixed Text/Language Files
Go to the Halo CMS deployment directory and find the themes/howiehz-higan/i18n folder. Inside, find the properties file for the corresponding language, modify and save it (for example, Simplified Chinese is zh_Hans.properties).
Sync Cookie Language Based on Page Content Language
This theme enables Sync Cookie Language Based on Page Content Language by default.
When enabled, if a page is visited without a non-empty ?language= parameter and the browser's language Cookie differs from the current page language[1], the theme synchronizes the language Cookie to the current page language[1:1] and refreshes the page after the Cookie is set successfully.
Canonical Casing
Cookie language synchronization ignores casing during comparison and treats _ as -. For example, zh_CN, zh-CN, and zh-cn are treated as the same language value. When writing the language Cookie, the theme preserves the current page language[1:2] as written; if the current page language[1:3] is zh-Hans, the written value is zh-Hans, not zh-hans.
Therefore, items involved in Page Language Setting Priority should use canonical casing: lowercase language, title-case script, and uppercase region, such as zh-Hans-CN, zh-Hans, zh-CN, and en-US.
If the visit triggers browser language-based auto redirect, the theme redirects to the target page with ?language=... first and does not perform Cookie synchronization on the current page.
This prevents theme fixed text from continuing to use the previous Cookie language and becoming inconsistent with the current page language[1:4]. If you do not want Cookie synchronization to cause an extra refresh, you can disable this option.
Browser Language-Based Auto Redirect Guide
This theme has comprehensive support for language-based auto redirect. You can enable Browser Language-Based Auto Redirect.
Warning
When the URL already contains a non-empty ?language= parameter, or when the current post, category, tag, or page has a "Page Language" metadata marker, browser language-based auto redirect will not run.
提示
Press F12 (or Fn+F12) to open the developer console, select the console tab. Enter navigator.language and press Enter to view your browser's navigator.language value.
Canonical Casing
Browser language-based auto redirect ignores casing only during matching and treats _ as -. For example, zh_CN, zh-CN, and zh-cn participate in matching as the same candidate value. When writing ?language=, the theme uses the matched allowed redirect target as written, except _ is replaced with -; if the configured value is zh-Hans, the redirect parameter is ?language=zh-Hans, not ?language=zh-hans.
Therefore, the Allowed Target Locale Language Code List should use canonical casing: lowercase language, title-case script, and uppercase region, such as zh-Hans-CN, zh-Hans, zh-CN, and en-US.
After enabling this option, Allowed Target Locale Language Code List should be set in the following format.
Note: When Multilingual Function Prefix Match Mode is disabled, matching follows the browser language candidate path order. When it is enabled, matching follows the list below from top to bottom.
| Allowed Target Locale Language Code List |
|---|
zh-CN |
en-US |
Matching Flow
For easier configuration, auto redirect first generates candidate paths from the browser language, then matches those paths against the allowed target language list.
After a target language is matched, the theme checks whether it is "equivalent" to the Default Content Language: if the default content language already covers that target language, no redirect happens. Otherwise, the theme redirects to a URL with ?language=.
For example, if the default content language is zh-CN and the browser finally matches the target language zh-Hans, no redirect happens because the candidate path for zh-CN includes zh-Hans.
When checking whether specific Chinese language targets such as zh-Hans and zh-Hant are equivalent, the check intentionally ignores the generic zh fallback, so zh-Hans and zh-Hant are not treated as the same language just because both can fall back to zh.
Candidate Path Table
Chinese language candidates stay as close as possible to Halo CMS backend language resource lookup behavior:
navigator.language value | Candidate path |
|---|---|
zh-CN / zh-SG | zh-Hans-{REGION} -> zh-Hans -> original language code -> zh |
zh-Hans-* | original language code -> zh-Hans -> zh-{REGION} -> zh |
zh-Hans | zh-Hans -> zh-CN -> zh |
zh-TW / zh-HK / zh-MO | zh-Hant-{REGION} -> zh-Hant -> original language code -> zh |
zh-Hant-* | original language code -> zh-Hant -> zh-{REGION} -> zh |
zh-Hant | zh-Hant -> zh-TW -> zh |
zh-MY and other zh-* | original language code -> zh |
zh | zh |
| Other non-Chinese languages | original language code |
After enabling Multilingual Function Prefix Match Mode, language codes in the Allowed Target Locale Language Code List can match browser language candidates by prefix instead of requiring an exact match.
Example: zh below can match Chinese candidates such as zh-Hans and zh-Hant.
Note: If you use the generic zh as an allowed redirect target, Simplified and Traditional Chinese are intentionally collapsed into the same zh target. If you want separate redirects for Simplified and Traditional Chinese, use zh-Hans, zh-Hant, or a more specific locale language code.
| Allowed Target Locale Language Code List |
|---|
zh |
en |
Multilingual Menu Usage Guide
This theme has comprehensive multilingual menu support. You can enable Multilingual Menu Support.
The multilingual menu matches top-level menu names against the current page language[1:5].
Canonical Casing
The multilingual menu ignores casing only during matching. For example, zh-CN and zh-cn are treated as the same language value.
Therefore, top-level menu names should use canonical casing: lowercase language, title-case script, and uppercase region, such as zh-Hans-CN, zh-Hans, zh-CN, and en-US.
Warning
If multiple top-level menu items match at the same time, the child items of all matched menu items are rendered.
After enabling this option, the main menu should be set in the following format. (Note: The zh-CN item can be a custom link with URL / and name zh-CN. The name is the key setting; other settings don't affect matching)
| Top-level menu item | Second-level menu items |
|---|---|
zh-CN | 首页 关于 |
en-US | Home About |
After enabling Multilingual Function Prefix Match Mode, top-level menu names can match the current page language[1:6] by prefix instead of requiring an exact match.
Example: when the current page language[1:7] is zh-Hans or zh-Hant, the zh menu below can match both.
| Top-level menu item | Second-level menu items |
|---|---|
zh | 首页 关于 |
en | Home About |
The menu with a name that matches the Default Content Language setting value case-insensitively will be used as the default menu, which will be displayed when no successful match is found.
Multilingual Page Bottom/Sidebar Content Usage Guide
Multilingual page bottom/sidebar content matches language codes in the configuration against the current page language[1:8].
Canonical Casing
Multilingual page bottom/sidebar content ignores casing only during matching. For example, zh-CN and zh-cn are treated as the same language value.
Therefore, the "Language Code" in Custom Multi-language Page Bottom/Sidebar Content should use canonical casing: lowercase language, title-case script, and uppercase region, such as zh-Hans-CN, zh-Hans, zh-CN, and en-US.
Warning
If multiple configuration items match at the same time, all matched page bottom/sidebar content items are rendered.
After enabling Multi-language Page Bottom/Sidebar Content Support, Custom Multi-language Page Bottom/Sidebar Content should be set in the following format.
| Custom Multi-language Page Bottom/Sidebar Content | ||||
|---|---|---|---|---|
| ||||
|
After enabling Multilingual Function Prefix Match Mode, language codes can match the current page language[1:9] by prefix instead of requiring an exact match.
Example: when the current page language[1:10] is zh-Hans or zh-Hant, zh below can match both. The above configuration can be changed to:
| Custom Multi-language Page Bottom/Sidebar Content | ||||
|---|---|---|---|---|
| ||||
|
The item whose Language Code matches the Default Content Language setting value case-insensitively will be used as the default page bottom/sidebar content when no successful match is found.
Multilingual Bio/Announcement Usage Guide
Multilingual bio/announcement content matches language codes in the configuration against the current page language[1:11].
Canonical Casing
Multilingual bio/announcement content ignores casing only during matching. For example, zh-CN and zh-cn are treated as the same language value.
Therefore, the "Language Code" in Custom Multi-language Announcement Content should use canonical casing: lowercase language, title-case script, and uppercase region, such as zh-Hans-CN, zh-Hans, zh-CN, and en-US.
Warning
If multiple configuration items match at the same time, all matched bio/announcement content items are rendered.
After enabling Multilingual Bio/Announcement Support, Custom Multilingual Announcement Content should be set in the following format.
| Custom Multilingual Announcement Content | ||||
|---|---|---|---|---|
| ||||
|
After enabling Multilingual Function Prefix Match Mode, language codes can match the current page language[1:12] by prefix instead of requiring an exact match.
Example: when the current page language[1:13] is zh-Hans or zh-Hant, zh below can match both. The above configuration can be changed to:
| Custom Multilingual Announcement Content | ||||
|---|---|---|---|---|
| ||||
|
The announcement content with a language code that matches the Default Content Language setting value case-insensitively will be used as the default announcement content, which will be displayed when no successful match is found.