Class TranslationManager

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.

Inheritance

object

TranslationManager

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Tlumach

Assembly: Tlumach.dll

Syntax

public class TranslationManager

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.

Declaration

public TranslationManager(Assembly assembly, string configFile)

Parameters

Type	Name	Description
Assembly	assembly	The reference to the assembly, from which the configuration file should be loaded.
string	configFile	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

Type	Condition
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.

Declaration

public TranslationManager(string configFile)

Parameters

Type	Name	Description
string	configFile	The file with the configuration that specifies where to load translations from.

Exceptions

Type	Condition
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.

Declaration

public TranslationManager(TranslationConfiguration translationConfiguration)

Parameters

Type	Name	Description
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.

Declaration

public CultureInfo CurrentCulture { get; set; }

Property Value

Type	Description
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).

Declaration

public TranslationConfiguration? DefaultConfiguration { get; }

Property Value

Type	Description
TranslationConfiguration

LoadFromDisk

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

Declaration

public bool LoadFromDisk { get; set; }

Property Value

Type	Description
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.

Declaration

public string TranslationsDirectory { get; set; }

Property Value

Type	Description
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.

Declaration

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.

Declaration

public void DropTranslation(CultureInfo culture)

Parameters

Type	Name	Description
CultureInfo	culture	The culture, whose translation should be dropped.

GetTranslation(CultureInfo)

Declaration

public Translation? GetTranslation(CultureInfo culture)

Parameters

Type	Name	Description
CultureInfo	culture

Returns

Type	Description
Translation

GetValue(string)

Retrieves the value based on the default configuration and culture.

Declaration

public TranslationEntry GetValue(string key)

Parameters

Type	Name	Description
string	key	The key of the translation entry to retrieve.

Returns

Type	Description
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.

Declaration

public TranslationEntry GetValue(string key, CultureInfo culture)

Parameters

Type	Name	Description
string	key	The key of the translation entry to retrieve.
CultureInfo	culture	The culture, for which the entry is needed.

Returns

Type	Description
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.

Declaration

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

Parameters

Type	Name	Description
TranslationConfiguration	config	The configuration that specifies from where to load translations.
string	key	The key of the translation entry to retrieve.
CultureInfo	culture	The culture, for which the entry is needed.

Returns

Type	Description
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).

Declaration

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

Parameters

Type	Name	Description
IList<string>	fileNames	The list of names obtained from ListTranslationFiles(Assembly?, string).

Returns

Type	Description
IList<CultureInfo>	The list ofCultureInfo.

ListCulturesInConfiguration()

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

Declaration

public IList<string> ListCulturesInConfiguration()

Returns

Type	Description
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").

Declaration

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

Parameters

Type	Name	Description
Assembly	assembly	An optional assembly to look for translations.
string	defaultFileName	The base name of the file to look for. If it contains a recognized extension, the extension is stripped.

Returns

Type	Description
IList<string>	The list of filenames of files found in the corresponding directory.

LoadTranslation(string, string, CultureInfo?)

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

Declaration

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

Parameters

Type	Name	Description
string	translationText	The text to load the translation from.
string	fileExtension	The extension of the file to use for choosing the parser.
CultureInfo	culture	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.

Returns

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

Exceptions

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

LoadTranslation(string, BaseParser, CultureInfo?)

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

Declaration

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

Parameters

Type	Name	Description
string	translationText	The text to load the translation from.
BaseParser	parser	The parser to use for parsing the translationText text.
CultureInfo	culture	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.

Returns

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

Exceptions

Type	Condition
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.

Declaration

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).

Declaration

public event EventHandler<CultureChangedEventArgs>? OnCultureChanged

Event Type

Type	Description
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.

Declaration

public event EventHandler<FileContentNeededEventArgs>? OnFileContentNeeded

Event Type

Type	Description
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.

Declaration

public event EventHandler<TranslationValueEventArgs>? OnTranslationValueFound

Event Type

Type	Description
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.

Declaration

public event EventHandler<TranslationValueEventArgs>? OnTranslationValueNeeded

Event Type

Type	Description
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.

Declaration

public event EventHandler<TranslationValueEventArgs>? OnTranslationValueNotFound

Event Type

Type	Description
EventHandler<TranslationValueEventArgs>