Line 1: |
Line 1: |
| {{../../header}} | | {{../../header}} |
| | | |
− | ===Translation===
| + | 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. |
− | The translation API lets you translate your mod into the player's current language, accounting for locale fallback automatically (e.g. if a translation isn't available in <tt>pt-BR.json</tt>, SMAPI will check <tt>pt.json</tt> and <tt>default.json</tt>). Translations can be a simple string, or they can include tokens to inject values into the translation. | |
| | | |
− | <dl> | + | ==Overview== |
− | <dt>File structure</dt> | + | 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 <tt>pt-BR.json</tt>, SMAPI will check <tt>pt.json</tt> and <tt>default.json</tt>). Translations can be a simple string, or they can include tokens to inject values into the translation. |
− | <dd>SMAPI reads translations from JSON files in a structure like this: | + | |
| + | ==i18n folder== |
| + | ===File structure=== |
| + | SMAPI reads translations from JSON files in an <tt>i18n</tt> subfolder in your mod folder: |
| <pre> | | <pre> |
| YourMod/ | | YourMod/ |
Line 17: |
Line 19: |
| </pre> | | </pre> |
| | | |
− | The <tt>default.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: | + | The <tt>default.json</tt> 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: |
− | <source lang="javascript">
| |
− | {
| |
− | // example translations
| |
− | "item-type.label": "Item type",
| |
− | "item-type.fruit-tree": "{{fruitName}} tree",
| |
− | }
| |
− | </source>
| |
− | | |
− | You can then add translation files for each language you want to support, by copying the <tt>default.json</tt> file and translating its values. Each translation file should have one of these file names:
| |
| | | |
| {| class="wikitable" | | {| class="wikitable" |
Line 50: |
Line 43: |
| | Spanish | | | Spanish |
| | <tt>es.json</tt> | | | <tt>es.json</tt> |
− | |}</dd> | + | |} |
| | | |
− | <dt>Reading translations</dt> | + | ===File format=== |
− | <dd>Once your i18n files are set up, you can read translations for the current locale: | + | 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"> |
| + | { |
| + | // example translations |
| + | "item-type.label": "Item type", |
| + | "item-type.fruit-tree": "{{fruitName}} tree", |
| + | } |
| + | </source> |
| + | |
| + | 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). |
| + | |
| + | ===Tips for translators=== |
| + | * Save i18n files with UTF-8 encoding to avoid broken symbols in-game. |
| + | * Type <code>reload_i18n</code> 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: |
| <source lang="c#"> | | <source lang="c#"> |
| // read a simple translation | | // read a simple translation |
Line 73: |
Line 82: |
| | | |
| i18n.Get("item-type.fruit-tree", new { fruitName = i18n.Get("apple") }); | | i18n.Get("item-type.fruit-tree", new { fruitName = i18n.Get("apple") }); |
− | </source></dd> | + | </source> |
− | | |
− | <dt>Tips for translators</dt>
| |
− | <dd>
| |
− | * Save i18n files with UTF-8 encoding to avoid broken symbols in-game.
| |
− | * Type <code>reload_i18n</code> 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.)
| |
− | </dd>
| |
− | </dl>
| |