Modding:Modder Guide/APIs/Translation

Creating SMAPI mods

---

• Get started
• Game fundamentals
• Test & troubleshoot
• Release
• API reference

  Basic SMAPI APIs:

  • Mod structure
  • Manifest
  • Events
  • Configuration
  • Load & edit content
  • Data
  • Input
  • Logging
  • Reflection
  • Multiplayer
  • Translation
  • Update checks
  • Utilities

  Advanced SMAPI APIs:

  • Content packs
  • Mod console commands
  • Mod integrations
  • Harmony patching

• Specific guides

← Modding:Index

The translation API lets you translate your mod, and include all languages in one release package for SMAPI to use automatically based on the game language.

Overview

SMAPI reads translations from files in your mod folder. When you request a translation, it will automatically handle locale fallback (e.g. if a translation isn't available in pt-BR.json, SMAPI will check pt.json and default.json). Translations can be a simple string, or they can include tokens to inject values into the translation.

i18n folder

File structure

SMAPI reads translations from JSON files in an i18n subfolder in your mod folder:

YourMod/
   i18n/
      default.json
      es.json
      pt.json
   manifest.json
   YourMod.dll

The default.json file includes the default text that will be shown if a more specific translation isn't available, and you create a separate file for each language. Each translation file should have one of these file names:

Language	File name
Chinese	zh.json
French	fr.json
German	de.json
Hungarian	hu.json
Italian	it.json
Japanese	ja.json
Korean	ko.json
Portuguese	pt.json
Russian	ru.json
Spanish	es.json
Turkish	tr.json

File format

Each .json file should contain a flat key→value lookup with your default text. Each key is case-insensitive, and can contain alphanumeric, underscore, hyphen, and dot characters. Feel free to add JavaScript comments to organise or document your translations. For example:

{
    // example translations
    "item-type.label": "Item type",
    "item-type.fruit-tree": "{{fruitName}} tree",
}

The {{fruitName}} in the above example is a token. You can add any tokens you want (each having only letters in the name), and replace them with a different value in code (see reading translations below).

Tips for translators

• Save i18n files with UTF-8 encoding to avoid broken symbols in-game.
• Type reload_i18n into the SMAPI console and hit enter to reload translations without exiting the game. (If a mod internally cached a translation, it may not be updated.)

Reading translations

Once your i18n files are set up, you can read translations for the current locale:

// read a simple translation
string label = helper.Translation.Get("item-type.label");

// read a translation which uses tokens (accepts an anonymous object, dictionary, or model)
string text = helper.Translation.Get("item-type.fruit-tree", new { fruitName = "apple" });

The helper.Translate(…) method returns a fluent interface — you can keep calling methods on its return value to customise the translation. (See IntelliSense for a description of the available methods.) To get the text, simply assign it to a string:

// use fluent chain
string text = helper.Translate(key).Tokens(tokens).Tokens(moreTokens).Assert();

If your code has a lot of translation calls, you can make it less verbose by aliasing the translation helper:

var i18n = helper.Translation;

i18n.Get("item-type.fruit-tree", new { fruitName = i18n.Get("apple") });