[HOW TO] Write a basic Localization.txt for your mod

[mr.devolver]

 Hello everyone,

 

recently I was trying to help another modder who wanted to learn how to write his custom Localization.txt file for his mods. Although the original idea was to give him a quick answer, it turned out to be a little tutorial I thought someone else may find useful, so here it is for everyone:

 

Think of the content of Localization.txt as if it was the content of a table. As long as you stick to the vanilla format and follow its rules, you should be fine. Always try to match the vanilla format whenever possible.

 

Following these three simple rules will help you to write your own basic localizations from scratch:

 

1. First line of Localization.txt is always the table header with all kinds of labels or descriptions for entries below it. In other words, they should give you a hint as to which entry is expected where. This is the first line in vanilla:

Key,File,Type,UsedInMainMenu,NoTranslate,english,Context / Alternate Text,german,latam,french,italian,japanese,koreana,polish,brazilian,russian,turkish,schinese,tchinese,spanish

 

2. As you can see in this first line, all the entries must be separated by commas thanks to which the game knows where the new entry is and everything after a comma is treated as a new entry. However, what if we needed to write a long text such as item description that may contain several commas that we actually want to show in game? That's what the rule number 2 is all about:

 

Writing long texts that have to include commas such as item descriptions would normally break the Localization.txt file format. To avoid that issue, the whole entry must be written inside double quotation marks like in the following example:

"This is one entry in Localization.txt, and this is still the same entry despite being written after the comma! All thanks to being written inside double quotation marks!"

 

3. Each line in Localization.txt file is considered a new line of entries in the table, so what if we wanted to write a pretty item description with paragraphs instead of showing a wall of text with no paragraphs?

 

To write a new line inside our text, we need to write a special mark that will tell the game to put the text that follows on a new line. The mark looks like this:

\n

 

Example:

This will be shown on the first line.\nThis will be shown on the second line.

In game this text will look like this:

This will be shown on the first line.
This will be shown on the second line.

 

If you wanted to leave one or more lines empty, you would have to put two or more of these marks together.

 

Example:

This will be shown on the first line.\n\nThis will be shown on the third line.

In game this text will look like this:

This will be shown on the first line.

This will be shown on the third line.

 

A good rule of thumb is to keep the length of your texts up to 80 characters per line, otherwise your text may show up a little bit broken, not neatly formatted the way you expected. It's because the game seems to put hard-coded line breaks after 80 characters, at least in some cases.

 

That's it for the basics. There are also some advanced things such as tags you can use inside Localization.txt that help you to show some special values that may be changing in game and it will always show the actual values, such as cvars, but honestly I'm not familiar with those yet, I never really had to use them and it's out of scope of this little tutorial point of which was to explain basics.

 

I hope this helps at least some of you to get started writing your first basic localizations for your new awesome mods. I hope you enjoyed it and I wish you good luck with your mods!

[xyth]

Great addition to the tutorial section.  Thanks for your effort!

[Cranberry Monster]

Great stuff here, succinctly explained. Love it.

For returning modders looking to update past work, you might want to note that quest localization no longer has its own file, plus the change to localization being pushed (I think--not playing around with a19 yet).

[Quicksilver]

How do you make changes to vanilla Localization in my mod? All I can find is info on adding new items. I made a mod to change crafting perks and I want to modify the Localization in my mod to reflect the changes, but what I have does not change anything.

 Example of the header and one line that I am currently hacking at trying.

 

key,source,context,changes,english,german,latam,french,italian,japanese,koreana,polish,brazilian,russian,turkish,schinese,tchinese,spanish
perkLightArmorRank1LongDesc,progression,perk Agi,"You have started on the path of the lightly armored warrior. Craft quality 3 fair light armor, reduce light armor movement penalty by 15% and stamina penalty by 10%. Improve durability by 50%.\nUnlocks leather armor crafting.",

[mr.devolver]

13 hours ago, Quicksilver said:

How do you make changes to vanilla Localization in my mod? All I can find is info on adding new items. I made a mod to change crafting perks and I want to modify the Localization in my mod to reflect the changes, but what I have does not change anything.

 Example of the header and one line that I am currently hacking at trying.

 

key,source,context,changes,english,german,latam,french,italian,japanese,koreana,polish,brazilian,russian,turkish,schinese,tchinese,spanish
perkLightArmorRank1LongDesc,progression,perk Agi,"You have started on the path of the lightly armored warrior. Craft quality 3 fair light armor, reduce light armor movement penalty by 15% and stamina penalty by 10%. Improve durability by 50%.\nUnlocks leather armor crafting.",

