Overview

This module serves as the primary interface for retrieving and formatting localized game text from the Data:Lang_*.json files. It handles variable substitution by fetching data from Module:ItemData, automatically applies rich text formatting for game-specific keywords (adding icons, colors, and links), and provides robust fallback mechanisms for missing translations.

Functions

get_string

Localizes a given string key to the current language, i.e. Data:Lang_en.json for English. This function also automatically processes game-specific formatting tags (see "Automatic Text Formatting" section below).

Note: If you need to get a string that uses a value referenced from another Data page, pass the item_name parameter to get_string.

Parameters

key - Key string to localize.
lang_code_override (OPTIONAL) - Overrides the current language to a specific language code.
fallback_str (OPTIONAL) - Specifies behavior when a key is not found in the target language.
- Passing en causes it to return the English localization.
- Passing any other string causes it to return that string.
- Both of the above options have Template:MissingValveTranslationTooltip appended.
- Passing dictionary causes it to return a translation via Module:Dictionary without the tooltip.
- Use this often, as some keys are not yet localized in every language by the game. If parsing the fallback_str from Lua is computationally expensive, consider using the fallback outside this function so it only computes when needed.
remove_var_index (OPTIONAL) - Removes %variables% from the resulting string. -1 also removes the character prefixing %variables%, while 1 removes the postfixed character, and 0 removes only the %variables%.
item_name (OPTIONAL) - Required for strings containing {s:variable} placeholders. It will fetch the corresponding property from Module:ItemData to fill in the variable.

NOTE: When calling from wikitext via #invoke, parameters can be named. When calling from another Lua module, parameters must be passed in order (e.g., p.get_string(key, nil, 'en')).

Internal Logic & Fallbacks

The function includes several automatic behaviors to handle inconsistencies in the source data:

Key Overrides: It checks a hardcoded list of overrides for known edge cases. For example, if the key MoveSlowPercent_label is requested, the module will internally use the value for MovementSlow_label to handle this known inconsistency.
Post-value Label Fallback: If a key ending in _label is not found, it will automatically try again with a key ending in _postvalue_label.
String Parsing: If a retrieved string contains | or #, the function will automatically use only the text that comes after the final instance of that character.

Examples

Invokes from wikitext:

