Using Tlumach via Dependency Injection

Dependency Injection lets you instantiate libraries at one location of your code and then use them in a more generic way than with direct references to classes and objects.

Tlumach supports this model since version 1.2. At the same time, the way Microsoft implemented the interface (IStringLocalizer) - by using a string for a key/name of the translation unit - makes it error-prone. The approach Tlumach offers via auto-generated TranslationUnit instances is more robust because with it, any typo in the key/ name will be detected by the compiler. Due to this, we recommend using DI only when you are already using it in your project and need to replace your current translation code with Tlumach.

An alternative approach is to use Generator to generate TranslationUnit instances and/or string constants and then use those instances and constants as keys. As you will see below, Tlumach supports this model that provides grounds for syntax checking and avoiding typos.

What to Reference

Tlumach includes the "Tlumach.Extensions.Localization" project if you use the source code and the assembly with the same name if you use NuGet.

Setting Up DI

Here's the sample C# Code:

TranslationManager manager = new TranslationManager(new TranslationConfiguration(Assembly.GetExecutingAssembly(), "sample.cfg", null, TextFormat.Arb));
...
var host = Host.CreateDefaultBuilder(args)
            .ConfigureServices(services =>
                services.AddTlumachLocalization(
                    // These are the default settings. They are used when you request IStringLocalizer without context.
                    options => 
                        { 
                            options.TranslationManager = manager; 
                        },

                    // These are the options for the countext-bound IStringLocalizer<Tlumach.Sample.Strings> (the class name is an example)
                    provider => provider.AddContext("Tlumach.Sample.Strings", new TlumachLocalizationOptions()
                        {
                            TranslationManager = Strings.TranslationManager,
                        })
                )
            )
            .Build();

What this code does is register the necessary classes and configures the options. "Global" options are used for instances of IStringLocalizer created without a context. When we want to use context and options specific to that context, we use the "provider" parameter to create and register these individual options using the name of the context.

Using Tlumach via DI

The use of Tlumach via DI and IStringLocalizer interfaces is no different from any translation engine:

var genericLocalizer = host.Services.GetRequiredService<IStringLocalizer>();
Console.WriteLine(genericLocalizer["HelloName", "John Doe"]);
...
var localizer = host.Services.GetRequiredService<IStringLocalizer<Strings>>();
Console.WriteLine(localizer["Welcome"]);
// or use this form which enables syntax checking:
Console.WriteLine(localizer[Strings.Welcome]);
// or use this form which enables syntax checking too. 
// WelcomeKey is a string constant, generated by Generator
Console.WriteLine(localizer[Strings.WelcomeKey]);

The first localizer accesses strings using the options provided as global in the setup code below.

The second localizer uses options provided for the given scope. The "Strings" type here is an autogenerated class that includes a property named "TranslationManager". The IStringLocalizer implementation will take the TranslationManager instance and use it to find the translated string with the "Welcome" name. The use of the autogenerated class also enables referencing translation units or string constants for the purpose of syntax checking.

More About Options

TlumachLocalizationOptions objects include different properties that let you reference an instance of TranslationManager or create a new instance. If the TranslationManager property is set, an IStringLocalizer implementation will use the value from this property and ignore the other settings. If the TranslationManager property is null and Configuration is not null, an IStringLocalizer implementation will use this configuration to create a new instance of TranslationManager. And if Configuration is null, the other properties are used to create an instance of TranslationConfiguration and then this new configuration is used to create an instance of TranslationManager. Note that in the latter scenario you don't need a configuration file, you need only the default translation file.

Each instance of TlumachLocalizationOptions may include a reference to a different translation set.