Module:Lang/doc: Difference between revisions

(5 intermediate revisions by 3 users not shown)

Line 1:

=Overview=

~~overview~~

This module serves as the primary interface for retrieving and formatting localized game text from the <code>Data:Lang_*.json</code> 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 to the current language, i.e. [[Data:Lang_en.json]] for ~~english~~.

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 ~~function~~ referenced in another Data page, ~~use~~ the <code>~~process_variables~~</code> ~~function from [[Module:Utilities]] instead~~.

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

===Parameters===

* '''key''' - Key string to localize

* '''key''' - Key string to localize.

* '''lang_code_override''' (OPTIONAL) - Overrides the current language to a specific language code

* '''lang_code_override''' (OPTIONAL) - Overrides the current language to a specific language code.

* '''fallback_str''' (OPTIONAL) - Passing <code>en</code> causes it to return the ~~english~~ localization ~~if it can't be localized to the current language~~. Passing any other string causes it to return that string ~~if it can't be localized~~. Both have [[Template:MissingValveTranslationTooltip]] appended. ~~Use this very often as some keys are not yet localized in every language by the game.~~ Passing <code>dictionary</code> causes it to return ~~the~~ translation via [[~~Data~~:Dictionary]] ~~if it can't be~~ localized. If parsing the fallback_str from ~~lua and~~ is computationally expensive ~~(i.e. add_space_before_cap)~~, consider using fallback outside this function so it only computes when needed.

* '''fallback_str''' (OPTIONAL) - Specifies behavior when a key is not found in the target language.

** Passing <code>en</code> 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 <code>dictionary</code> 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 <code>{s:variable}</code> placeholders. It will fetch the corresponding property from [[Module:ItemData]] to fill in the variable.

NOTE: ~~Optional~~ parameters ~~are ideally~~ named ~~when not all parameters are provided~~, ~~though named~~ parameters ~~can only~~ be passed ~~by invoke~~, ~~and~~ not ~~internal lua calls~~.

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., <code>p.get_string(key, nil, 'en')</code>).

===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 <code>MoveSlowPercent_label</code> is requested, the module will internally use the value for <code>MovementSlow_label</code> to handle this known inconsistency.

* '''Post-value Label Fallback:''' If a key ending in <code>_label</code> is not found, it will automatically try again with a key ending in <code>_postvalue_label</code>.

* '''String Parsing:''' If a retrieved string contains <code>|</code> or <code>#</code>, the function will automatically use only the text that comes after the final instance of that character.

===Examples===

Line 27:

Line 39:

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

====Strings with Variables====

For strings containing <code>{s:variable}</code>, provide the <code>item_name</code>:

'''Example:'''

