Getting Started

Integration with Avalonia

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, Tlumach, and Tlumach.Avalonia 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
generatedClass=Strings
generatedNamespace=Tlumach.Sample

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. Create and set up a translation project

This is a C# project separate from your main code project(s); this translation project does not need any source code in it.

Please see the detailed description of setting up a translation project here.

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

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

<ItemGroup>
    <AdditionalFiles Include="strings.cfg" />
</ItemGroup>

Next, add "strings.toml" to the project as Embedded Resource:

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

Alternatively, if you plan to load translations from the disk, you can add a file as Content, but then, you will need to set LoadFromDisk property to true. The TranslationManager instance will be accessible to you as a static object named "Tlumach.Sample.Strings.TranslationManager".

Important: In Avalonia, you also need to add the following lines to your translation projects to tell Generator from which namespace to take the TranslationUnit class (WinUI has own class with this name):

<PropertyGroup>
    <TlumachGeneratorUsingNamespace>Tlumach.Avalonia</TlumachGeneratorUsingNamespace>
</PropertyGroup>
<ItemGroup>
    <!-- Makes the property visible to analyzers/generators -->
    <CompilerVisibleProperty Include="TlumachGeneratorUsingNamespace" />
</ItemGroup>

5. Add required references to your translation project

If you use NuGet, add a package reference to the Tlumach package to your translation project:

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

If you are using Tlumach Source Code, add project references as follows:

    <ItemGroup>
        <ProjectReference Include="Tlumach\src\Tlumach.Generator\Tlumach.Generator.csproj" OutputItemType="Analyzer" ReferenceOutputAssembly="false" />
		<ProjectReference Include="Tlumach\src\Tlumach.Avalonia\Tlumach.Avalonia.csproj" />
        <ProjectReference Include="Tlumach\src\Tlumach.Base\Tlumach.Base.csproj" />
        <ProjectReference Include="Tlumach\src\Tlumach\Tlumach.csproj" />
    </ItemGroup>

6. Reference the translation project from your main project

7. Build translation project

This step is needed so that Generator creates the source code with generated translation units, which you will reference in your code.

8. Use generated translation units in your Avalonia project

The "hello" string from "string.toml" is available in your main project as a static object named "Tlumach.Sample.Strings.hello", to which you can bind your XAML attributes.

Switching languages

To switch current language (the one used in the XAML bindings), assign a new value to CurrentCulture:

using Tlumach.Sample;
...
CultureInfo deCulture = new CultureInfo("de-DE");
Strings.TranslationManager.CurrentCulture = deCulture;

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