Translations
Your mod can show its texts in the player's language. Translations ship with the mod as one JSON file per language, in a Translations directory next to manifest.json.
Prefix your IDs
The game and all mods share one set of string IDs. A string is your mod's own when its ID starts with your mod ID and a period, and a mod can translate only its own strings. So start both your proto IDs and your Loc.Str IDs with that prefix.
The name and description of a proto take their string IDs from the proto ID, so a prefixed proto ID is all they need. This furnace's strings are ExampleMod.ExampleFurnace__name and ExampleMod.ExampleFurnace__desc:
public static readonly MachineProto.ID ExampleFurnace = new MachineProto.ID("ExampleMod.ExampleFurnace");
A string you create with Loc.Str gets the prefix in the ID you write. The second argument is the text, the third a note for translators:
using Mafi.Localization;
public static class ExampleModTexts {
public static readonly LocStr Welcome = Loc.Str("ExampleMod.Welcome", "Welcome!", "Greeting shown to the player");
}
Keep such strings in static readonly fields like this one. The game registers those as soon as it loads your mod, so the export below finds every one.
In a string ID, what follows the period is 4 to 64 characters of letters, digits and underscores, starting with a letter or an underscore and ending with a letter or a digit. A string whose ID breaks this rule cannot be translated, and the game warns about it in the log.
Write the texts in English
The game treats the texts in your code as English. Players who chose English see them, and so do players whose language your mod has no translation for. Write them in English, proto names and descriptions included.
Export and translate
Start a new game or load a save with your mod enabled, open the console with the backtick key, and run the export with your mod ID:
export_mod_translations ExampleMod
It writes two files and prints where it put them, normally the Translations directory of your deployed mod. template.json holds your mod's texts: the names and descriptions of its protos, its Loc.Str strings, and the titles and tooltips of its key bindings. source.json has the same texts together with your notes for translators.
Copy template.json to a file named after the language, the way the game names its own files in the Translations directory of the game installation: de.json for German, zh_Hans.json for Simplified Chinese. Translate the texts and leave the IDs as they are. A German file with three texts looks like this:
[
["ExampleMod.ExampleFurnace__name", "Beispielofen"],
["ExampleMod.ExampleFurnace__desc", "Testofen"],
["ExampleMod.Welcome", "Willkommen!"]
]
Ship the files
The language files go in your mod's Translations directory:
ExampleMod/
manifest.json
ExampleMod.dll
Translations/
de.json
zh_Hans.json
Ship only the languages you have. Players whose language has no file, or whose file lacks a text, see the English text.
In the example project, keep the language files in the project's Translations directory: every build copies it into the deployed mod. The game reads the files when a game starts or loads, so load your save again to see a change.
Good to know
- Keep placeholders such as
{0}in the translated text. A translation that drops one is not used, and the player sees the English text instead. - IDs in your language files that are not your mod's own are ignored, with a warning in the log.
- The console command
print_translation_errorslists the problems the game found in the translations of the current language, such as a dropped{0}or a plural text with the wrong number of forms. It covers the game's own strings too, so look for your mod's IDs. - A mod whose ID breaks the Mod ID rules, usually by containing a period, cannot ship translations. The game ignores its
Translationsdirectory. - A mod already published with unprefixed proto IDs should keep them for now, because renaming a proto ID breaks existing saves. The mod can still translate those strings under their IDs as they are, and the export lists them. That ends with Update 5 (v0.9.0), which breaks saves anyway, so rename the IDs then. Prefix every new ID right away.