Apparently you didn't read the advices I wrote in the OP. Commas between the individual entries are there for a reason! Please refer to the line in vanilla Localization.txt starting with perkLightArmorRank1LongDesc and compare it to your own. The difference is the reason why it didn't work for you.

[Quicksilver]

Thank you,

  Do you mean quotation marks? I used commas and quotation marks but I did not understand how the header list related to the body lines.

  I got it working by cutting it down to only the header entries of:

 

Key,File,Type,english,
perkLightArmorRank1LongDesc,progression,perk Agi,"You have started on the path of the lightly armored warrior. Craft quality 3 fair light armor, reduce light armor movement penalty by 15% and stamina penalty by 10%. Improve durability by 50%.\nUnlocks leather armor crafting.",

Edited October 27, 2020 by Quicksilver (see edit history)

[mr.devolver]

15 hours ago, Quicksilver said:

Do you mean quotation marks? I used commas and quotation marks but I did not understand how the header list related to the body lines.

 

This is explained in OP:

On 9/5/2020 at 9:35 AM, mr.devolver said:

Think of the content of Localization.txt as if it was the content of a table. As long as you stick to the vanilla format and follow its rules, you should be fine. Always try to match the vanilla format whenever possible.

 

Your original table didn't work, because the body of the table didn't match the header. It's really that simple, I can't really think of any other way to explain it to you...

 

Again, it's a table with columns and rows, so naturally the body of the table must match the header, not only in sense of the meaning of individual entries, but also in number of entries. The latter is done using commas which are there to let the game know that it's a new entry in the table. If you need to use a comma inside the entry, you have to mark the start and end of the entry with quotation marks like so: "<TABLE ENTRY GOES HERE>", because any comma outside quotation marks is considered a delimiter between table entries.

 

Your new table is also wrong as it's contains a comma after english and the entry with the perkLightArmorRank1LongDesc key also ends with a comma. Why did you leave those commas there? It's unnecessary and doesn't match the vanilla format.

On 9/5/2020 at 9:35 AM, mr.devolver said:

Always try to match the vanilla format whenever possible.

 

I can't stress this enough. You may think that if it works, it doesn't need fixing, but then you will run into other issues if you ignore the way vanilla file is constructed and you will have no clue what went wrong again...

[Nomadikhan]

 

I'm looking at adding 5.56mm ammo.. or rather have.  Issue I'm having is if I copy ammo762mmBulletBallDesc line into my localization.txt and change it from ammo762mmBulletBallDesc to ammo556mmBulletBallDesc in-game I get quite literally "ammo556mmBulletBallDesc" as the description.... everything else in the line is vanilla.

 

I'm unsure what I'm doing wrong?

 

Update:  Apparently it's required to have that first line that defines the table.  Once I had that as the first line in mine it now works properly.  (fixed my invisible icons too lol).   It may be worth putting in your OP that you need that first line that defines the table else it doesn't function when pushed.

 

Thanks for the guide!

Edited December 5, 2020 by Nomadikhan (see edit history)

[DEV GANG donorcap]

Hello i have been making a code adding a lot but for my Recipes it will have the picture of the custom item But will not give me the name of the ingredient EG below:

If anyone is to help me figure this out I would greatly appreciate it.

[Gouki]

Hi donorcap

 

Does your mod or what you've done has a location file?
or your recipe file as is or did you modify the original game file?
Regards

[DEV GANG donorcap]

Hi there @Gouki yes i have a localization file i just have no idea who to write it
i have got my custom items with Desc and custom names for when hovering over them i just been trying to figure out how the code is written for a Recipes window.

thank so much for taking an interest in my issue

Edited December 7, 2020 by DEV GANG donorcap (see edit history)

[DEV GANG donorcap]

Turns out the Materials_based="true" was the issue  fixed it now

[Gouki]

4 hours ago, DEV GANG donorcap said:

Turns out the Materials_based="true" was the issue  fixed it now

 

yes, materials_based = "true" is implemented to work only in forge recipes.
Good that you have solved that problem.
For the location here is an example:

 

Key,File,Type,UsedInMainMenu,NoTranslate,english,Context / Alternate Text,german,latam,french,italian,japanese,koreana,polish,brazilian,russian,turkish,schinese,tchinese,spanish
TitaniumBars,items,Item,,,Barras de Titanio
TitaniumBarsDesc,items,Item,,,"Mas fuertes que las barras de acero"
TitaniumBarsSchematic,items,item,,,Esquema de Barras de Titanio

 

