punkfuncgames/localization-module

LocalizationModule Reference

Package: com.punkfuncgames.localization | Define: PUNKFUNC_LOCALIZATION Location: Packages/com.punkfuncgames.localization/Runtime/PunkFuncGames.Localization/ Namespace: PunkFuncGames.Localization

ILocalizationService : IAsyncInitializable, IAsyncStartable

Properties:

• ReadOnlyReactiveProperty<SystemLanguage> CurrentLanguage
• IReadOnlyList<SystemLanguage> AvailableLanguages
• bool IsLanguageLoaded

Language Control:

• SetLanguage(SystemLanguage language)
• UniTask PreloadLanguageAsync(SystemLanguage language, ct)
• UnloadLanguage(SystemLanguage language) — cannot unload current or fallback

Text Retrieval:

• string GetText(string key) — returns localized text, falls back to default language, then [key]
• string GetText(string key, params object[] args) — with string.Format
• bool TryGetText(string key, out string value)
• bool HasKey(string key), IReadOnlyList<string> GetAllKeys()

Asset Paths:

• string GetLocalizedAssetPath(string basePath) — inserts language code before extension (e.g., icons/flag → icons/flag_en)

Implementation: LocalizationService

Dependencies: LocalizationSettings (required), ISteamService (optional), 4 MessagePipe publishers

Language Detection Order:

1. PlayerPrefs (if SaveLanguagePreference enabled)
2. Steam language (if ISteamService available)
3. System language (Application.systemLanguage)
4. Default from settings

File Loading: JSON files from Resources or Addressables

• Supports nested JSON with dot notation flattening ({ "ui": { "title": "Hello" } } → key "ui.title")
• Ignores "meta" section

Dual Dictionary System: Current language + fallback language for graceful degradation

Configuration: LocalizationSettings (Config + Data Pattern)

LocalizationSettings (ScriptableObject): Thin wrapper with public LocalizationSettingsData data; Access fields via _settings.data.fieldName.

LocalizationSettingsData ([Serializable] public struct, camelCase fields):

• SystemLanguage defaultLanguage — English
• SystemLanguage[] supportedLanguages — 10 defaults (en, es, fr, de, it, pt, ru, zh, ja, ko)
• string localizationFolder — "Localization"
• bool useAddressables, bool autoDetectLanguage, bool saveLanguagePreference
• bool useFallback, bool returnKeyOnMissing, bool logMissingKeys

Extension methods on LocalizationSettingsData:

• GetLanguageFileName(SystemLanguage) → language code string (e.g., English → "en")
• IsLanguageSupported(SystemLanguage) → bool

Events

| Event | Key Fields | |-------|------------| | LanguageChangedEvent | PreviousLanguage, NewLanguage | | LanguageLoadStartedEvent | Language | | LanguageLoadCompletedEvent | Language, Success, StringCount | | LocalizationKeyMissingEvent | Key, Language |

Installer

LocalizationInstaller.Install(builder, options, localizationSettings);
// Registers: LocalizationService as EntryPoint (ILocalizationService)
// Events: all 4 message brokers

Usage Pattern

// Get localized text
string title = _localization.GetText("ui.main_menu.title");
string formatted = _localization.GetText("ui.score", score);

// React to language change
_localization.CurrentLanguage
    .Subscribe(lang => RefreshUI())
    .AddTo(_disposables);

// Use LocalizedText component (auto-updates on language change)
// Attach to any GameObject with TMP_Text, set _key in inspector

// Get localized asset path for images
string path = _localization.GetLocalizedAssetPath("icons/flag"); // → "icons/flag_en"