Table of Contents

Class TranslationManager

Namespace
Tlumach
Assembly
Tlumach.dll

The core of Tlumach that manages translations, provides functions to enumerate translation files, and controls current language and locale used for translations.

Applications can use it to retrieve translation entries by their string key.

public class TranslationManager
Inheritance
TranslationManager
Inherited Members

Constructors

TranslationManager(Assembly, string)

Initializes a new instance of the TranslationManager class.

This constructor creates a translation manager based on the configuration that is to be loaded from the specified assembly. Such translation manager can be used to simplify access to translations when translation units are not used - an application simply calls the GetValue method and species the key and, optionally, the culture. 

public TranslationManager(Assembly assembly, string configFile)

Parameters

assembly Assembly

The reference to the assembly, from which the configuration file should be loaded.

configFile string

The name of the file to load the configuration from. This name must include a subdirectory (if any) in resource format, such as "Translations.Data" if the original files' subdirectory is "Translations\Data" or "Translations/Data".

Exceptions

GenericParserException

Thrown if the parser for the specified configuration file is not found.

ParserLoadException

Thrown if the parser failed to load the configuration file.

TranslationManager(string)

Initializes a new instance of the TranslationManager class.

This constructor creates a translation manager based on the configuration that is to be loaded from the disk file. Such translation manager can be used to simplify access to translations when translation units are not used - an application simply calls the GetValue method and species the key and, optionally, the culture. 

public TranslationManager(string configFile)

Parameters

configFile string

The file with the configuration that specifies where to load translations from.

Exceptions

GenericParserException

Thrown if the parser for the specified configuration file is not found.

ParserLoadException

Thrown if the parser failed to load the configuration file.

TranslationManager(TranslationConfiguration)

Initializes a new instance of the TranslationManager class.

This constructor creates a translation manager based on the specified configuration. Such translation manager can be used to simplify access to translations when translation units are not used - an application simply calls the GetValue method and species the key and, optionally, the culture. 

public TranslationManager(TranslationConfiguration translationConfiguration)

Parameters

translationConfiguration TranslationConfiguration

The configuration that specifies where to load translations from.

Properties

CurrentCulture

Gets or sets the culture, which will be used by the GetValue(string) method as a current culture.

public CultureInfo CurrentCulture { get; set; }

Property Value

CultureInfo

DefaultConfiguration

Gets the configuration used by this Translation Manager. May be empty if it was not set explicitly or by the generated class (when the Generator is used).

public TranslationConfiguration? DefaultConfiguration { get; }

Property Value

TranslationConfiguration

Empty

Gets an instance of the class that is empty, not linked to any translations.

public static TranslationManager Empty { get; }

Property Value

TranslationManager

LoadFromDisk

Gets or sets the indicator that tells TranslationManager to attempt to locate translation files on the disk.

public bool LoadFromDisk { get; set; }

Property Value

bool

TranslationsDirectory

Gets or sets the directory in which translations files are looked for.

When LoadFromDisk is disabled, this value is used when trying to load the translations from the assembly. When LoadFromDisk is enabled, this value is also used when trying to locate translation files on the disk.

This property is a hint for the manager, which affects loading of secondary translation files. When a configuration is loaded via the TranslationManager constructor, specify the directory in the name of the configuration file.

public string TranslationsDirectory { get; set; }

Property Value

string

Methods

DropAllTranslations()

"Forgets" all translation so that upon the next attempt to access any translation, they get loaded again.

The method is useful when it is necessary to rescan translations updated on the disk or in another storage.

public void DropAllTranslations()

DropTranslation(CultureInfo)

"Forgets" the translation for the given culture so that upon the next attempt to access it, the translation gets loaded again.

public void DropTranslation(CultureInfo culture)

Parameters

culture CultureInfo

The culture, whose translation should be dropped.

GetTranslation(CultureInfo)

Returns the translation object for the given culture if one exists.

public Translation? GetTranslation(CultureInfo culture)

Parameters

culture CultureInfo

The culture to retrieve the translation for.

Returns

Translation

The Translation instance if one was found and null otherwise or if culture was null.

GetValue(string)

Retrieves the value based on the default configuration and culture.

public TranslationEntry GetValue(string key)

Parameters

key string

The key of the translation entry to retrieve.

Returns

TranslationEntry

The translation entry or an empty entry if nothing was found.

GetValue(string, CultureInfo)

Retrieves the value based on the default configuration and culture.

public TranslationEntry GetValue(string key, CultureInfo culture)

Parameters

key string

The key of the translation entry to retrieve.

culture CultureInfo

The culture, for which the entry is needed.

Returns

TranslationEntry

The translation entry or an empty entry if nothing was found.

GetValue(TranslationConfiguration, string, CultureInfo)

Retrieves the value based on the default configuration and culture.

public TranslationEntry GetValue(TranslationConfiguration config, string key, CultureInfo culture)

Parameters

config TranslationConfiguration

The configuration that specifies from where to load translations.

key string

The key of the translation entry to retrieve.

culture CultureInfo

The culture, for which the entry is needed.

Returns

TranslationEntry

The translation entry or an empty entry if nothing was found.

GetValue(TranslationConfiguration, string, CultureInfo, out bool)

