Languages Library

Internationalization (i18n) and localization system for the Lilia framework.

---

Overview

The languages library provides comprehensive internationalization (i18n) functionality for the Lilia framework. It handles loading, storing, and retrieving localized strings from language files, supporting multiple languages with fallback mechanisms. The library automatically loads language files from directories, processes them into a unified storage system, and provides string formatting with parameter substitution. It includes functions for adding custom language tables, retrieving available languages, and getting localized strings with proper error handling. The library operates on both server and client sides, ensuring consistent localization across the entire gamemode. It supports dynamic language switching and provides the global L() function for easy access to localized strings throughout the codebase.

---

lia.lang.loadFromDir(directory)

Load language files from a directory and merge them into storage.

During startup to load built-in and schema-specific localization.

Parameters:

string directory Path containing language Lua files.

Example Usage:

    -- Load base languages and a custom pack.
    lia.lang.loadFromDir("lilia/gamemode/languages")
    lia.lang.loadFromDir("schema/languages")

---

lia.lang.addTable(name, tbl)

Merge a table of localized strings into a named language.

When adding runtime localization or extending a language.

Parameters:

string name Language id (e.g., "english").

table tbl Key/value pairs to merge.

Example Usage:

    lia.lang.addTable("english", {
        customGreeting = "Hello, %s!",
        adminOnly = "You must be an admin."
    })

---

lia.lang.getLanguages()

List available languages by display name.

When populating language selection menus or config options.

Returns:

table Sorted array of language display names.

Example Usage:

    for _, langName in ipairs(lia.lang.getLanguages()) do
        print("Language option:", langName)
    end

---

lia.lang.generateCacheKey(lang, key)

Build a cache key for a localized string with parameters.

Before caching formatted localization results.

Parameters:

string lang

string key ... (vararg)

Returns:

string

Example Usage:

    local cacheKey = lia.lang.generateCacheKey("english", "hello", "John")

---

lia.lang.cleanupCache()

Evict half of the cached localization entries when over capacity.

Automatically from getLocalizedString when cache exceeds maxSize.

Example Usage:

    if lia.lang.cache.currentSize > lia.lang.cache.maxSize then
        lia.lang.cleanupCache()
    end

---

lia.lang.clearCache()

Reset the localization cache to its initial state.

When changing languages or when flushing cached strings.

Example Usage:

    hook.Add("OnConfigUpdated", "ClearLangCache", function(key, old, new)
        if key == "Language" and old ~= new then
            lia.lang.clearCache()
        end
    end)

---

lia.lang.getLocalizedString(key)

Resolve and format a localized string with caching and fallbacks.

Every time L() is used to display text with parameters.

Parameters:

string key Localization key.

Returns:

string Formatted localized string or key when missing.

Example Usage:

    local msg = lia.lang.getLocalizedString("welcomeUser", ply:Name(), os.date())
    chat.AddText(msg)

---