Hi everyone! This is Yang. I want to share some details on the upcoming changes to localization that we’re making in Alpha 12. Our goal is to get all of the strings that players can see in-game into locales/en.json. Having all strings in this file will make the game easier to translate and also allow players to select the language that they want simply by specifying which translation json file to load.
The Problem
Those of you who’ve tried out modding or have volunteered (graciously!) to translate Stonehearth into other languages know that the current names and descriptions of objects are stored in their respective json files. Ex: the name that is displayed when you click on a basket of corn is defined in corn_basket.json like this:
Hard for the Translator:
One problem with this model is that a translator needs to touch every single .json file in order to make the translation changes necessary. That’s a lot of files! Another problem is that it’s not always clear which lines should be translated and which should not be. For example, though an object’s “name” attribute should be translated, other attributes that look like English words, such as the tags for object material, are actually used by the game logic, and may change the way the game works if altered.
Furthermore, some of the English words (programmers call them “strings”) were actually defined in lua files, not in json files, which means the translator would need to modify code in order to get to them, and as you modders who have tried to override .lua files know, this is very hard to maintain as the code changes.
Hard for the Player:
Another problem with the current model is that a player would need to replace all the json files for every object if they wanted to change their language. This makes it very difficult to package the game for international players — a translated version of stonehearth means downloading a 100MB mod that includes translated versions of all the files.
Hard for Everyone:
Finally, the old language model would have been less player friendly when we implement multiplayer. In ye olde days, the names of objects are read by the server directly from the json files, so if the server’s corn_basket.json file is in English, the corn basket name would be permanently stuck in the English, even if some of the players connected to the server would prefer to play in Spanish or French or German instead. This doesn’t have to be the case! A corn basket looks and behaves the same regardless of which language it was created in.
The Solution
The solution is to put all translatable strings into a single translation json file. In this case, en.json would be the English translation file (en = ENglish). Then, in the individual object files, the object names and descriptions will be a string key that points to a particular line in the translation file. That way, the key would stay the same no matter the language.
In the future, with multiplayer, this allows players that prefer different languages to play together on the same server. The server will create objects with keys and each client can look up what to display for each key.
Now that basket of corn’s unit info looks like this:
It’s harder to read and a lot longer than the plain English string, but here’s what it means:
- i18n(stonehearth:entities.food.corn.corn_basket.name) is the new name key for the corn basket
- The i18n() that surrounds the key tells Stonehearth that “this is a localization key instead of normal text”. i18n is shorthand for “internationalization”, which is another name for localization
- The portion inside, stonehearth:entities.food.corn.corn_basket.name, describes how to navigate to the actual string that defines the name for the corn basket in the translation json file (en.json for English). The “stonehearth:” at the beginning says that the string will be defined in the translation file in the stonehearth mod.
- In the stonehearth/locales/en.json file, there will be an entry like this:
![image04]()
- Now, if we wanted to change the language to say, German, all we need to do is create a new translation json file called de.json (de is the language code for German.) and specify the same entry except put in the German translation:
![image00]()
Now the corn_basket.json file can be the same exact file for both an English and a German version of the game. And changing languages just means changing which translation json file is used!
Testing!
Having all translations in one file also means we can easily test which portions of the game are translatable and which portions need to be added to the translation file. One way to do this is to use pseudolocalization. This is where we replace everything in en.json with letters that have accents such that the words look different, but are still readable by an English speaker. An example:
Here we can see that the “Building Templates” string has been translated using pseudolocalization, so that string is good to go. However, we can clearly read the “Design Custom Building” text on the button. This means “Design Custom Building” has been put into the game as plain text instead of being placed in the translation json file and referenced by a key.
Using techniques like this, we can make sure all our text is translatable and (hopefully) make Stonehearth easier to translate for all our volunteers.
Note to all our existing localization modders out there: This system is backwards compatible, so you can still put the names and descriptions for your objects directly in their json files if you want. However, if you want to give the new system a try in A12, please let us know how it’s working for you!