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 : BaseTranslationManager, IDisposable

Inheritance

object

BaseTranslationManager

TranslationManager

Implements

IDisposable

Inherited Members

BaseTranslationManager._defaultConfig

BaseTranslationManager._defaultTranslation

BaseTranslationManager.Translations

BaseTranslationManager.DefaultConfiguration

BaseTranslationManager.LoadFromDisk

BaseTranslationManager.TranslationsDirectory

BaseTranslationManager.GetTranslation(CultureInfo, bool)

BaseTranslationManager.LoadTranslation(CultureInfo)

BaseTranslationManager.InternalLoadTranslation(TranslationConfiguration, CultureInfo, bool)

BaseTranslationManager.InternalLoadFileContent(Assembly, string, string, ref string, string)

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

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

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

CacheDefaultTranslations

Gets or sets the flag that specifies whether the translation manager should store values from the basic culture or default translation in locale-specific translations (in memory) for optimization as described further.

If a translation text is requested but not found in a locale-specific translation, it is searched in a basic culture translation and then in default culture. If an entry is found there, it may be stored in the locale-specific and basic culture translations; this is done depending on this property.

Caching makes sense in most cases unless you expect that the missing value may become available in the future (e.g., when files are loaded from the disk and you are translating your text to a new language and placing a file to the translation directory for verification in your application).

public bool CacheDefaultTranslations { get; set; }

Property Value

bool

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

Empty

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

public static TranslationManager Empty { get; }

Property Value

TranslationManager

TranslationManagers

public static IReadOnlyList<TranslationManager> TranslationManagers { get; }

Property Value

IReadOnlyList<TranslationManager>

Methods

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

Dispose(bool)

protected virtual void Dispose(bool disposing)

Parameters

disposing bool

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.

GetContent(Assembly?, string, CultureInfo)

protected override string GetContent(Assembly? assembly, string fileName, CultureInfo culture)

Parameters

assembly Assembly

fileName string

culture CultureInfo

Returns

string

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

The "_" character (underscore) is defined in the LocaleSeparatorChar property of the parser classes and can be replaced by another character if needed.

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.

LoadDefaultTranslation(string)

Locates and loads the default translation.

This method is intended to be used when working with the writer classes.

public Translation? LoadDefaultTranslation(string fileName)

Parameters

fileName string

The filename from which the translation should be loaded.

Returns

Translation

A Translation instance or null if a translation could not be loaded.

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.

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

TranslationFileNotFound(CultureInfo)

protected override Translation TranslationFileNotFound(CultureInfo culture)

Parameters

culture CultureInfo

Returns

Translation

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>

OnReferenceNotResolved

The event is fired when a translation entry contains a reference to an external file that could not be resolved.

Should a handler decide to take the text from another place or provide an error message in place of the translation text, it may set the text in the Text property.

public event EventHandler<ReferenceNotResolvedEventArgs>? OnReferenceNotResolved

Event Type

EventHandler<ReferenceNotResolvedEventArgs>

OnTranslationFileNotFound

The event is fired when the translation file for a given locale was looked for but not found. A handler can use a translation from a different non-default locale or otherwise substitute the translation.

public event EventHandler<TranslationFileNotFoundEventArgs>? OnTranslationFileNotFound

Event Type

EventHandler<TranslationFileNotFoundEventArgs>

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>