{{#invoke:Lang|get_string|CitadelHeroStats_Weapon_Falloff}}

Falloff Range

{{#invoke:Lang|get_string|CitadelHeroStats_Weapon_Falloff|lang_code_override=es}}

Distancia de caída

Strings with Variables

For strings containing {s:variable}, provide the item_name:

Example: {{#invoke:Lang|get_string|upgrade_target_stun_desc|item_name=Knockdown}} → Apply a Stun after 2s. Stun duration is increased against airborne targets.

Increases the target's gravity for the duration of the stun.

Without item_name, variables won't be filled: {{#invoke:Lang|get_string|upgrade_target_stun_desc}} → Apply a Stun after {s:StunDelay}s. Stun duration is increased against airborne targets.

Increases the target's gravity for the duration of the stun.

Examples for fallback_str

{{#invoke:Lang|get_string|StatDesc_CritDamageBonusScale|lang_code_override=es}}

Escala de críticos adicional

{{#invoke:Lang|get_string|StatDesc_CritDamageBonusScale|lang_code_override=es|fallback_str=en}}

Escala de críticos adicional

{{#invoke:Lang|get_string|StatDesc_CritDamageBonusScale|lang_code_override=es|fallback_str=Crit Damage Bonus Scale}}

Escala de críticos adicional

{{#invoke:Lang|get_string|Tech Items|fallback_str=dictionary}}

Key 'Tech Items' is not in Data:Dictionary

Examples for remove_var_index

{{#invoke:Lang|get_string|Citadel_HeroBuilds_DefaultHeroBuild}}

Default %hero_name% Build

TODO: Debug why is =0 still removing that extra space? Doesn't matter yet I suppose, no use cases for 0 yet {{#invoke:Lang|get_string|Citadel_HeroBuilds_DefaultHeroBuild|remove_var_index=0}}

Default Build

{{#invoke:Lang|get_string|Citadel_HeroBuilds_DefaultHeroBuild|remove_var_index=-1}}

Default Build

Automatic Text Formatting

When a string is retrieved by get_string, it undergoes several automatic transformations to convert in-game formatting tags into rich wikitext.

Newlines: "n is converted to a line break ().
HTML Spans: Tags like ... are converted into styled text (e.g., bolded and colored purple).
Game Attribute Icons: Special tags like <Panel class="AbilityPropertyIcon prop_cooldown"> or {g:citadel_inline_attribute:'SpiritDamage'} are replaced with formatted wikitext that includes an icon, a colored label, and a wiki link. If a keyword is not recognized, it will be highlighted in red.
Keybinds: Tags like {g:citadel_binding:'Ability1'} are replaced with their respective text string (e.g., Ability 1). A replacement can be added to the list in case of tags that don't match their string name (e.g. AltCast > alt_cast). The module also cleans up spacing around these replacements for better readability. (Note: If we want to add additional text to the string like "[Ability] button" this needs to be supported by localizations)

search_string

Searches for the unlocalized key corresponding to a given English string, then localizes it to the current language. NOTE: Use sparingly. This function is much slower than get_string and should be avoided when the key is known. For use in other Lua modules, see _search_string.

Parameters

string - English string to search for.
lang_code_override (OPTIONAL) - Overrides the current language to a specific language code.

Examples

From wikitext:

{{#invoke:Lang|search_string|Abrams}}

Abrams

_search_string

This is the internal version of search_string, intended for use by other Lua modules. It provides the core search logic without the wikitext frame overhead or final text processing.

NOTE: This function returns the raw localized string. Unlike the invoked search_string, it does not process newlines ("n). The calling module is responsible for any further processing.

Parameters

label (string) - The English string to search for.
lang_code_override (string, optional) - The language code to translate to.

Example (from another Lua module)

local lang_module = require("Module:Lang")
-- Searches for the Spanish localization of the string "Abrams"
local localized_name = lang_module._search_string("Abrams", "es")

get_lang_code

Outputs the language subpage of the current page (e.g., "en", "es"). Defaults to "en" if the page is not a language subpage.

{{#invoke:Lang|get_lang_code}}

en

local p = {}
local util_module = require("Module:Utilities")
local lang_codes_set = mw.loadJsonData("Data:LangCodes.json")
local dictionary_module = require("Module:Dictionary")

-- Overrides applied to searches by key. Designed to handle edge cases where
-- the expected key does not have a localization entry
local KEY_OVERRIDES = {
    MoveSlowPercent_label = 'MovementSlow_label',
    BonusHealthRegen_label = 'HealthRegen_label',
    BarbedWireRadius_label = 'Radius_label',
    BarbedWireDamagePerMeter_label = 'DamagePerMeter_label',
    BuildUpDuration_label = 'BuildupDuration_label',
    TechArmorDamageReduction_label = 'TechArmorDamageReduction_Label',
    DamageAbsorb_label = 'DamageAbsorb_Label',
    InvisRegen_label = 'InvisRegen_Label',
    EvasionChance_label = 'EvasionChance_Label',
    DelayBetweenShots_label = 'DelayBetweenShots_Label',
}

function get_lang_file(lang_code)
    local file_name = string.format("Data:Lang_%s.json", lang_code)
    local success, data = pcall(mw.loadJsonData, file_name)
    if success then
        return data
    else
        return nil
    end
end

local function process_newlines(text)
    if not text or type(text) ~= "string" then return text end
    -- Replace "n with newline character
    return text:gsub('"n', '\n')
end

local function process_html_tags(text, frame)
    if not text or type(text) ~= "string" then return text end
    
    local replacements = {
	    SpiritIcon = {icon='{{Icon/Purple|[[File:AttributeIconTechShieldHealth.png|link=Spirit Damage|12px]]}}', link='Spirit Damage'},
	    SpiritDamage = {icon='{{Icon/Purple|[[File:AttributeIconTechShieldHealth.png|link=Spirit Damage|12px]]}}', label_color='#bc8ee8', link='Spirit Damage'},
	    SpiritResist = {icon='{{Icon/Purple|[[File:Spirit_Armor.png|link=Damage_Resistance|20px]]}}', label_color='#bc8ee8', link='Damage_Resistance'},
	    FireRate = {icon='{{Icon/White|[[File:Fire_Rate.png|link=Fire Rate|20px]]}}', label_color='#ffefd7', link='Fire Rate'},
	    ReducedFireRate = {icon='{{Icon/White|[[File:Fire_Rate.png|link=Fire Rate|20px]]}}', label_color='#ffefd7', link='Fire Rate'},
	    MeleeDamage = {icon='{{Icon/Brown|[[File:Melee damage.png|link=Melee Damage|20px]]}}', label_color='#ec981a', link='Melee Damage'},
	    WeaponDamage = {icon='{{Icon/Brown|[[File:Damage.png|link=Weapon Damage|20px]]}}', label_color='#ec981a', link='Weapon Damage'},
	    BulletResist = {icon='{{Icon/Brown|[[File:Bullet_Armor.png|link=Damage_Resistance|20px]]}}', label_color='#ec981a', link='Damage_Resistance'},
	    BonusWeaponDamage = {icon='{{Icon/Brown|[[File:Damage.png|link=Weapon Damage|20px]]}}', label_color='#ec981a', link='Weapon Damage'},
	    MoveSpeed = {icon='{{Icon/White|[[File:Move_speed.png|link=Move speed|20px]]}}', label_color='#ffefd7', link='Move speed'},
	    BonusSpiritDamage = {icon='{{Icon/Purple|[[File:AttributeIconTechShieldHealth.png|link=Spirit Damage|12px]]}}', label_color='#bc8ee8', link='Spirit Damage'},
	    BonusFireRate = {icon='{{Icon/White|[[File:Fire_Rate.png|link=Fire Rate|20px]]}}', label_color='#ffefd7', link='Fire Rate'},
	    Heal = {icon='{{Icon/Green|[[File:Health_regen.png|link=Health_Regen|20px]]}}', label_color='#13f278', link='Health_Regen'},
	    BonusMoveSpeed = {icon='{{Icon/White|[[File:Move_speed.png|link=Move speed|20px]]}}', label_color='#ffefd7', link='Move speed'},
	    Spirit = {icon='{{Icon/NoColor|[[File:Spirit_icon.png|link=Spirit Power|20px]]}}', label_color='#bc8ee8', link='Spirit Power'},
	    Stun = {icon='{{Icon/White|[[File:Status_Stun.png|link=Stun|20px]]}}', link='Stun'},
	    SpiritDPS = {icon='{{Icon/Purple|[[File:AttributeIconTechShieldHealth.png|link=Spirit Damage|12px]]}}', label_color='#bc8ee8', link='Spirit Damage'},
	    Healing = {icon='{{Icon/Green|[[File:Health_regen.png|link=Healing|20px]]}}', label_color='#13f278', link='Healing'},
	    Regen = {icon='{{Icon/Green|[[File:Health_regen.png|link=Health_Regen|20px]]}}', label_color='#13f278', link='Health_Regen'},
	    Slow = {icon='{{Icon/White|[[File:MoveSlow.png|link=Movement_Slow|20px]]}}', label_color='#ffefd7', link='Movement_Slow'},
	    SlowResistance = {icon='{{Icon/White|[[File:MoveSlow.png|link=Movement_Slow#Movement_Slow_Resist|20px]]}}', label_color='#ffefd7', link='Movement_Slow#Movement_Slow_Resist'},
	}
   
    -- Process HTML spans
    text = text:gsub('<span class="highlight">(.-)</span>', "<span style= font-weight:bold>%1</span>")
    text = text:gsub('<span class="diminish">(.-)</span>', '<span style="font-style: italic;color:#C0C0C0">%1</span>')
    text = text:gsub('<span class=".-">(.-)</span>', '%1')
    
    -- Process citadel_inline_attribute tags
    text = text:gsub("{g:citadel_inline_attribute:'(.-)'}", function(key)
    	local replacement = replacements[key]
        if replacement then
            return string.format('<span class="no-blue-link" style="text-wrap:nowrap; font-weight:bold; color:%s;">%s [[%s|{{#invoke:Lang|get_string|InlineAttribute_%s}}]]</span>', replacement.label_color, replacement.icon, replacement.link, key)
        else
            return '<span style="color:red;font-weight:bold;border-bottom:1px dotted red;" title="Missing attribute definition - Add \''..key..'\' to local replacements in [Module:Lang]">['..key..']</span>'
        end
    end)
    
    return frame:preprocess(text)
end


function p.get_string(key, lang_code_override, fallback_str, remove_var_index, item_name)
    -- Get frame object (either passed directly or via first argument)
    local frame
    if type(key) == "table" and key.args then
        frame = key
        key = frame.args[1]
        lang_code_override = frame.args["lang_code_override"]
        fallback_str = frame.args["fallback_str"]
        remove_var_index = frame.args["remove_var_index"]
        item_name = frame.args["item_name"]
    else
        frame = mw.getCurrentFrame()
    end

    -- Determine lang_code if not overridden
    local lang_code = lang_code_override
    if (lang_code == '' or lang_code == nil) then
        lang_code = p.get_lang_code()
    end

    -- Retrieve lang data
    local data = get_lang_file(lang_code)
    if (data == nil) then
        return string.format("Lang code '%s' does not have a json file", lang_code)    
    end
    
    -- Localize
    local label = data[KEY_OVERRIDES[key] or key]
    if (label == nil) then
        -- Apply fallback (without HTML processing for fallback)
        local fallback_tooltip = frame:expandTemplate{title = "MissingValveTranslationTooltip"}
        local fallback
        if (fallback_str == 'en') then
            fallback = p.get_string(key, 'en', key .. fallback_tooltip, remove_var_index, item_name)
        elseif fallback_str == 'dictionary' then
            return dictionary_module.translate(key, lang_code_override)
        elseif fallback_str ~= nil then
            fallback = fallback_str
        else
            return ''
        end
        return fallback .. fallback_tooltip
    end
    
    -- Apply remove_var
    if (remove_var_index ~= nil) then 
        label = util_module.remove_var(label, remove_var_index)
    end
    
    -- Process variables if item_name is provided
    if item_name and item_name ~= '' then
        local item_data_module = require('Module:ItemData')
        label = label:gsub("{s:([^}]+)}", function(variable_name)
            -- Get the value from ItemData
            local value = item_data_module.get_prop({args = {item_name, variable_name}})
            
            -- If value exists, remove non-number symbols (but keep + and -)
            if value then
                value = value:gsub("[^0-9+-]", "")
                -- Return empty string if nothing left, otherwise return the filtered value
                return value ~= "" and value or variable_name
            else
                return variable_name -- Fallback to variable name if value not found
            end
        end)
    end
    
    -- Process HTML and return as "raw" HTML
    label = process_newlines(label)
    label = process_html_tags(label, frame)
    -- Create HTML object for safe output
    local html = mw.html.create()
    html:wikitext(label)
    return tostring(html)
end

-- Search for a localized string using its English label
p.search_string = function(frame)
    local label = frame.args[1]
    local lang_code_override = frame.args[2]

    local result = p._search_string(label, lang_code_override)
    result = process_newlines(result)
    return result
end

-- search_string, but for internal use by other modules
p._search_string = function(label, lang_code_override)
    lang_code = lang_code_override
    if (lang_code == '' or lang_code == nil) then
        lang_code = p.get_lang_code()
    end

    -- Load the language files
    local data_en = get_lang_file('en')  -- English data
    local data_lang = get_lang_file(lang_code)  -- Target language data

    if (data_lang == nil) then
        error("Lang code '%s' does not have a json file", lang_code)    
    end
    
    -- Search for the key in the English data
    local key = nil
    for k, v in pairs(data_en) do
        if v == label then
            key = k  -- Find the key corresponding to the label
            break
        end
    end

    -- Default to input label if localized string is not found
    if (key == nil) then
        return label
    end
    if (data_lang[key] == nil) then
        return label
    end

    return data_lang[key]
end

p.get_lang_code = function()
    local title = mw.title.getCurrentTitle()
    local lang_code = title.fullText:match(".*/(.*)$")
    
    if lang_code == nil or lang_codes_set[lang_code] == nil then
        return 'en'    
    end
        
    return lang_code
end

return p

Module:LangGive feedback

Contents

Overview

Functions

get_string

Parameters

Internal Logic & Fallbacks

Examples

Strings with Variables

Examples for fallback_str

Examples for remove_var_index

Automatic Text Formatting

search_string

Parameters

Examples

_search_string

Parameters

Example (from another Lua module)

get_lang_code

Navigation menu