Feature Description
Add comprehensive localization (i18n) support to HyperFactions with translations bundled directly in the mod JAR. All player-facing text should be translatable, allowing servers to run in any supported language.
Proposed Solution
Bundled language files inside JAR:
resources/
lang/
en_US.json # English (default)
es_ES.json # Spanish
de_DE.json # German
fr_FR.json # French
pt_BR.json # Portuguese (Brazil)
zh_CN.json # Chinese (Simplified)
ja_JP.json # Japanese
ru_RU.json # Russian
ko_KR.json # Korean
pl_PL.json # Polish
it_IT.json # Italian
nl_NL.json # Dutch
tl-PH.json # Philippines
Configuration:
language: en_US # Server-wide default languageper_player_locale: true # Use player's client locale when availablefallback_locale: en_US # Fallback if translation missing
Translation coverage - ALL player-facing text:
| Category | Examples |
|---|
| Commands | Success/error messages, confirmations, usage hints |
| GUI Labels | Button text, headers, descriptions, tooltips |
| GUI Help Pages | All help content, tutorials, explanations |
| Chat Messages | Faction announcements, alerts, notifications |
| Territory Messages | Enter/leave messages, claim feedback |
| Error Messages | Permission denied, invalid input, cooldowns |
| Relation Messages | Alliance requests, war declarations, truces |
| Power Messages | Power gain/loss notifications |
| Admin Messages | Admin command feedback, warnings |
Excluded from localization:
- Console debug logs (remain in English for developer debugging)
- Log file entries
- Internal error stack traces
Translation key format:
{
"command.create.success": "Faction {faction} has been created!",
"command.create.error.name_taken": "A faction with that name already exists.",
"gui.home.title": "Faction Home",
"gui.home.button.members": "Members",
"gui.help.claiming.title": "How to Claim Territory",
"gui.help.claiming.description": "Stand in a chunk and use /f claim to claim it for your faction.",
"territory.enter.faction": "~ {faction} ({relation}) ~",
"territory.enter.safezone": "~ SafeZone ~",
"power.gained": "You gained {amount} power. ({current}/{max})",
"error.no_permission": "You don't have permission to do that.",
"error.not_in_faction": "You must be in a faction to use this command."
}Placeholder support in translations:
{player} - Player name{faction} - Faction name{amount} - Numeric values{current} / {max} - Current/max values{relation} - Relation type (Ally, Enemy, etc.){time} - Formatted time values
Implementation approach:
- Create
LocalizationManager class to load and cache translations - Use message keys throughout codebase instead of hardcoded strings
- Provide
Lang.get(key, placeholders...) utility method - Auto-detect player locale from client settings (if per_player_locale enabled)
- Graceful fallback chain: Player locale → Server default → en_US → Raw key
Alternatives Considered
- External lang files in config folder - User requested against this; harder to distribute translations
- Resource pack based - Client-side only, doesn't work for chat messages
- Database-stored translations - Overcomplicated for this use case
- Crowdin/Weblate integration - Could be added later for community translations
Additional Context
- Translations bundled in JAR ensure all servers get updates automatically
- Community can contribute translations via GitHub PRs
- Consider adding
/f admin lang reload for hot-reloading during testing - GUI help pages are extensive - significant translation effort needed
- Permission messages should use consistent terminology across languages
- RTL (right-to-left) language support may require additional GUI work
Feature Description
Add comprehensive localization (i18n) support to HyperFactions with translations bundled directly in the mod JAR. All player-facing text should be translatable, allowing servers to run in any supported language.
Proposed Solution
Bundled language files inside JAR:
Configuration:
Translation coverage - ALL player-facing text:
Excluded from localization:
Translation key format:
{ "command.create.success": "Faction {faction} has been created!", "command.create.error.name_taken": "A faction with that name already exists.", "gui.home.title": "Faction Home", "gui.home.button.members": "Members", "gui.help.claiming.title": "How to Claim Territory", "gui.help.claiming.description": "Stand in a chunk and use /f claim to claim it for your faction.", "territory.enter.faction": "~ {faction} ({relation}) ~", "territory.enter.safezone": "~ SafeZone ~", "power.gained": "You gained {amount} power. ({current}/{max})", "error.no_permission": "You don't have permission to do that.", "error.not_in_faction": "You must be in a faction to use this command." }Placeholder support in translations:
{player}- Player name{faction}- Faction name{amount}- Numeric values{current}/{max}- Current/max values{relation}- Relation type (Ally, Enemy, etc.){time}- Formatted time valuesImplementation approach:
LocalizationManagerclass to load and cache translationsLang.get(key, placeholders...)utility methodAlternatives Considered
Additional Context
/f admin lang reloadfor hot-reloading during testing