DLC - Dynamic Localization for RAID: World War II

Have you ever been making a mod for RAID: World War II and found yourself wanting to change your custom localisation strings at runtime without needing to rely on macros or swapping out the string IDs? If so, your mod needs some DLC (Dynamic Localization)!

What is Dynamic Localization?

It is Dynamic

• Instead of the existing static localization system, in which every localised string is only initialized with a single, unchanging string, DLC rejects this rigid structure, in favour of a flexible, dynamic system of allowing multiple possibilities!

It is Local

• Instead of requiring all mod authors to reimplement the DLC functionality in all their mods (with lots of overhead from all the identical overrides), DLC is intended to be used as a dependency. This allows other mods to make use of it, whilst the busywork of DLC is contained locally.
• DLC is also Local in the sense that it is entirely clientside!
• Furthermore, as DLC is still very niche functionality (for now), containing the functionality of DLC locally within this mod instead of adding it via a PR to SuperBLT prevents it from impacting those who do not want it.
  • That said, DLC will soon enough take the world by storm, and, give or take a few years, every game will proudly announce that it has DLC!

And, but most importantly, it is Ization

• For it is the act, the process, and the result of both doing the dynamic and local thing, and of making something dynamically and locally!

Technical info for mod authors

What exactly does DLC do?

The background context (RAID-SuperBLT's localization system)

Spoiler!

RAID-SuperBLT itself has a custom LocalizationManager class (overriding the base game's instance of it), allowing it to use localization data defined by mod authors (said data is all loaded and added to a _custom_localization table, containing key-value pairs of <string ID (string), localized text (string)>). So, when a string needs to be localized, it first checks if there's an entry for the ID in the _custom_localization table, returning the localized string from there if present (after applying macros on the placeholders in that string) - otherwise, it will fall back on the base game's localization manager (loading the default localization string).

This system works, but it has its drawbacks. Firstly, there is no easy way to change the value of an entry in the _custom_localization table - meaning that whatever string was passed to the table upon initialization usually cannot be changed later on without manually re-running a function to replace an entry in the table. Secondly, whilst you could try to change strings at runtime via writing a custom macro, it appears that nested macros may not be supported by RAID's internal macro system, and attempting to implement something Wacky™️ like DLC via that system would not be very user-friendly.

Okay, so what does DLC do differently?

The default system only allows one to use Strings as values in the localization table. DLC extends this by allowing the values to be one of three datatypes! You can use:

• Strings
  • Same behaviour as in vanilla RAID-SuperBLT
• Tables/arrays
  • DLC will pick a value at random from the table, and perform the appropriate action on that value.
  • However, if you specify a fstring= value in your table, you can use DLC for string formatting.
    • the fstring value will be treated as the format string (containing placeholders), the rest of the table will be used to generate the values inserted into it (see https://www.luadocs.com/docs/functions/string/format)
• Zero/One-argument functions
  • DLC will run that function each time the localized string needs localization, and will perform the appropriate action on the returned value.
  • (it will pass the original string ID as an argument to that function)

And yes, DLC supports comically-excessive nesting of these datatypes!

• Tables may contain Strings, zero-argument functions, or more tables!
• Zero/One-argument functions may return Strings, tables, or other zero/one-argument functions!
• Any combo works, as long as it eventually returns a String.

And how does that benefit mod authors?

Variety is the spice of life. Add some more variety to the UX of your mod via the magic of DLC!

How would one use DLC in their RAID-SuperBLT mod?

Check out Woher kommt Wolfgang? for an example of DLC in action!

You can add some DLC functionality to your mod like so:

local function _someExampleDLCFunction()
  if math.random() > 0.75 then
    return "raid deez nutz lmao gottem"
  end
  return "raid ww2 my beloved"
end

local function _otherExampleDLCFunction(original_id)
  return "I love to ".. original_id .. " in raid ww2!"
end

Hooks:Add("LocalizationManagerPostInit", "Example_DLC_Localization", function(loc)
  LocalizationManager:add_localized_strings({
    menu_main_title = _someExampleDLCFunction,
    footer_back = {"My $BTN_CANCEL key broke", "take me home", "no thanks"},
    menu_play = _otherExampleDLCFunction,
    menu_options = {{"bruh","woah","wow"},"cool",{"jank","malarkey","hax"},fstring={"%s %s %s","%s, %s %s!","%s! %s %s."}},
  })
end)

Of course, you still need to add DLC as a dependency to your mod (otherwise things will end badly!)

How do I add DLC as a dependency to my RAID-SuperBLT mod?

Add this to your mod's supermod.xml:

<dependencies>
  <dependency
    name="DLC - Dynamic Localization"
    meta="https://github.com/11BelowStudio/RAID-DynamicLocalization/releases/latest/download/meta.json"
    download_url="https://github.com/11BelowStudio/RAID-DynamicLocalization/releases/latest/download/RAID-DynamicLocalization.zip"
  /> 
</dependencies>

Do I need to give credit or anything if I make a mod which uses DLC as a dependency?

DLC - Dynamic Localization (DLC) is released under the MIT license - so you don't need to faff around with credit or license malarkey if you just add DLC as a dependency to your mod (the malarkey only happens if you were to directly include DLC's functionality within your mod).

That said, you are encouraged to take pride in your choice of dependencies, and announce to the whole world that your mod contains DLC!