Retrieves the value based on the default configuration and culture.

public TranslationEntry GetValue(TranslationConfiguration config, string key, CultureInfo culture, out bool foundForCulture)

Parameters

config TranslationConfiguration

The configuration that specifies from where to load translations.

key string

The key of the translation entry to retrieve.

culture CultureInfo

The culture, for which the entry is needed.

foundForCulture bool

Upon return, indicates if the requested entry was found for the speciifed culture or its base culture. false will be returned if a value from the default translation was used.

Returns

TranslationEntry

The translation entry or an empty entry if nothing was found.

ListCultures(IList<string>)

From the list of available language files obtained using ListTranslationFiles(Assembly?, string), retrieve culture information (needed for language names and to switch application language).

public static IList<CultureInfo> ListCultures(IList<string> fileNames)

Parameters

fileNames IList<string>

The list of names obtained from ListTranslationFiles(Assembly?, string).

Returns

IList<CultureInfo>

The list ofCultureInfo.

ListCulturesInConfiguration()

Lists culture names listed in the configuration file, if one was used.

public IList<string> ListCulturesInConfiguration()

Returns

IList<string>

The list of culture names (every name is contained in uppercase).

ListTranslationFiles(Assembly?, string)

Scans the assembly and optionally a disk directory for translation files.

This method can recognize only the files with names that have the {base_name}_{locale-name}[.{supported_extension}] format, where 'locale-name' may be either language name (e.g., "en") or locale name (e.g., "en-US").

public IList<string> ListTranslationFiles(Assembly? assembly, string defaultFileName)

Parameters

assembly Assembly

An optional assembly to look for translations.

defaultFileName string

The base name of the file to look for. If it contains a recognized extension, the extension is stripped.

Returns

IList<string>

The list of filenames of files found in the corresponding directory.

LoadTranslation(string, string, CultureInfo?, TextFormat?)

Loads the translation from the given text, choosing the parser based on the extension.

public static Translation? LoadTranslation(string translationText, string fileExtension, CultureInfo? culture, TextFormat? textProcessingMode)

Parameters

translationText string

The text to load the translation from.

fileExtension string

The extension of the file to use for choosing the parser.

culture CultureInfo

An optional reference to the locale, whose translation is to be loaded. Makes sense for CSV and TSV formats that may contain multiple translations in one file.

textProcessingMode TextFormat?

The required text processing mode.

Returns

Translation

A Translation instance or null if the parser could not be selected or if the parser failed to load the translation.

Exceptions

GenericParserException

and its descendants are thrown if parsing fails due to errors in format of the input.

LoadTranslation(string, BaseParser, CultureInfo?, TextFormat?)

Loads the translation from the given text using the specified parser.

public static Translation? LoadTranslation(string translationText, BaseParser parser, CultureInfo? culture, TextFormat? textProcessingMode)

Parameters

translationText string

The text to load the translation from.

parser BaseParser

The parser to use for parsing the translationText text.

culture CultureInfo

An optional reference to the locale, whose translation is to be loaded. Makes sense for CSV and TSV formats that may contain multiple translations in one file.

textProcessingMode TextFormat?

The required text processing mode.

Returns

Translation

A Translation instance or null if the parser failed to load the translation.

Exceptions

GenericParserException

and its descendants are thrown if parsing fails due to errors in format of the input.

SystemCultureUpdated()

This method should be called when a change of the system culture is detected, so that IF the default culture of the TranslationManager is set to CurrentCulture, the manager can notify listeners about the change.

public void SystemCultureUpdated()

Events

OnCultureChanged

The event is fired when the CurrentCulture property is changed by the application. It is used primarily by the reactive classes in XAML packages (Tlumach.MAUI, Tlumach.Avalonia, Tlumach.WPF, Tlumach.WinUI).

public event EventHandler<CultureChangedEventArgs>? OnCultureChanged

Event Type

EventHandler<CultureChangedEventArgs>

OnFileContentNeeded

The event is fired when the content of the file is to be loaded. A handler can provide file content from another location.

public event EventHandler<FileContentNeededEventArgs>? OnFileContentNeeded

Event Type

EventHandler<FileContentNeededEventArgs>

OnTranslationValueFound

The event is fired after a translation of a certain key has been found in a file.

Should a handler need to provide a different value, it may change the text in the Text property or replace the reference in the Entry property of the arguments.

public event EventHandler<TranslationValueEventArgs>? OnTranslationValueFound

Event Type

EventHandler<TranslationValueEventArgs>

OnTranslationValueNeeded

The event is fired when the translation of a certain key is requested. A handler can provide a different text or even a reference which will be resolved. If the returned values are valid and accepted (e.g., a reference is properly resolved), the value is returned without firing OnTranslationValueFound.

public event EventHandler<TranslationValueEventArgs>? OnTranslationValueNeeded

Event Type

EventHandler<TranslationValueEventArgs>

OnTranslationValueNotFound

The event is fired after a translation of a certain key has not been found in a file.

Should a handler decide to provide some value, it may set the text in the Text property or place a reference in the Entry property of the arguments.

public event EventHandler<TranslationValueEventArgs>? OnTranslationValueNotFound

Event Type

EventHandler<TranslationValueEventArgs>