HarbourMasters / HarbourMasters/Shipwright

Feature EPIC: Localization Refactor and Support

Open
#4,936 1 comment 1 reaction 0 assignees View on GitHub
epic
Dominant language
C
Stars
5.4k
Forks
837
Avg merge
1d 9h
Merged PRs (30d)
72

Description

Project details can be found [here](https://github.com/users/TheJabuJabu/projects/1).

### Overview

The current localization system is limited and tailored primarily to the PAL version's English, French, and German languages. To better support existing languages, enable modding, and facilitate future translations, we need a robust and flexible localization framework. Additionally, all vanilla strings must be extracted from user-provided ROMs.

### Goals

**String Extraction Framework**
Develop a system that extracts vanilla strings from user-provided ROMs into a human-readable and editable format (e.g., JSON).
Ensure the framework supports adding new languages without altering the original ROM content.

**Refactor Localization System**
Refactor the code to support any combination of languages, not just the default ones from the base ROMs (PAL, NA, JP, iQue).
Replace the current language handling with a system using standardized ISO 639 language codes (potentially with locale extensions).

**Dynamic Asset Loading by Language**
Transition from hardcoded language asset lists (e.g., scripts = [script_EN, script_FRA, script_GER]) to directory-based dynamic paths:

`scripts//script`

This allows mods to add new translations simply by placing files in the correct directory structure.

**Partial Translation and Fallback Mechanism**
Build a system to detect and list languages with at least partial support.
Implement fallback logic to default to English (or another available language) if specific assets are missing.

**Font Support for Non-Vanilla Languages**
Ensure mods can include necessary glyphs for unsupported languages (e.g., Korean, Chinese).

**Localized Texture Support**
Identify textures that require localization (e.g., boss titles, location names) and ensure they use the language setting for asset loading.

**Localization of SoH ImGui UI**
Update the SoH ImGui UI to fully support localization, addressing unique challenges for UI-based assets.

**Unified Encoding for In-Game Strings**
Transition to a standard encoding (e.g., Unicode) for strings to support a wider range of languages.
Ensure that encoding preserves control codes and formatting for in-game triggers.

**Support for Dynamically Constructed Strings**
Develop a scalable system for translating dynamically constructed strings (e.g., those used in randomizers).
Provide an external mechanism for mods to supply translations for such strings.

**Legal Compliance for Vanilla Strings**
Extract all vanilla strings from the user-provided ROM to comply with copyright laws.
Store extracted strings in a human-readable/editable format.
Provide a framework that allows players to drop in new language files without distributing vanilla strings.

### Proposed Implementation Steps

**Asset Path Refactor**
Replace existing hardcoded lists with dynamic path-based loading for scripts and textures.

**Language Detection System**
Implement a method to detect available languages (folders/files) and populate the UI with selectable options.

**Fallback System**
Add logic to attempt loading user-selected language assets first, then fallback to English or other available files.

**String Encoding Overhaul**
Define a representation format for strings that supports both Unicode and in-game control codes.

**Font Glyph Integration**
Provide a method for mods to include and integrate additional font glyphs for non-vanilla languages.

**UI Localization Support**
Update the SoH ImGui framework to support dynamic text and language switching.

**Partial Translations Handling**
Ensure the system can handle sparse data within large files (e.g., JSON blobs) to support incomplete translations.

**Dynamic String Translation Framework**
Develop an external mechanism or translation dictionary that mods can use to define translations for dynamic strings.

### Challenges

**Technical Feasibility**
- Maintaining performance with a more flexible and dynamic localization system.
- Preserving existing functionality while transitioning to new encoding formats and asset-loading mechanisms.

### Acceptance Criteria

- The localization system must support ISO 639 language codes and allow mods to add new languages without code changes.
- A fallback mechanism ensures that untranslated assets default gracefully to a supported language.
- UI elements, in-game strings, dynamically generated text, and textures are fully localizable.
- Vanilla strings are extracted from the ROM into an editable format, ensuring legal compliance.
- Modders can add glyphs for unsupported languages.

### Future Considerations

- Support for right-to-left languages.
- Advanced font rendering for complex scripts (e.g., Indic, Thai).
- Enhancements for auto-detection of ROM-modified language data.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.