Tutorial: Making a Json Assets Mod Compatible with Other Languages (i18n)

PLEASE NOTE: JSON Assets has been obsoleted in favor of Content Patcher in 1.6. Backwards compatibility is maintained but for new mods, items should be added via CP.

Introduction

During this tutorial, I will assume the following:

• You have read the page on How to make your mod compatible with other languages
• You are already familiar with Json Assets (JA) content pack formatting

The Old Way

There are two ways to add translation support to JA mods. The old way is to directly add the translation to the object.json of each object (or similar for other types of items). However, this means that when translators want to translate a mod, they would either need to send the whole mod edited in every file to the original author, or somehow otherwise communicate all the individual changes and where they needed to go.

The New Way

The new way to add translation support is through a more standard i18n folder and the use of translation keys there. The translation keys you put there will relate back to the translation keys declared in the object.json (or craftable.json, etc), in order to match up display names and descriptions with each item. In this format, translators have all of the different things that need translating conveniently in one place, and they can upload just the json file containing the translations instead of having to reupload the mod.

The Quick Guide

If you just want a quick guide on how translations work in JA, you can refer to the author guide on Github.

i18n Folder Structure

JA uses a normal i18n folder structure, with an i18n folder in the top level of your mod folder. Inside the i18n folder, you have your default.json as usual, and any additional json files for other languages you are translating it into. The folder structure will end up looking something like this:

Here's roughly what it should look like:

- [JA] Main mod folder
    - manifest.json
    - i18n folder
        - default.json
        - (any other language json files)
    - Objects
    - Crops
    - (any other subfolders needed for JA items)

Adding Translation Keys to object.json

In order to let JA know that you have translations for an object, you need to put an entry named TranslationKey into each object.json (or craftable.json, etc). One important thing to note is that even though you can translate the display name, the object still needs to have a name declared here.

Here's an example of an object with a translation key:

{
	"Name": "Fa Gao", // Still needed even if you translate the name in your i18n folder
	"TranslationKey": "fagao",
	"Category": "Cooking",
	"Price": 125,

    // Other fields needed for JA object go here
}

I've omitted parts of the object.json as they are not relevant for translations.

Structure of Your default.json

Your default.json should have a number of entries in it, separated by commas, each of which has a key referencing one of the translation keys in one of your items, and then some text as the associated value. For each item, you will need one entry that is of the form yourtranslationkey.name and one entry that is of the form yourtranslationkey.description, where yourtranslationkey is whatever you declared as the translation key in the object.json.

{
	"fagao.name": "Fa Gao",
	"fagao.description": "A muffin-like dessert whose distinctive tops rise and split while cooking. Its name means either rising cake or prosperity cake.",
}

Adding Translation Keys to Other Items

For items other than the basic objects, the process is very similar, except that instead of object.json you would have hat.json, craftable.json, etc. The only important note is that for seeds and saplings, you have SeedTranslationKey for seeds instead of TranslationKey, and similarly for saplings, you have SaplingTranslationKey instead of TranslationKey.

Pitfalls to Watch Out For

As of Stardew Valley version 1.5.6, recipe names don't translate in English in the cooking menu. There are also a few other things that don't use the translation in English. This should be fixed in future game versions, but for now you either have to deal with non-unique-ID-formatted item names (which is suboptimal but normal for Json Assets items), or you can have the non-display name sometimes show up in the game (may look slightly odd/non-immersive).