How to add Localization to your mod

Here you will learn how to add Localization to your mod.

Foreword

As far I have not found anything which really explaining the Localization of a Mod, there is a Github post about it, but it is not longer working, and is not really well explained, so here is my Guide for it.
In this Guide I will try to explain to you how to make translations possible for your mod.
I will try to explain it in detail, as best as I can, of course.

If you are just here for translating a mod, head over to:
"Create a Translation for a mod"

In this Guide, I want to give my Smaller Hydrogen Block a Localization String, for the Display Name, and the Description.

What are Localization Strings?
Localization Strings are tags that we can put into the name of Items, Blocks, or whatever, and with the magic of the Localization file, those will be changed automatically into the correct Text, for the chosen language if supported.
It is a method to make it possible to translate your Items, Blocks, or whatever, as the Translator can just add a custom file for his Language to his mod, in which all Localization Strings are stored, this file only needs to get updated as soon as the mod adds another Block, Item, expanding its Localization String, or whatever.
But the mod needs to be set up for this.

Required

A Text Editor of your choice.

• Most, if not all, are capable of editing .resx, and .sbl files
  
• For this Guide, I will offer two ways of editing the .resx files.
  The first will be with Visual Studio Community 2022, which can be found here: https://visualstudio.microsoft.com/de/vs/
  And the second will be with a Text Editor of your choice.

An empty .resx file (Download[drive.google.com])
An empty .sbl file (Download[drive.google.com])

The BCP 47 Code for the language you want to translate your mod to, or you want to define as the default language of your mod.
Those can be found here: https://learn.microsoft.com/en-us/openspecs/office_standards/ms-oe376/6c085406-a698-4e12-9d4d-c3b0ee3dbc4a

Limitations of the Localization String

.resx File

A Localization String needs to have a specific prefix, which is:

Prefix	For what
DisplayName_	<DisplayName></DisplayName>
Description_	<Description></Description>
Item_	<ExtraInventoryTooltipLineId></ExtraInventoryTooltipLineId>

If I find more, I will add them here.

• You can not use spaces inside the Localization String, but you can separate it with a simple "_".
  
• I Suggest you put a unique tag behind the prefix, this minimizes the risk of accidentally overwriting someone else's Localization String, just like: Prefix_Tag_String

---

.sbc file

If you want to use your Localization String, each Localization String needs to be inside "{LOC:}".
"{LOC:}", is the way the Game identifies your string as a custom localization.
The usage is simple:

{LOC:Prefix_Tag_String}

Setup

Download the .resx, and .sbl files above, and place them into the following folder:

(your mod name)\Data\Localization\MyTexts.resx
(your mod name)\Data\Localization\MyTexts.sbl

They are named, "MyTexts", and Those are basically just the names for your files, but those names are the ones the devs gave their files.

For better compatibility, and as I normally tend to give every file I have worked on my tag.
In this guide, I am naming them "fta_Strings", but you can call them whatever you want to.
But I would not recommend leaving the default name.

You can use a sub-folder at this stage, which further minimizes the risk of overwriting someone else's files.
I will put mine into the folder "fta", which basically is my tag for everything I am doing. So my files are located here:

(mod name)\Data\Localization\fta\fta_Strings.resx
(mod name)\Data\Localization\fta\fta_Strings.sbl

Setup the .sbl file

This is the Definition file for your .resx file, and each .resx file needs to have its own .sbl file.
The game is looking for every .sbl file and works with it.

Open up the .sbl file, and you will find these:

---

<Language>us-US</Language>

• This is the BCP 47 Code of your Language, you can find them in the Section "Required".
  Change this to the default language you are working with, for my example, and because it is a common practice to work with English as the default language, I will keep it in English. You can set up a second file for your main language later if needed, have a look at the section: "Create a Translation for a mod".

<Default>true</Default>

• This should be true for only one Language in your mod. This will be the language that is chosen if the language the player is using was not found. I am using the English file for this, as stated above, so I leave it set to "true". If you are just here for a Translation, turn it to "false"

<ResXName>fta_Strings.resx</ResXName>

• This is the name of the .resx file this definition is for, the extension needs to be included.

<Id>12345</Id>

• I have not yet sawed any differences, but I set it to a number of my choice, and keep it for every translation file for the mod. I have set this to "92000".

Setup the .resx file (Visual Studio Community 2022)

Without lying, this is, by far, the easiest method.
Open the .resx file with Visual Studio Community 2022.

It should look like this:

---

How to use it:
Each column contains one Localization String, and the text shown in-Game, like:

---