Hope that helps you.

Regards

Edited December 7, 2020 by Gouki (see edit history)

[CrazyAluminum]

On 9/5/2020 at 10:35 AM, mr.devolver said:

 Hello everyone,

 

recently I was trying to help another modder who wanted to learn how to write his custom Localization.txt file for his mods. Although the original idea was to give him a quick answer, it turned out to be a little tutorial I thought someone else may find useful, so here it is for everyone:

 

Think of the content of Localization.txt as if it was the content of a table. As long as you stick to the vanilla format and follow its rules, you should be fine. Always try to match the vanilla format whenever possible.

 

Following these three simple rules will help you to write your own basic localizations from scratch:

 

1. First line of Localization.txt is always the table header with all kinds of labels or descriptions for entries below it. In other words, they should give you a hint as to which entry is expected where. This is the first line in vanilla:

Key,File,Type,UsedInMainMenu,NoTranslate,english,Context / Alternate Text,german,latam,french,italian,japanese,koreana,polish,brazilian,russian,turkish,schinese,tchinese,spanish

 

2. As you can see in this first line, all the entries must be separated by commas thanks to which the game knows where the new entry is and everything after a comma is treated as a new entry. However, what if we needed to write a long text such as item description that may contain several commas that we actually want to show in game? That's what the rule number 2 is all about:

 

Writing long texts that have to include commas such as item descriptions would normally break the Localization.txt file format. To avoid that issue, the whole entry must be written inside double quotation marks like in the following example:

"This is one entry in Localization.txt, and this is still the same entry despite being written after the comma! All thanks to being written inside double quotation marks!"

 

3. Each line in Localization.txt file is considered a new line of entries in the table, so what if we wanted to write a pretty item description with paragraphs instead of showing a wall of text with no paragraphs?

 

To write a new line inside our text, we need to write a special mark that will tell the game to put the text that follows on a new line. The mark looks like this:

\n

 

Example:

This will be shown on the first line.\nThis will be shown on the second line.

In game this text will look like this:

This will be shown on the first line.
This will be shown on the second line.

 

If you wanted to leave one or more lines empty, you would have to put two or more of these marks together.

 

Example:

This will be shown on the first line.\n\nThis will be shown on the third line.

In game this text will look like this:

This will be shown on the first line.

This will be shown on the third line.

 

A good rule of thumb is to keep the length of your texts up to 80 characters per line, otherwise your text may show up a little bit broken, not neatly formatted the way you expected. It's because the game seems to put hard-coded line breaks after 80 characters, at least in some cases.

 

That's it for the basics. There are also some advanced things such as tags you can use inside Localization.txt that help you to show some special values that may be changing in game and it will always show the actual values, such as cvars, but honestly I'm not familiar with those yet, I never really had to use them and it's out of scope of this little tutorial point of which was to explain basics.

 

I hope this helps at least some of you to get started writing your first basic localizations for your new awesome mods. I hope you enjoyed it and I wish you good luck with your mods!

Can you update your guide and add the "Key,English" way?

[mr.devolver]

On 12/5/2020 at 8:07 PM, Nomadikhan said:

It may be worth putting in your OP that you need that first line that defines the table else it doesn't function when pushed.

 

It's already there in the rule number 1 with an example. I'm sorry, but I can't think of any better way how to explain it...

On 9/5/2020 at 9:35 AM, mr.devolver said:

1. First line of Localization.txt is always the table header

 

  ...

 

On 12/9/2020 at 12:00 PM, CrazyAluminum said:

Can you update your guide and add the "Key,English" way?

I am aware of the flexibility of the format of this file, but this was meant to be a short guide for beginners to teach the players how to format their first basic localization.txt file and how to make one quickly with as few errors as possible. The reason why I'm encouraging them to stick with the vanilla format is simply that there's always an example in vanilla localization.txt file, so if they ever get stuck, they could simply check out the vanilla file again, but if they decide to go with their custom format, they will be on their own with no example they could follow. Therefore adding something like this may be counter-productive. As you can see, some people find it difficult to even understand the vanilla format. If I added another option to the guide, they could be confused even more and make more mistakes.

Edited December 11, 2020 by mr.devolver (see edit history)

[CrazyAluminum]

8 hours ago, mr.devolver said:

 

It's already there in the rule number 1 with an example. I'm sorry, but I can't think of any better way how to explain it...

 

  ...

 

