Adding Localisation

This guide covers how to work with localised strings and edit existing ones.

Any time text needs to be displayed to the player, it needs to be localised to other languages. Because of this, we have a database of strings for dialogue lines and UI text. This database connects a handle to different localised versions of that string for each language that we support.

For the base game, this database is converted into a binary file with the .loca extension. However, you are able to mod existing strings in the game, as well as create new ones, by creating an XML file in your own mod folder. This guide will show you how to do that.

Setting Up

Navigate to .../Data/Mods/<YourMod>.

Create a folder named Localization.

Inside this new Localization folder, create a folder for the language you’ll be adding to. For example, a new folder called Japanese.

You can see examples of language names in ...Data/Localization. Here’s a list of the language names available at the time of writing:

• BrazilianPortuguese
• Chinese
• ChineseTraditional
• English
• French
• German
• Italian
• Japanese
• Korean
• LatinSpanish
• Polish
• Russian
• Spanish
• Turkish
• Ukrainian

In the new language directory, create a .xml file. Name the XML file after the language you’re creating the mod for – for example, English would be english.xml and would be located here:

.../Data/Mods/<YourMod>/Localization/English/english.xml

All .xml files in this directory will be processed, regardless of their name.

Inside your new .xml file, paste this skeleton:

<?xml version="1.0"?>
 <contentList date="18/07/2023 18:07">
  <!-- <content contentuid="h000000000000000000000000000000000000" version="1">Your line here.</content> -->
 </contentList>

There are additional rules for gendered languages, which are covered below.

ⓘ Important! Any changes made to localisation XML files won’t be picked up by the game/Editor until you’ve loaded a new module or restarted the game/Editor or used the command reloadLoca in the debug console.

Details

From the skeleton code you copy-and-pasted above, you can remove the XML comment markers (<!-- and -->) to start creating your own localised lines.

Lines follow this format:

<content contentuid="<translated string handle>" version="<version number>">Your new string here</content>

<translated string handle> is the ID used by the game to fetch your localised line. This will be referred to as the TranslatedStringHandle.

• Custom TranslatedStringHandles can be any alphanumeric identifier, with no whitespace.
• Existing TranslatedStringHandles are of the format h<uuid> (e.g. h1587638ag320fg40a1g9566g82783d951ea3). This is because they are generated by internal tooling based on the content of the string. You have no such limitations, so they can be any identifier you’d like.

<version number> is the version of your string, in case you need to update your own line or want to update an existing line in the game.

Your string can have HTML character entities embedded in it like < or i>.

Using the above information, here are two examples:

<content contentuid="MyNewString" version="1">Hello world!</content>

<content contentuid="h1587638ag320fg40a1g9566g82783d951ea3" version="2">This line is now overridden.</content>

You can change strings from the base game by using that line’s TranslatedStringHandle in your XML file.

Localised Strings for Spells, Statuses, and Other Stats Objects

When you create a new spell, status, or other stats object and fill out the row’s DisplayName or other localised field, the Editor will try to generate a TranslatedStringHandle.

If it fails to create loca, instead of a TranslatedStringHandle in the file, it will just say ls::TranslatedStringRepository::s_HandleUnknown.

To actually add localised names for your stats objects, you’ll need to first create your Localization file following the steps in the Setting Up section, and add your string there. Then, there are two ways for you to add the new line to the stats object:

1. Manually add the row to your stats object data file, or
2. Add the DisplayName (or other localised field) in the Stats Editor.

Manually Adding the Row to Your Stats Object Data File

Open the generated stats data file.

Example: .../Data/Public/<YourMod>/Stats/Generated/Data/Spell_Projectile.txt

Add a row to your stats object: data "DisplayName" "<TranslatedStringHandle>;<version>"

The TranslatedStringHandle should be the one you created earlier for this purpose.

Adding the DisplayName (or Other Localised Field) in the Stats Editor

You can also add the DisplayName (or other localised field) in the Stats Editor, which will add the row for you but with ls::TranslatedStringRepository::s_HandleUnknown instead of a real handle.

Then, replace that string with your actual TranslatedStringHandle.

The format here is <TranslatedStringHandle>;<version>.

Gender-/Identity-Specific Lines

Many languages change grammar or nouns depending on the gender you’re speaking to, or as. We support three grammatical genders for each (speaker and listener): Male, Female, and Gender Neutral. By default, the lines in your localisation file are assumed to be Male speaking to Male.

Speaking As Another Gender/Identity

1. Create a folder inside the language folder called Gender.
   • For example: .../Data/Mods/<YourMod>/Localization/French/Gender
2. Within the Gender folder, create a folder for either Female or Neutral.
   • The default is Male, so overrides are only necessary for Female or Neutral.
3. Within the Female or Neutral folder, you can now create a .xml file with your lines as that identity, following Steps 4 and 5 from the Setting Up section.

Speaking To Another Gender/Identity

To specify which gender the speaker is speaking to, you can add a suffix to the .xml file’s name. The default is still assumed to be Male in this case.

• If the file name ends with _to_F, the lines in that file will be used when speaking to characters with Female identities.
  • e.g. .../Data/Mods/<YourMod>/Localization/French/Gender/Female/french_to_F.xml would be for female French speakers speaking to female characters.
• If the file name ends with _to_X, the lines in that file will be used when speaking to characters with Neutral identities.
  • e.g. .../Data/Mods/<YourMod>/Localization/French/french_to_X.xml would be for male French speakers speaking to gender-neutral characters.

Example Folder Structure

…/Localization/
    /French/
        /Gender/
        /Female/
            french.xml (Female speaker speaking to Male speaker)
            french_to_F.xml (Female speaker speaking to Female speaker)
        french.xml (Male speaker speaking to Male speaker)
        french_to_F.xml (Male speaker speaking to Female speaker)