Changes

===File format===

===File format===

Each <tt>.json</tt> 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:

Each <tt>.json</tt> 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:

<source lang="javascript">

<syntaxhighlight lang="javascript">

{

{

     // example translations

     // example translations

     "item-type.fruit-tree": "{{fruitName}} tree",

     "item-type.fruit-tree": "{{fruitName}} tree",

}

}

</source>

</syntaxhighlight>

The <code><nowiki>{{fruitName}}</nowiki></code> 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|''reading translations'']] below).

The <code><nowiki>{{fruitName}}</nowiki></code> 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|''reading translations'']] below).

===Built-in API===

===Built-in API===

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

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

<source lang="c#">

<syntaxhighlight lang="c#">

// read a simple translation

// read a simple translation

string label = helper.Translation.Get("item-type.label");

string label = helper.Translation.Get("item-type.label");

// read a translation which uses tokens (accepts an anonymous object, dictionary, or model)

// 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" });

string text = helper.Translation.Get("item-type.fruit-tree", new { fruitName = "apple" });

</source>

</syntaxhighlight>

The <tt>helper.Translate(…)</tt> 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, just assign it to a string:

The <tt>helper.Translate(…)</tt> 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, just assign it to a string:

<source lang="c#">

<syntaxhighlight lang="c#">

// use fluent chain

// use fluent chain

string text = helper.Translation.Get(key).Tokens(tokens).Tokens(moreTokens).Default("missing translation?");

string text = helper.Translation.Get(key).Tokens(tokens).Tokens(moreTokens).Default("missing translation?");

</source>

</syntaxhighlight>

===Strongly-typed API===

===Strongly-typed API===

The optional [https://github.com/Pathoschild/SMAPI-ModTranslationClassBuilder#readme SMAPI mod translation class builder] package lets you generate a strongly-typed class to read translations like this instead:

The optional [https://github.com/Pathoschild/SMAPI-ModTranslationClassBuilder#readme SMAPI mod translation class builder] package lets you generate a strongly-typed class to read translations like this instead:

<source lang="c#">

<syntaxhighlight lang="c#">

string label = I18n.ItemType_Label();

string label = I18n.ItemType_Label();

string text = I18n.ItemType_FruitTree(fruitName: "apple");

string text = I18n.ItemType_FruitTree(fruitName: "apple");

</source>

</syntaxhighlight>

If a translation breaks, you'll know immediately since it won't compile.

If a translation breaks, you'll know immediately since it won't compile.