ModTranslationClassBuilder autogenerates a strongly-typed class to access i18n
translation files
from your SMAPI mod code.
Mods use code like this to read their translations:
string text = helper.Translation.Get("range-value", new { min = 1, max = 5 });
Unfortunately there's no validation at this point; if the key is range
(not range-value
) or the
token name is minimum
(not min
), you won't know until you test that part of the mod in-game and
see an error message.
That also means that after changing the translation files, you need to manually search the code for anywhere that referenced the translations to update them. That gets pretty tedious with larger mods, which might have hundreds of translations used across dozens of files.
This package lets you write code like this instead:
string text = I18n.RangeValue(min: 1, max: 5);
Since it's strongly typed, it's validated immediately as you type. For example, if you accidentally
typed I18n.RangeValues
instead, you'll see an immediate error that RangeValues
doesn't exist
without needing to test it in-game (or even compile the mod).
See the test mod for an example of the generated class in an actual mod.
- Install the NuGet package.
- In your mod's
Entry
method, add this line:I18n.Init(helper.Translation);
That's it! Now you can immediately use I18n
anywhere in your mod code. The class will be updated
automatically whenever your i18n/default.json
file changes.
-
The class uses your project's root namespace by default (you can change that if needed).
-
Translation keys are converted to CamelCase, with
.
changed to_
to help group categories.For example:
key in i18n/default.json
method ready
I18n.Ready()
ready-now
I18n.ReadyNow()
generic.ready-now
I18n.Generic_ReadyNow()
You can configure the I18n
class using a <PropertyGroup>
section in your mod's .csproj
file.
Each property must be prefixed with TranslationClassBuilder_
. For example, this changes the class
name to Translations
:
<PropertyGroup>
<TranslationClassBuilder_ClassName>Translations</TranslationClassBuilder_ClassName>
</PropertyGroup>
Main options:
argument | description | default value |
---|---|---|
ClassName |
The name of the generated class. | I18n |
Namespace |
The namespace for the generated class. | project's root namespace |
Advanced options:
argument | description | default value |
---|---|---|
ClassModifiers |
The access modifiers to apply to the generated class (e.g. to make it public). | internal static |
CreateBackup |
Whether to add a backup of the generated class to the project folder in a Generated subfolder. If it's disabled, the generated file will be hidden and excluded from source control. |
false |