For this Guide, I will go with two Columns, one for the Display Name, and one for the Description.
You can add another Column, by just selecting the next Column and start typing.

In the end, mine looks like this:

Setup the .resx file (Text Editor)

Open up the .resx file in any Text Editor of your Choice.

You will see a lot of text, ignore it, and head down to the bottom.
Until you see:

  </resheader>
</root>

</root> - Marks the end of the file.

You need to put your localizations in between </resheader> and </root>.
To define a new Localization String, you need to type in:

  <data name="String" xml:space="preserve">
    <value>Text</value>
  </data>

Replace "String" with the Localization String of your Choice.
Replace "Text" with the Text which you want to get shown in-Game.

---

For this Guide, I will go with two Localization Strings, one for the Display Name, and one for the Description.
You can add another Localization String, by just adding another below an existing one.

At the end, mine looks like this:

  </resheader>

  <data name="DisplayName_fta_HydrogenTankSmaller" xml:space="preserve">
    <value>Smaller Hydrogen Tank</value>
  </data>
  <data name="Description_fta_HydrogenTankSmaller" xml:space="preserve">
    <value>This Tank is smaller than the other one.</value>
  </data>
</root>

Setup the .sbc file

Now we add the Localization String to your Mod.
Open up your .sbc file, in which you will find the Object you want to translate.

For the Display name, you go to:

<DisplayName></DisplayName>

Here you will need to type in the Localization String for your Display Name, which you declared earlier.

For the Description, you go to:

<Description></Description>

Here you will need to type in the Localization String for your Description, as you declared earlier.

Do NOT forget {LOC:} as described earlier in the section "Limitations of the Localization String".

---

My end result now looks like this:

<DisplayName>{LOC:DisplayName_fta_HydrogenTankSmaller}</DisplayName>
<Description>{LOC:Description_fta_HydrogenTankSmaller}</Description>

Test it in-Game
Now we should be able to see our wanted text in-Game.
For this, we just load up our Space Engineers test World, with the mod loaded.

It now will look like this:

Create a Translation for a mod

For this Guide, I will go with my Native Language, German.

Set-Up
You first need to copy the .resx, and .sbl files, from the mod's directory, and place them inside:

(your Translation Mod name)\Data\Localization

If the localization files of the mod you want to translate, are inside a subfolder, then include the subfolder in the structure above, and place your files in this.

Now this is important, you will need to add something to the name of the files.
This is just to make them not have the same name, as the author's files.
I would suggest you stick to the same naming rule the devs did.
The Format is: "fileName.BCP 47 Code.resx"
So leave the file name the Author gave it, and put your BCP 47 Code behind it.
To find out the BCP 47 Code you need, have a look at the section "Required".

Mine are looking like this:

fta_Strings.de-DE.resx
fta_Strings.de-DE.sbl

Since I am using German, I have added ".de-DE" to my file name, which is the BCP 47 Code for German-Germany.
Keep in mind, you need to rename both, the .resx file, and the .sbl file, I would give both the same name.

The .sbl file
You will need to follow the Section "Set up the .sbl file" for this.

The .resx file
You can now use any text Editor of your choice to translate.
The easiest one is to use Visual Studio Community 2022 since this will let you edit it in a table format.

• Visual Studio Community 2022
  Open the file, now you can translate everything inside the "Value" row (The middle one), do not touch the other rows.
  
• Text Editor
  Open up the .resx file with any text Editor of your choice, translate everything inside, and do not touch anything else:
  

  <value></value>

---

How your folder should look like
Keep in mind, this was made from a modders Perspective, as a translator, you will only have your translated language files.
But mine now looks like this:

---

Test it in-Game
Now we have a look into the game, and see if everything is now translated.
For this, just select the language, you translated the mod to, and see the results. It should look like this: (Just with your Language instead)

Final words

Now you know how to create a Localization File for your mod, which makes it now possible for other people to translate your mod, without getting into issues, and less frustration.

The Guide went a bit longer than I initially intended, but I think you have got what this is all about.

I hope that this will be used more often since I find this a better way to give your mod proper Language support and let us be honest, not everyone wants to play in partial Native Language and partial English. Nor does everyone want to play in full English.

At the end, I want to say, if there is something you did not understand, then please, tell me.
Only with this, I can make this Guide better and more useful.
Even if you noticed some writing mistakes, or have additions for my Guide, go ahead and feel free to tell me.

And I have uploaded a Mod which Utilizes Localization Strings, this can be found here:
https://steamcommunity.com/sharedfiles/filedetails/?id=3018870004

And as always, Happy Modding/Translating!

[Gabe Lily]

Do you know if this works the same with UI elements?