Pathoschild.Stardew.ModTranslationClassBuilder 2.1.0

ModTranslationClassBuilder autogenerates a strongly-typed class to access i18n translation files from your SMAPI mod code.

Contents

• Why does this exist?
• Usage
  • First-time setup
  • Conventions
• Customization
• See also

Why does this exist?

Without the package

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.

With the package

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.

Usage

First-time setup

1. Install the NuGet package.
2. 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.

Conventions

• 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()

Customization

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:

Advanced options:

See also

• Release notes