Internationalization & Translations
Relevant source files
The following files were used as context for generating this wiki page:
The HoloPrint project implements a robust internationalization (i18n) and translation system designed to provide a localized user experience across the web application and within the generated Minecraft resource packs. The system manages UI text, in-game control descriptions, and material list naming across multiple languages, primarily English (en_US) and Simplified Chinese (zh_CN).
The architecture separates translation concerns into two main areas: client-side web UI translation using data attributes and JSON dictionaries, and resource pack generation which involves compiling .lang files for Minecraft Bedrock Edition. This ensures that features like block validation, hologram controls, and material lists are accessible to users in their preferred language both during the configuration phase and during active gameplay.
UI Translation Architecture
The web interface uses a declarative approach to translation. HTML elements are tagged with data-translate attributes, which act as keys for the translation engine to look up values in localized JSON files.
Translation Logic Flow
When a user changes the language via the language selector, the application fetches the corresponding JSON translation file and iterates through all elements marked for translation. It also handles attribute-specific translations (e.g., placeholders or titles) using the data-translate-[attribute] pattern.
Sources: src/index.js:332-385, src/index.html:199-204
Key Functions and Components
| Component | Functionality |
|---|---|
translatePage(language) | Asynchronous function that iterates through DOM elements and applies translations from fetched JSON. |
performTranslationSubstitutions() | Handles dynamic placeholders in strings, such as {COUNT} or pluralization logic using [singular/plural] brackets. |
MutationObserver | Monitors the document body for added nodes or changed attributes to ensure dynamically rendered content (like pack results) is translated immediately. |
languageSelector | A dropdown menu populated by translations/languages.json that triggers the re-translation process. |
Sources: src/index.js:347-362, src/index.js:388-403, src/index.js:424-444
Resource Pack Translation Generation
A critical feature of HoloPrint is generating .lang files that allow the Minecraft resource pack to display localized content. This includes the pack name, description, and specific item names for the hologram control system.
Data Flow for Pack Localization
The generation process combines template .lang files with dynamic data gathered from the structure file and user settings.
Dynamic Substitutions
The makeLangFiles function replaces several placeholders in the template files before zipping them into the final .mcpack:
- {PACK_NAME}: The user-defined or default name of the resource pack.
- {TOTAL_MATERIAL_COUNT}: The calculated number of blocks in the structure.
- {MATERIAL_LIST}: A concatenated string of required materials.
- {CONTROLS_SECTION}: Localized instructions for using items like Sticks or Copper Ingots to manipulate the hologram.
Sources: src/HoloPrint.js:774-790
Material List & Item Translation
The MaterialList class is responsible for mapping internal Minecraft block IDs to human-readable localized names. It uses vanilla metadata and translation files provided via a ResourcePackStack.
Translation Resolution Logic
To find the correct name for a block or item, the system follows a specific hierarchy to ensure coverage even for custom or renamed blocks.
- Check for specific patches in
material_list_mappings.json. - Search for the Item serialization ID in
mojang-items.json. - If not found, search for the Block serialization ID in
mojang-blocks.json. - Apply
.namesuffix to the ID (e.g.,tile.dirt.name). - Look up the key in the loaded
.langMap.
Sources: src/MaterialList.js:72-98, src/MaterialList.js:125-132
Material List Entries
The exported material list entries include the localized name and a "partitioned count" which displays quantities in stacks (s) and shulker boxes (emoji \uE200).
| Field | Description | Source |
|---|---|---|
translationKey | The raw key used in Minecraft .lang files. | src/MaterialList.js:94 |
translatedName | The final resolved string (e.g., "Stone Brick"). | src/MaterialList.js:95 |
partitionedCount | Formatted count: 100 = 1s + 36. | src/MaterialList.js:161-167 |
Translation Dictionaries
The project maintains JSON files for the web UI. These files share identical keys to ensure consistency across languages.
Sample Key Structure
{
"app_name": "HoloPrint",
"player_controls.move_hologram": "Move hologram",
"settings.ghost_block_scale": "Ghost block scale:",
"extract_from_world.extracting": "Extracting structures from world..."
}
Sources: src/translations/en_US.json:2-93, src/translations/zh_CN.json:2-108
Conclusion
The internationalization system in HoloPrint is a dual-layered architecture. For the web interface, it relies on a dynamic DOM-scanning engine and JSON dictionaries. For the generated Minecraft output, it leverages vanilla Bedrock Edition localization standards by compiling custom .lang files. This comprehensive approach ensures that complex technical data—such as block indices, material counts, and holographic controls—is presented clearly to a global user base.