I am aware of the flexibility of the format of this file, but this was meant to be a short guide for beginners to teach the players how to format their first basic localization.txt file and how to make one quickly with as few errors as possible. The reason why I'm encouraging them to stick with the vanilla format is simply that there's always an example in vanilla localization.txt file, so if they ever get stuck, they could simply check out the vanilla file again, but if they decide to go with their custom format, they will be on their own with no example they could follow. Therefore adding something like this may be counter-productive. As you can see, some people find it difficult to even understand the vanilla format. If I added another option to the guide, they could be confused even more and make more mistakes.

"Key,English" format is easier and better, because you don't have to write a lot of useless text you skip anyway

Edited December 11, 2020 by CrazyAluminum (see edit history)

[mr.devolver]

On 12/11/2020 at 12:37 PM, CrazyAluminum said:

"Key,English" format is easier and better, because you don't have to write a lot of useless text you skip anyway

This is an understatement of the vanilla format of localization.txt file. This is the same as if you said that you don't need a manual to assemble a chair from the parts, then you throw out some of the parts because you have no idea where they are supposed to go and as soon as you sit on it, it breaks.

 

Going with the simple format is neither easier nor better. Just because it seems to work even if you throw out some part of it doesn't mean that it's better, it just means that you don't understand the purpose of the part that you just threw out and you still might need it later.

 

Besides, what might seem as easier to you may seem more confusing to others who don't really know what are they doing, because they are still learning their way through this. Some people prefer a simple solution that would allow them to quickly copy and paste the lines they already have at their disposal (in vanilla file) and make some changes to them to repurpose them for their mod rather than trying to write their own lines from scratch, not really knowing how to do it correctly.

 

Ultimately, people first need to learn the vanilla format to understand how it works and how to do some changes to it safely without breaking it and this little guide is for them.

 

The knowledge how to simplify it comes along with it automatically, if they ever wanted to go that way.

[khzmusik]

Just an FYI for those people who actually want to do localization for their modlets, and not just add English entries...

 

I found this online tool helpful. It will translate English text into multiple languages at once:

https://smodin.me/translate-one-text-into-multiple-languages

 

I can't vouch for the quality of the translations. But, IMHO, something is usually better than nothing.

 

If anyone else knows of better translation services, then feel free to post them here.

[Cranberry Monster]

After a glance at that site, I can kind of vouch for the quality, but not in a good way. Let's put it this way--in the interface, their translation of "Japanese" is "Japanese person" as opposed to "Japanese language." Context is hard, and I'm sure it probably works better for Romance languages, but the old adage of "Write what you know" goes double for translating. Best possible outcome: unintentional hilarity. Worst possible outcome: WWIII?

[meganoth]

3 hours ago, Cranberry Monster said:

After a glance at that site, I can kind of vouch for the quality, but not in a good way. Let's put it this way--in the interface, their translation of "Japanese" is "Japanese person" as opposed to "Japanese language." Context is hard, and I'm sure it probably works better for Romance languages, but the old adage of "Write what you know" goes double for translating. Best possible outcome: unintentional hilarity. Worst possible outcome: WWIII?

 

You forget that this best outcome is actually the best outcome possible. If you give the word "japanese" to a translation service and do not supply a context by hand then even a human translator could not do better.

 

Asian companies have done this automatic translations of their product manuals for ages and it worked (i.e. they got to sell that stuff in the west, it was cheap for them and it did not start WWIII).

 

[khzmusik]

Does anyone know what happens if you override a vanilla entry in localization.txt but only provide an English translation?

 

For example, the vanilla 7D2D localization.txt file has this entry:

quest_BasicSurvival1,Quest,Quest Info,,,Basic Survival 1/8,,Das 1x1 des Überlebens 1/8,Supervivencia básica 1/8,Les bases de la survie 1/8,Basi della sopravvivenza 1/8,生き残るための基礎知識 1/8,기본 생존 1/8,Podstawy przetrwania 1/8,Sobrevivência Básica 1/8,Основы выживания 1/8,Temel Hayatta Kalma 1/8,基础生存 1/8,基本生存 1/8,Supervivencia básica 1/8

 

Let's say you wanted to insert a basic survival quest before that one, so that it is now 2 of 9. What happens if you supply this?

quest_BasicSurvival1,Quest,Quest Info,,,Basic Survival 2/9,,,,,,,,,,,,,,

 

Do non-English speakers still see the "1/8" text? Or does the game assume there is no localized text for that language, and display the English text?

[khzmusik]

Quick update. It looks like the site I suggested (smodin.me) doesn't really work any more.

 

