Getting Started

Use via Dependency Injection

1. Add Tlumach to your project:

a) via NuGet

Add a package reference to "Tlumach" to your project

via NuGet package manager GUI in Visual Studio
via the command line:

dotnet add package Tlumach

using the text editor - add the following reference to your project:

<ItemGroup>
    <PackageReference Include="Tlumach" Version="1.*" />
</ItemGroup>

b) with Source Code

Check out Tlumach from the Tlumach repository on GitHub
Add Tlumach.Base and Tlumach projects to your solution and reference them from your project(s).

2. Create a configuration file

Please see the detailed description of the configuration file here.

A simple configuration file for a start looks like this:

defaultFile=strings.toml

Save it to "strings.cfg".

The "strings.toml" file is a default file, i.e., a file with strings that will be retrieved by default.

3. Create a default translation file

Here is the minimal translation file in TOML format:

hello="Hello!"

Save it to "strings.toml".

4. Include translation files into your project

The minimal addition you need to make to your project are the "strings.cfg" file and the "strings.toml" file from the previous step.

Add "strings.cfg" and "strings.toml" to the project as Embedded Resource. You can use the IDE for this or edit the project file as text and add these lines:

<ItemGroup>
    <EmbeddedResource Include="strings.cfg" />
    <EmbeddedResource Include="strings.toml" />
</ItemGroup>

Alternatively, if you plan to load translations from the disk, you can both files as Content and specify that they should be copied to the output directory:

<Content Include="strings.cfg">
    <CopyToOutputDirectory>Always</CopyToOutputDirectory>
</Content>
<Content Include="strings.toml">
    <CopyToOutputDirectory>Always</CopyToOutputDirectory>
</Content>

But then, you will need to set LoadFromDisk property to true (you will create an instance of TranslationManager in your code as described below).

5. Initialize parsers

Before you can load a configuration and create a translation manager, you need to initialize the parsers for the formats you are using. In our sample, we use INI format for settings and TOML format for translations. So, you need to call the Use method of those two parsers:

using Tlumach;
...
IniParser.Use();
TomlParser.Use();

6. Setup Dependency Injection

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Localization;
using Tlumach;
...
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.DefaultFile = "strings.cfg",
                        }
                )
            )
            .Build();

If files are located on the disk, the procedure is a bit more complicated - you need to create an instance of TranslationManager class and use it for initialization:

TranslationManager manager = new TranslationManager("strings.cfg");
manager.LoadFromDisk = true;
...
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; 
                        }
                )
            )
            .Build();

7. Use translations in your code

The "hello" string from "string.toml" can be loaded via DI as follows:

var genericLocalizer = host.Services.GetRequiredService<IStringLocalizer>();
string helloValue = genericLocalizer["hello"];

If you used Generator in your project, you can access strings with syntax checking:

var genericLocalizer = host.Services.GetRequiredService<IStringLocalizer>();
string helloValue = genericLocalizer[Strings.Hello];

var genericLocalizer = host.Services.GetRequiredService<IStringLocalizer>();
string helloValue = genericLocalizer[Strings.HelloKey];

Strings.Hello is an instance of TranslationUnit, whereas Strings.HelloKey is a string constant. You can disable generation of TranslationUnit, if you don't need them, via a configuration file.

DI classes return the string that corresponds to the culture defined in CultureInfo.CurrentCulture property.

To access the translation for a specific culture (e.g., in a server application), retrieve an instance of IStringLocalizer for that locale:

var genericLocalizer = ((TlumachStringLocalizer)host.Services.GetRequiredService<IStringLocalizer>()).WithCulture(new CultureInfo("de-DE"));
string helloValue = genericLocalizer["hello"];

Remember that you need locale-specific files for other languages. For this, read about Translation Files and Formats

Table of Contents

Getting Started

Use via Dependency Injection