Getting Started

For Mod Authors

Translation Helper allows mods to easily support localization. It accepts a key and a fallback string from your mod, checks the current game language, looks up the corresponding translated JSON file, and returns either the translated string or your fallback value.

Because the API returns the fallback string whenever the mod or translation is missing, Translation Helper acts as a safe soft dependency.

---

API Reference

• C++: Uses the TH:: namespace (#include "TranslationHelperAPI.h").
• Lua: Uses the global TH table.

Registration

Registers your mod with the API. This tells Translation Helper which translation JSON namespace to associate with your calls.

• C++: Required before calling Translate / TranslateW.
• Lua: Optional, but recommended for consistency.

/**
 * @brief Registers a mod to the API (required for C++ translation lookups).
 * @param mod_name Unique identifier for your mod (must remain consistent).
 */
static void RegisterMod(const char* mod_name);

---Registers the mod to the API.
---@param modName string Unique identifier for your mod.
function TH.RegisterMod(modName) end

Important

Your mod_name must be unique and remain constant across updates, as it matches the folder/JSON naming convention.

---

Translation

Fetches a localized string by its key. If Translation Helper is missing or the key is not translated, the fallback value is returned immediately.

/**
 * @brief Translates a string using its unique key.
 * @param key The translation lookup key.
 * @param fallback The default string if translation is not found.
 * @return const char* The translated string or the fallback.
 */
static const char* Translate(const char* key, const char* fallback);

/**
 * @brief Translates a string and returns a wide string (std::wstring).
 * @param key The translation lookup key.
 * @param fallback The default string if translation is not found.
 * @return std::wstring The translated string or the fallback as a wide string.
 */
static std::wstring TranslateW(const char* key, const char* fallback);

---Translates a string using its unique key.
---@param modName string The mod's unique identifier.
---@param key string The translation lookup key.
---@param fallback string The default string if translation is not found.
---@return string The translated string or fallback.
function TH.Translate(modName, key, fallback) end

---

Helper Utilities (C++ Only)

/**
 * @brief Checks if the TranslationHelper instance is active and initialized.
 * @return true if available, false otherwise.
 */
static bool HasInit();

---

Usage Examples

Lua

For Lua scripts, define a short wrapper function to pass your ModName automatically. You can also include THelper.lua in your workspace for IDE autocompletion.

local ModName = "THelperLuaExample"

---Helper function to pass ModName automatically
---@param key string
---@param fallback string
---@return string
local function Translate(key, fallback)
    if not TH then
        return fallback
    end
    return TH.Translate(ModName, key, fallback)
end

-- Initialize mod registration (not required on lua)
if TH then
    TH.RegisterMod(ModName)
end

-- Example calls
print(Translate("greeting", "Hello! Welcome to the mod."))
print(Translate("menu_start", "Start Game"))

---

C++

Include TranslationHelperAPI.h in your project. Call TH::RegisterMod once during initialization before making translation requests.

#include "TranslationHelperAPI.h"

void InitMod()
{
    // Register the mod once on startup
    TH::RegisterMod("THelperCPPExample");
}

void DoSomething()
{
    // Standard char* translation
    const char* greeting = TH::Translate("greeting", "Hello from C++ Mod!");

    // Wide string translation (ideal for UE4SS / Unreal Engine logs etc)
    std::wstring wGreeting = TH::TranslateW("greeting", "Hello from C++ Mod!");
    std::wstring wStartBtn = TH::TranslateW("menu_start", "Start Game");
}

---

File & Translation Structure

Translation files are structured as JSON dictionaries matching your unique mod name and the target language code in IETF format:

Mods/
└── Localizations/
    ├── ModName_es.json
    ├── ModName_fr.json
    ├── ModName_zh-Hans.json

JSON Format (ModName_es.json)

{
  "greeting": "¡Hola!",
  "menu_start": "Iniciar juego"
}