But I found an even easier option.

 

If anyone uses Google Sheets, it turns out that Google has included a function to translate cells automatically. Why does this matter? Because, basically, Localization.txt is just a renamed CSV file ("comma separated values"). Those can be imported and exported by pretty much any spreadsheet software, Google Sheets included.

 

To translate a cell, just enter this formula:

=GoogleTranslate(F2, "en", "de")

 

...where "F2" is the cell you're translating, and "de" is the language code for the translation ("de" is German). If you copy a formula to another cell, the reference to the original cell ("F2") gets updated. You can easily copy a formula to other cells by double-clicking on the little square icon in the bottom right corner when you select a cell with a formula in it.

 

EDIT: That is assuming that your original language is English. If you're translating from another language, put in that language code instead of "en" - and make sure you also put that formula into the place where the English version goes.

 

So, you can set up a template with those formulas entered for every language that 7D2D supports. Copy that template, add the relevant information into your spreadsheet (the key, the English original text, etc.) and export the whole thing as a CSV file. Then rename that file to Localization.txt.

 

Bingo bango - you now have a modlet that has all the translations for all your text, not just English.

 

I've already used this and it's stupid simple. You do sometimes get errors - I suspect Google is throttling the translation services - but reloading the spreadsheet fixes them in my experience.

 

Microsoft also has translation services, so there's probably some similar functionality for Excel, but I don't use Excel.

 

EDIT 2: To make things easier, here's a link to the Google Sheet that I use as a template. Anyone with this link should be able to view it, but not modify it (and if I'm wrong... please don't modify it).

https://docs.google.com/spreadsheets/d/1UzO2_8ahCbOYD9buwP_yNDlXNXSeW6ysR3cascG1gr0/edit?usp=sharing

Edited June 17, 2021 by khzmusik
Added link to my template (see edit history)

[FramFramson]

EDIT: Wrong thread, will ask in help.

Edited December 20, 2023 by FramFramson (see edit history)

[y_f]

On 6/17/2021 at 12:07 PM, khzmusik said:

Quick update. It looks like the site I suggested (smodin.me) doesn't really work any more.

 

But I found an even easier option.

 

If anyone uses Google Sheets, it turns out that Google has included a function to translate cells automatically. Why does this matter? Because, basically, Localization.txt is just a renamed CSV file ("comma separated values"). Those can be imported and exported by pretty much any spreadsheet software, Google Sheets included.

 

To translate a cell, just enter this formula:

=GoogleTranslate(F2, "en", "de")

 

...where "F2" is the cell you're translating, and "de" is the language code for the translation ("de" is German). If you copy a formula to another cell, the reference to the original cell ("F2") gets updated. You can easily copy a formula to other cells by double-clicking on the little square icon in the bottom right corner when you select a cell with a formula in it.

 

EDIT: That is assuming that your original language is English. If you're translating from another language, put in that language code instead of "en" - and make sure you also put that formula into the place where the English version goes.

 

So, you can set up a template with those formulas entered for every language that 7D2D supports. Copy that template, add the relevant information into your spreadsheet (the key, the English original text, etc.) and export the whole thing as a CSV file. Then rename that file to Localization.txt.

 

Bingo bango - you now have a modlet that has all the translations for all your text, not just English.

 

I've already used this and it's stupid simple. You do sometimes get errors - I suspect Google is throttling the translation services - but reloading the spreadsheet fixes them in my experience.

 

Microsoft also has translation services, so there's probably some similar functionality for Excel, but I don't use Excel.

 

EDIT 2: To make things easier, here's a link to the Google Sheet that I use as a template. Anyone with this link should be able to view it, but not modify it (and if I'm wrong... please don't modify it).

https://docs.google.com/spreadsheets/d/1UzO2_8ahCbOYD9buwP_yNDlXNXSeW6ysR3cascG1gr0/edit?usp=sharing

Hello, thank you very much for your translation method. I have a new question. When I import the text, the quotes disappear automatically. How do you solve it?

[khzmusik]

9 hours ago, y_f said:

Hello, thank you very much for your translation method. I have a new question. When I import the text, the quotes disappear automatically. How do you solve it?

 

You should be able to escape a double quote symbol by preceding it with another double quote symbol:

"He said, ""Hello, world!"" to me."

That should show on screen as:

He said, "Hello, world!" to me.

 

EDIT: If you're using Google Sheets, I thought it would do this for you automatically. I never tested it though.

Edited January 19 by khzmusik (see edit history)