Common Mistakes When Using hxLang¶

This document highlights frequent mistakes developers may encounter when using the hxLang localization system, and how to avoid them.

1. Not Providing the languages Array in init()¶

Problem¶

If you call Lang.init() without specifying the languages array, it may abort the initialization silently, especially in JS targets.

Example¶

Lang.init("assets/lang", null);

Output: [Lang] Aborting init: languages array not provided or NULL.

Solution¶

Always provide a list of language codes:

Lang.init("assets/lang", ["en", "pt", "es"]);

2. Missing Language Files or Incorrect Paths¶

Problem¶

If any language file is missing or the path is incorrect, the loader will retry indefinitely (especially on JS/HTML5 builds), possibly flooding logs.

Output: [Lang] Failed to load "pt": HTTP status 404. Retrying...

Solution¶

Ensure the file exists: assets/lang/pt.json

Make sure files are correctly embedded or served (e.g. embed in Haxe/OpenFL, or asset folders configured correctly in your build system)

3. Accessing Translations Before Language Is Loaded¶

Problem¶

Calling Lang.get("some.key") before loading a language will return "???".

Solution¶

Always call Lang.load(lang) (or Lang.switchLanguage(lang)) before trying to fetch strings.

Lang.switchLanguage("en");
trace(Lang.get("menu.play")); // Only valid after switching

4. Incorrect or Nested Key Paths in Lang.get()¶

Problem¶

Using incorrect key paths or assuming nested structure incorrectly.

Example¶

Lang.get("menu.start.play"); // Too deeply nested or wrong path

Solution¶

Ensure the path matches the structure in your JSON file. For example:

{
    "menu": {
        "play": "Play",
        "options": "Options"
    }
}

Then:

Lang.get("menu.play"); // "Play"
Lang.get("menu.start.play"); // returns "???"

5. Forgetting to Set Default Language¶

Problem¶

If you call switchLanguage() with an unknown language and forget to set a fallback using setDefaultLang(), it may fail silently or show "Unknown".

Solution¶

Set a default language explicitly:

Lang.setDefaultLang("en");
Lang.switchLanguage("fr"); // Fallbacks to "en" if "fr" is missing

6. Assuming Language File Contains currentLanguage¶

Problem¶

Lang.displayName is based on the currentLanguage field from the loaded language data. If your JSON does not include it, displayName will default to the language code.

Solution¶

Include the field in your language files:

{
    "currentLanguage": "English",
        "menu": {
            "play": "Play"
        }
    }

7. Using get() to Fetch Empty or Null Fields¶

Problem¶

If a key exists but its value is null or an empty string, the return value will still be "???", which may confuse debugging.

Solution¶

Ensure that all required keys in your JSON files are properly filled.

8. Relying on Infinite Retry Loops in JS¶

Problem¶

The JS version retries failed loads every second. This can be problematic if:

• The file is missing permanently
• The user has no internet connection
• You deploy with wrong paths

Solution¶

• Add a maximum retry count
• Improve error messaging
• Validate asset deployment before release

Tips :)¶

• Use Lang.langs() to list all loaded languages.
• Consider providing a GUI dropdown that maps Lang.get("currentLanguage") to Lang.switchLanguage(langCode).
• You can extend Lang to support pluralization, formatting, or parameter substitution.