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"
}

For Mod Users & Translators

Want to translate your favorite mod into your language? Creating translation files for Translation Helper is simple and doesn't require any programming knowledge!

---

Prerequisites

Before creating a translation, make sure you have:

• Translation Helper installed in your game's ue4ss/Mods directory.
• A mod that supports Translation Helper.
• A text editor (e.g., VS Code, Notepad++, Sublime Text, or standard Notepad).
• The translation keys used by the mod.

Tip

Where to find translation keys:

1. Check if the mod already includes a default language file (e.g., ModName_en.json).
2. Check the mod author's documentation or repository.
3. Ask the mod author directly for their key list.

---

How to Create a Translation File

1. Identify Your Language Code

Translation Helper matches files using standard IETF language codes.

You can use general 2-letter codes (e.g., es, fr, en). If the game requests a specific regional variant like es-419 or fr-FR and a matching regional file is not found, Translation Helper will automatically fall back to the base language file (e.g., es.json or fr.json).

Language	Standard Code	Regional Variants (Optional)
English	en	en-US, en-GB
Spanish	es	es-ES, es-419
French	fr	fr-FR, fr-CA
German	de	de-DE
Japanese	ja	—
Simplified Chinese	zh-Hans	zh-CN
Traditional Chinese	zh-Hant	zh-TW
Russian	ru	ru-RU
Korean	ko	ko-KR
Portuguese	pt	pt-BR, pt-PT

---

2. Name Your File

Save your file using the exact format:

<ModName>_<LanguageCode>.json

• Example for InspectTools in Spanish: InspectTools_es.json
• Example for AdjustableLights in Japanese: AdjustableLights_ja.json

---

3. Write Your Translations

Create a standard JSON file. Map each mod key (do not alter this) to your translated string:

{
  "greeting": "¡Hola! Bienvenido al juego.",
  "menu_start": "Iniciar juego",
  "menu_options": "Opciones",
  "quest_complete": "¡Misión completada!"
}

Important

Always save your file using UTF-8 encoding (without BOM). This ensures accented letters and non-Latin alphabets (like Japanese or Chinese characters) are shown properly.

---

4. Install the File

Place your completed .json file inside the Localizations directory located in your ue4ss/Mods folder (create the folder if it does not already exist):

ue4ss/
└── Mods/
    └── Localizations/
        └── <ModName>_<LanguageCode>.json