[GUIDE] - Handling multiple languages in UI mods
Mr2150
Member Posts: 1,170
Having released a few mods for the UI now, one challenge I've found over and over is how best to incorporate multiple languages into the mod in a simple and effective way.
Currently there are several ways I've seen to do this, for example, export the L_xx_YY.lua files using NI and then edit the additional strings directly into the files, create a unique M_* lua file for each language that a mod supports and get the user to drop the correct file in when they are installing, or avoid using additional strings and use symbols and/or graphics in their place etc.
None of these feels ideal for UI mods and it can be very difficult for the user if they want to uninstall the mod later. Also, I'm generally not in favour of editing system files if I don't have to.
For my latest mod, I will be releasing with support for approx. 6 or 7 languages and I developed a very simple solution, and I thought it might be an idea to share the idea so others can utilise it if they want.
The two English strings that TestMod uses are:
"The Sun"
"The Moon"
First, we need to find out the language that the user interface is set to. One good thing about changing languages in game is that it requires a restart for the new language to be implemented. When you restart, the game also reloads all LUA files, therefore a simple function in a M_* lua file that checks the current language and sets the appropriate strings will work perfectly.
So, let's create a new M_*.lua file and we'll call it M_TMlang.lua indicating it is the TestMod language file.
In this lua file, let's add a new function:
Now to retrieve the current language, we can use this:
This will return the language code set in the baldur.lua file, eg fr_FR for French. So, let's add that to the function:
So far, for TestMod I've been able to collect translations in French and Italian, as well as English which I will want to be the default.
Now we need to check 'currentlanguage' against these translations. To do that, a simple if statement will suffice.
If you have more languages, then just add an 'elseif' block for each additional language you have making sure to check for the correct language code.
Next, we need to define our strings. To do this, we will put them into a table:
If you have more strings just make sure that each line ends in a comma (apart from the last). You could use a more complicated table that uses the language code as part of the key however I found that for updating and editing the language strings it is much simpler to keep it clearer and separated.
The name of the table (TMStrings) and the unique keys (TM_Sun, and TM_Moon) are then used in place of the string, for example, in a label, you might use: text lua "TMStrings.TM_Sun" to display "The Sun" or the equivalent in the other languages.
So putting it together we end up with:
Now, we just need to call this function at the right time, usually the best place to do this is in the onopen of a menu, using findTestModStrings() like this:
Once that function is called the strings are set for the remainder of the game session and can be used wherever needed. You could call it in the onopen of the 'START' menu so that the strings are available everywhere.
When you need to add more strings or more languages just add the appropriate extra 'elseif' blocks and line items.
And that's it.
*UPDATE*
This approach works great if you want to call the function at a specific time in the UI.menu during a UI mod, eg you are already editing the UI.menu file so calling a function is just another line to add - however it isn't actually necessary. You can adapt the approach, for example:
Let's say you want to give the UI access to certain strings but your mod focus is not the UI so you want to avoid editing it unless necessary.
Taking what's been done above, all you would need to do is remove the function line from the start, and the last 'end' from the very end. This will result in the M_TMlang.lua file being loaded and automatically called on session start. The strings are set and you've not had to edit the UI.menu
Comments, feedback and suggestions all welcome!
Currently there are several ways I've seen to do this, for example, export the L_xx_YY.lua files using NI and then edit the additional strings directly into the files, create a unique M_* lua file for each language that a mod supports and get the user to drop the correct file in when they are installing, or avoid using additional strings and use symbols and/or graphics in their place etc.
None of these feels ideal for UI mods and it can be very difficult for the user if they want to uninstall the mod later. Also, I'm generally not in favour of editing system files if I don't have to.
For my latest mod, I will be releasing with support for approx. 6 or 7 languages and I developed a very simple solution, and I thought it might be an idea to share the idea so others can utilise it if they want.
Guide
Let's say we are releasing a UI mod with 2 new strings. We will be calling our mod 'TestMod' and it has some UI.menu changes and a M_*.lua file associated with it.The two English strings that TestMod uses are:
"The Sun"
"The Moon"
First, we need to find out the language that the user interface is set to. One good thing about changing languages in game is that it requires a restart for the new language to be implemented. When you restart, the game also reloads all LUA files, therefore a simple function in a M_* lua file that checks the current language and sets the appropriate strings will work perfectly.
So, let's create a new M_*.lua file and we'll call it M_TMlang.lua indicating it is the TestMod language file.
In this lua file, let's add a new function:
function findTestModStrings()
end
Now to retrieve the current language, we can use this:
currentlanguage = Infinity_GetINIString('Language', 'Text', '')
This will return the language code set in the baldur.lua file, eg fr_FR for French. So, let's add that to the function:
function findTestModStrings()
currentlanguage = Infinity_GetINIString('Language', 'Text', '')
end
So far, for TestMod I've been able to collect translations in French and Italian, as well as English which I will want to be the default.
Now we need to check 'currentlanguage' against these translations. To do that, a simple if statement will suffice.
if currentlanguage == "it_IT" then
-- Italian is selected language
elseif currentlanguage == "fr_FR" then
-- French is selected language
else
-- no matching language or English is selected, so default to en_US for the extra strings
end
If you have more languages, then just add an 'elseif' block for each additional language you have making sure to check for the correct language code.
Next, we need to define our strings. To do this, we will put them into a table:
TMStrings = {
TM_Sun = "The Sun",
TM_Moon = "The Moon"
}
If you have more strings just make sure that each line ends in a comma (apart from the last). You could use a more complicated table that uses the language code as part of the key however I found that for updating and editing the language strings it is much simpler to keep it clearer and separated.
The name of the table (TMStrings) and the unique keys (TM_Sun, and TM_Moon) are then used in place of the string, for example, in a label, you might use: text lua "TMStrings.TM_Sun" to display "The Sun" or the equivalent in the other languages.
So putting it together we end up with:
function findTestModStrings()
currentlanguage = Infinity_GetINIString('Language', 'Text', '')
if currentlanguage == "it_IT" then
-- Italian is selected language
TMStrings = {
TM_Sun = "Il Sole",
TM_Moon = "La Luna"
}
elseif currentlanguage == "fr_FR" then
-- French is selected language
TMStrings = {
TM_Sun = "Le Soleil",
TM_Moon = "La Lune"
}
else
-- no matching language or English is selected, so default to en_US for the extra strings
TMStrings = {
TM_Sun = "The Sun",
TM_Moon = "The Moon"
}
end
end
Now, we just need to call this function at the right time, usually the best place to do this is in the onopen of a menu, using findTestModStrings() like this:
onopen
"
findTestModStrings()
"
Once that function is called the strings are set for the remainder of the game session and can be used wherever needed. You could call it in the onopen of the 'START' menu so that the strings are available everywhere.
When you need to add more strings or more languages just add the appropriate extra 'elseif' blocks and line items.
And that's it.
*UPDATE*
This approach works great if you want to call the function at a specific time in the UI.menu during a UI mod, eg you are already editing the UI.menu file so calling a function is just another line to add - however it isn't actually necessary. You can adapt the approach, for example:
Let's say you want to give the UI access to certain strings but your mod focus is not the UI so you want to avoid editing it unless necessary.
Taking what's been done above, all you would need to do is remove the function line from the start, and the last 'end' from the very end. This will result in the M_TMlang.lua file being loaded and automatically called on session start. The strings are set and you've not had to edit the UI.menu
Comments, feedback and suggestions all welcome!
Post edited by Mr2150 on
12
Comments