About localization

Stonehearth's UI is encoded in UTF-8 and we use this Javascript framework for localization.

In order to enable localization for your mod, you need to add this key to your manifest. Usually we put it below the "info" section to avoid forgetting about it (remember to add commas where needed!) :

  "default_locale" : "en"

Localization in the game works this way: for every text that we want to be translatable, we create a key in the stonehearth/locales/en.json file. Then, in our JSON files, we reference that key wrapping it with "i18n()". For example, this is how we specify the name and description of the brightbell window box:

  "entity_data": {
     "stonehearth:catalog": {
        "display_name": "i18n(stonehearth:entities.decoration.window_box_brightbell.window_box_brightbell_ghost.display_name)",
        "description": "i18n(stonehearth:entities.decoration.window_box_brightbell.window_box_brightbell_ghost.description)",
        "icon": "file(window_box_brightbell.png)",
        "category": "decoration",
        "material_tags": "decoration crafted stockpile_decoration"
     }
  }

Notice the dots separating the keys. In the en.json file, we'll have this structure:

  {
     "entities" : {
        "decoration": {
           "window_box_brightbell" : {
              "window_box_brightbell_ghost" : {
                 "display_name" : "Brightbell planter",
                 "description" : "A tidy home for the plant."
              }
           }
        }
     }
  }

So we use "i18n()" and inside it we write the namespace of our mod, a colon, and then the hierarchy of keys that we set up in the language file, separated by dots. When the game loads this file, it will replace the i18n() string with the actual translation we specified in our language file.

For quick testing, we can write plain text instead of "i18n(...)" and the game should be able to read it fine. But later we'll have to change it as explained above to make it translatable.

We have thousands of text lines to translate in the stonehearth mod, so we organize the keys imitating our folder structure. In this case, the text we want to translate is inside stonehearth/entities/decoration/window_box_brightbell/window_box_brightbell_ghost.json.

When adding localization to your own mod, you can use any nodes you like for your en.json file, you can even have all the keys at the same level, like this:

  {
     "name_1" : "Test",
     "description_1" : "My description",
     "info" : "Another text"
  }

But it's useful to have them organized so that you can have repeated keys inside different nodes.

When making a translation mod for an existing en.json file, you have to use the exact same keys, then translate the text/value part into your language.

When translating the stonehearth mod, you might find special text inside localization strings, such as [str(i18n_data.town_name)]. These are meant to be left untouched. They are variables that will get substituted inside the game. For example, [str(i18n_data.town_name)] represents your town name. These variables are declared in JSON files such as campaign encounters that trigger dialogs. That way, we can use proper nouns dynamically generated by the game inside of our translatable text, such as boss names, your town name (which you customize when you start playing), etc.

Information about fonts and how to make translation mods can be found here.