Tlumach.NET is a flexible library that provides translation and localization support to all kinds of .NET applications: from desktop WinForms, UWP, WPF, WinUI, and console to mobile MAUI and Avalonia to server Razor and Blazor.
The goal of the library is to support different formats of translation files and to support different languages and locales concurrently (even within one thread). Also, Tlumach works with source files residing in resources or in disk files, which makes maintenance of translations easier than dealing with resource compilation and language DLLs. Finally, the application language can be switched without restarting the application. And if you are bound to .resx format, Tlumach supports .resx files in their source form (no compilation required).
The features of Tlumach include:
- Integration with XAML (in WPF, UWP, WinUI, MAUI, and Avalonia projects) via bindings to provide localized UI. The markup extension is provided for easy integration.
- Dependency Injection support and integration with Microsoft.Extensions.Localization.
- Low-level use via the translation manager or by accessing generated translation units, which enable syntax checking in design time.
- The Generator class to generate source code with translation units for static use and for XAML UIs during compilation of the project.
- Suitable for server and web applications thanks to the possibility to obtain translations for different languages/locales concurrently, even within one thread.
- Support for on-the-fly switching of current language/locale with automatic update of the UI (for XAML UIs).
- Automatic fallback to the basic locale (e.g., "de-AT" -> "de-DE") translation or to the default translation if a translation for a particular key is not available in the locale-specific translation.
- Handling of translation files in JSON, Arb (JSON with additional features, used in Dart/Flutter), simple INI, TOML, CSV and TSV, and .NET ResX files.
- Loading of translations from assembly resources, from disk files, or from a custom source (via events).
- Smart search for localized files using ISO 639-1 names (e.g., "de" or "hr") and using RFC 5646 locale identifiers (e.g., "de-AT", "pt-BR"). It is also possible to specify custom names for files with translations via a configuration file or to provide translation files via events, making it possible to fetch the translations from the network.
- Support for multiple translation sets in one project. For example, you can keep server log strings in one file and client messages in another.
- Each translation set can have a hierarchy of groups of translation entries, enabling easy management of translations (depending on the source format).
- Automatic recognition and support for templated strings in Arb and .NET formats. This includes support for .NET- and Arb-style placeholders and support of main Unicode and ICU features ("number", "select", "plural", "selectordinal", "date", "time", "datetime" placeholder kinds) in Arb-style placeholders. (Note: placeholder style is independent of the file format, i.e., you can use Arb-style placeholders in a ResX or TOML translation file.)
- The possibility to control the found translation entries or provide entries for missing keys via events (it may be necessary if an application should use some phrases configured by a user rather than from translations).
- Compatibility with AOT compilation.
- .NET 10.0 (a dedicated set of assemblies is provided)
- .NET 9.0 (a dedicated set of assemblies is provided)
- Anything that loads .NET Standard 2.0 assemblies
...on any operating system capable of running .NET 9+ or loading .NET Standard 2.0 assemblies.
Tlumach documentation can be conveniently read in the Tlumach section of Allied Bits site. The source files of the documentation are available in the Tlumach repository on GitHub, in the "docs" directory.
For general discussions and suggestions, you are welcome to use the Discussions section.
If you need help with issues or want to report a bug, please open an issue and include the necessary details (including the relevant configuration and translation files) to help us better understand the problem. Providing this information will aid in resolving the issue effectively.
There are several ways to use Tlumach depending on what type of application you have. The included samples cover the use with XAML-based frameworks (most common scenario for desktop and mobile development), and they also show how a text and its translations can be accessed from code (useful in web applications and servers). For a formal guidance on getting started, please check the Getting Started section of the documentation.