Localization

Overview

KalmForge.Localization is a static class. Call Load() once after KalmForgeClient.Init() and from then on every Get(key) resolves against the active language with fallback to your project's default language, then to the key itself.

• ~40 ISO codes supported out of the box (full list in the dashboard).
• System language is auto-detected on first launch - saved to PlayerPrefs after the first SetLanguage.
• The full payload is cached on disk at Application.persistentDataPath/kalmforge_localization.json.

Quick start

1using KalmForge;
2using UnityEngine;
3using UnityEngine.UI;
4
5public class LocalizedHud : MonoBehaviour {
6    [SerializeField] Text title;
7    [SerializeField] Text body;
8
9    async void Start() {
10        await KalmForgeClient.Init();
11        await Localization.Load();
12
13        Refresh();
14        Localization.OnLanguageChanged += Refresh;
15    }
16
17    void Refresh() {
18        title.text = Localization.Get("hud.title");
19        body.text  = Localization.Format("hud.coins", playerCoins);
20    }
21}

Languages & detection

After Load() resolves, AvailableLanguages contains every code your project ships. The active language is picked in this order:

1. Whatever the player previously chose (persisted in PlayerPrefs under kalmforge.language).
2. The exact match for Application.systemLanguage (e.g. pt-br).
3. The base language code (pt when the system says pt-br).
4. The project's default language.

1// Show a language picker
2foreach (var code in Localization.AvailableLanguages) {
3    Debug.Log(code); // "en", "fr", "pt-br", ...
4}
5
6// Switch - returns false if the code is unknown.
7bool ok = Localization.SetLanguage("fr");

Resolving keys

Get(key) walks current language → default language → first non-empty value → the key string itself. It never returns null - a missing key shows up as the literal key, which is your bug-finding fallback.

1string label = Localization.Get("store.gem_pack.title");
2string formatted = Localization.Format("store.gem_pack.price", 4.99f);
3bool defined = Localization.Has("store.gem_pack.title");

Reacting to language changes

OnLanguageChanged fires whenever the dataset is loaded or SetLanguage succeeds. Re-bind your UI from this single handler:

1void OnEnable()  { Localization.OnLanguageChanged += Rebind; }
2void OnDisable() { Localization.OnLanguageChanged -= Rebind; }
3void Rebind()    { /* refresh every label */ }

Cache & offline

Load() tries the network first; on failure it falls back to kalmforge_localization.json in persistentDataPath. A successful network response overwrites the cache. The cache file name is exposed as Localization.CacheFileName - delete it to force a clean re-download.

API reference

REST endpoint

1GET /api/public/sdk/localization
2Headers:
3  X-API-Key: kf_xxx_yyy
4
5Response:
6{
7  "default_language": "en",
8  "languages": ["en", "fr", "pt-br", ...],
9  "keys": [
10    { "key": "hud.title", "values": { "en": "Score", "fr": "Score" } },
11    ...
12  ]
13}