<code><nowiki>{{#invoke:Lang|get_string|upgrade_target_stun_desc|item_name=Knockdown}}</nowiki></code>

→ {{#invoke:Lang|get_string|upgrade_target_stun_desc|item_name=Knockdown}}

Without <code>item_name</code>, variables won't be filled:

<code><nowiki>{{#invoke:Lang|get_string|upgrade_target_stun_desc}}</nowiki></code>

→ {{#invoke:Lang|get_string|upgrade_target_stun_desc}}

Line 64:

Line 87:

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

==Automatic Text Formatting==

When ~~calling~~ by ~~internal modules~~, ~~the parameters cannot be named, and therefore have~~ to be in ~~order~~. ~~Unused parameters before the last used parameter should be~~ <code>~~nil~~</code>. ~~Such as,~~ <code>.~~get_string~~('~~hero_atlas~~', ~~nil~~, 'en')</code>

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

* '''Newlines:''' <code>"n</code> is converted to a line break (<code><br/></code>).

* '''HTML Spans:''' Tags like <code><span class="highlight_spirit">...</span></code> are converted into styled text (e.g., bolded and colored purple).

* '''Game Attribute Icons:''' Special tags like <code><Panel class="AbilityPropertyIcon prop_cooldown"></code> or <code>{g:citadel_inline_attribute:'SpiritDamage'}</code> 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 <code>{g:citadel_binding:'Ability1'}</code> 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. <code>AltCast</code> > <code>alt_cast</code>). 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~~, always~~ use ~~'''get_string''' instead where plausible, as it has time complexity O(1) compared to search_string's O(10~~,~~000)~~.

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 <code>get_string</code> and should be avoided when the key is known. For use in other Lua modules, see <code>_search_string</code>.

===Parameters===

* '''string''' - English string to search for

* '''string''' - English string to search for.

* '''lang_code_override''' (OPTIONAL) - Overrides the current language to a specific language code.

===Examples===

Line 78:

Line 106:

<pre>{{#invoke:Lang|search_string|Abrams}}</pre>

==_search_string==

This is the internal version of <code>search_string</code>, 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 <code>search_string</code>, it does '''not''' process newlines (<code>"n</code>). 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)===

<pre>

local lang_module = require("Module:Lang")

-- Searches for the Spanish localization of the string "Abrams"

local localized_name = lang_module._search_string("Abrams", "es")

</pre>

==get_lang_code==

~~Output~~ the language subpage of the current page

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

<pre>{{#invoke:Lang|get_lang_code}}</pre>

Module:Lang/doc: Difference between revisionsGive feedback

Gammaton32 (talk | contribs)

@@ Line 1: / Line 1: @@
 =Overview=
-overview
+This module serves as the primary interface for retrieving and formatting localized game text from the <code>Data:Lang_*.json</code> 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 to the current language, i.e. [[Data:Lang_en.json]] for english.
+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 function referenced in another Data page, use the <code>process_variables</code> function from [[Module:Utilities]] instead.
+Note: If you need to get a string that uses a value referenced from another Data page, pass the <code>item_name</code> parameter to <code>get_string</code>.
 ===Parameters===
-* '''key''' - Key string to localize
+* '''key''' - Key string to localize.
-* '''lang_code_override''' (OPTIONAL) - Overrides the current language to a specific language code
+* '''lang_code_override''' (OPTIONAL) - Overrides the current language to a specific language code.
-* '''fallback_str''' (OPTIONAL) - Passing <code>en</code> causes it to return the english localization if it can't be localized to the current language. Passing any other string causes it to return that string if it can't be localized. Both have [[Template:MissingValveTranslationTooltip]] appended. Use this very often as some keys are not yet localized in every language by the game. Passing <code>dictionary</code> causes it to return the translation via [[Data:Dictionary]] if it can't be localized. If parsing the fallback_str from lua and is computationally expensive (i.e. add_space_before_cap), consider using fallback outside this function so it only computes when needed.
+* '''fallback_str''' (OPTIONAL) - Specifies behavior when a key is not found in the target language.
+** Passing <code>en</code> 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 <code>dictionary</code> 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 <code>{s:variable}</code> placeholders. It will fetch the corresponding property from [[Module:ItemData]] to fill in the variable.
-NOTE: Optional parameters are ideally named when not all parameters are provided, though named parameters can only be passed by invoke, and not internal lua calls.
+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., <code>p.get_string(key, nil, 'en')</code>).
+===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 <code>MoveSlowPercent_label</code> is requested, the module will internally use the value for <code>MovementSlow_label</code> to handle this known inconsistency.
+* '''Post-value Label Fallback:''' If a key ending in <code>_label</code> is not found, it will automatically try again with a key ending in <code>_postvalue_label</code>.
+* '''String Parsing:''' If a retrieved string contains <code>|</code> or <code>#</code>, the function will automatically use only the text that comes after the final instance of that character.
 ===Examples===
@@ Line 27: / Line 39: @@
 {{#invoke:Lang|get_string|CitadelHeroStats_Weapon_Falloff|lang_code_override=es}}
+====Strings with Variables====
+For strings containing <code>{s:variable}</code>, provide the <code>item_name</code>:
+'''Example:'''
+<code><nowiki>{{#invoke:Lang|get_string|upgrade_target_stun_desc|item_name=Knockdown}}</nowiki></code>
+→ {{#invoke:Lang|get_string|upgrade_target_stun_desc|item_name=Knockdown}}
+Without <code>item_name</code>, variables won't be filled:
+<code><nowiki>{{#invoke:Lang|get_string|upgrade_target_stun_desc}}</nowiki></code>
+→ {{#invoke:Lang|get_string|upgrade_target_stun_desc}}
@@ Line 64: / Line 87: @@
 {{#invoke:Lang|get_string|Citadel_HeroBuilds_DefaultHeroBuild|remove_var_index=-1}}
+==Automatic Text Formatting==
-When calling by internal modules, the parameters cannot be named, and therefore have to be in order. Unused parameters before the last used parameter should be <code>nil</code>. Such as, <code>.get_string('hero_atlas', nil, 'en')</code>
+When a string is retrieved by <code>get_string</code>, it undergoes several automatic transformations to convert in-game formatting tags into rich wikitext.
+* '''Newlines:''' <code>"n</code> is converted to a line break (<code><br/></code>).
+* '''HTML Spans:''' Tags like <code><span class="highlight_spirit">...</span></code> are converted into styled text (e.g., bolded and colored purple).
+* '''Game Attribute Icons:''' Special tags like <code><Panel class="AbilityPropertyIcon prop_cooldown"></code> or <code>{g:citadel_inline_attribute:'SpiritDamage'}</code> 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 <code>{g:citadel_binding:'Ability1'}</code> 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. <code>AltCast</code> > <code>alt_cast</code>). 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, always use '''get_string''' instead where plausible, as it has time complexity O(1) compared to search_string's O(10,000).
+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 <code>get_string</code> and should be avoided when the key is known. For use in other Lua modules, see <code>_search_string</code>.
 ===Parameters===
-* '''string''' - English string to search for
+* '''string''' - English string to search for.
+* '''lang_code_override''' (OPTIONAL) - Overrides the current language to a specific language code.
 ===Examples===
@@ Line 78: / Line 106: @@
 <pre>{{#invoke:Lang|search_string|Abrams}}</pre>
 {{#invoke:Lang|search_string|Abrams}}
+==_search_string==
+This is the internal version of <code>search_string</code>, 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 <code>search_string</code>, it does '''not''' process newlines (<code>"n</code>). 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)===
+<pre>
+local lang_module = require("Module:Lang")
+-- Searches for the Spanish localization of the string "Abrams"
+local localized_name = lang_module._search_string("Abrams", "es")
+</pre>
 ==get_lang_code==
-Output the language subpage of the current page
+Outputs the language subpage of the current page (e.g., "en", "es"). Defaults to "en" if the page is not a language subpage.
 <pre>{{#invoke:Lang|get_lang_code}}</pre>
 {{#invoke:Lang|get_lang_code}}