Table of Contents

Interface ILocalizer

Namespace
RentADeveloper.ResXLocalization
Assembly
ResXLocalization.Core.dll

Resolves localized strings from one or more ResourceManager instances for a runtime-selectable culture, and raises change notifications so bindings update live when the culture changes - without reloading views.

public interface ILocalizer : INotifyPropertyChanged
Inherited Members

Remarks

Implementations are intended for UI-thread use: register resource managers at startup and switch CurrentCulture from the UI thread, so change notifications reach bindings on the thread WPF and Avalonia expect.

Properties

CurrentCulture

Gets or sets the culture used to resolve resources. Setting a different value raises PropertyChanged and CultureChanged, causing bound localized values to re-resolve.

CultureInfo CurrentCulture { get; set; }

Property Value

CultureInfo

The active culture. Defaults to CurrentUICulture.

Remarks

Setting this property changes only how this localizer resolves translations; it deliberately does not touch CurrentUICulture or DefaultThreadCurrentUICulture. ResXLocalization is a translation engine, not a formatting engine - if number, date, or currency formatting should follow the selected language too, set those thread cultures yourself when handling CultureChanged.

Exceptions

ArgumentNullException

The supplied value is null.

this[string]

Gets the localized string for the specified key by searching every registered ResourceManager in registration order.

string this[string key] { get; }

Parameters

key string

The resource key to resolve.

Property Value

string

The localized string for key in CurrentCulture; Empty if key is null or empty; or the configured missing-translation sentinel (by default !key!) if no registered resource manager contains the key.

MissingTranslationFormat

Gets or sets the composite format string that produces the sentinel returned for a key no lookup could resolve, where {0} is the key. Defaults to !{0}!, which renders a missing Greeting as !Greeting!.

string MissingTranslationFormat { get; set; }

Property Value

string

The sentinel format. Defaults to !{0}!.

Remarks

Configure this once at startup, before views load: changing it later does not re-resolve values that are already bound (only a culture change does that).

Exceptions

ArgumentNullException

The supplied value is null.

ArgumentException

The supplied value is not a valid composite format string for a single argument (the key) - for example {1}. It is validated on assignment so the defect surfaces here rather than on the first miss.

Methods

ClearResourceManagers()

Removes every registered ResourceManager from the search-all set. Typed and scoped lookups are unaffected - they never consult the registration set.

void ClearResourceManagers()

Get(ResourceKey)

Resolves the localized string for a typed ResourceKey, which carries both the key name and the owning ResourceManager.

string Get(ResourceKey key)

Parameters

key ResourceKey

The typed key identifying the resource and its resource manager.

Returns

string

The localized string for key in CurrentCulture, or the configured missing-translation sentinel (by default !key!) if the resource manager does not contain it.

Exceptions

ArgumentNullException

key is a default or otherwise uninitialized ResourceKey, whose Manager is null.

Get(ResourceKey, params object?[])

Resolves the localized string for a typed ResourceKey, then formats it as a composite format string with the supplied arguments in CurrentCulture.

string Get(ResourceKey key, params object?[] arguments)

Parameters

key ResourceKey

The typed key identifying the resource and its resource manager.

arguments object[]

The values to format into the resolved string.

Returns

string

The formatted, localized string, or the configured missing-translation sentinel (by default !key!), without applying arguments, if the resource manager does not contain the key.

Exceptions

ArgumentNullException

arguments is null, or key is a default or otherwise uninitialized ResourceKey whose Manager is null.

FormatException

The resolved resource value is not a valid composite format string for arguments.

Get(Enum, ResourceManager, string)

Resolves the localized string for an enumeration value from a single, explicit ResourceManager, mapping the value to a key using the convention {keyPrefix}{EnumTypeName}_{Value}.

string Get(Enum value, ResourceManager resourceManager, string keyPrefix = "Enum_")

Parameters

value Enum

The enumeration value to resolve.

resourceManager ResourceManager

The resource manager to read the generated key from.

keyPrefix string

The prefix prepended to the generated key. Defaults to Enum_.

Returns

string

The localized string for the generated key in CurrentCulture, or the configured missing-translation sentinel (by default !key!) if resourceManager does not contain it.

Exceptions

ArgumentNullException

value, resourceManager, or keyPrefix is null.

Get(Enum, string)

Resolves the localized string for an enumeration value by mapping it to a resource key using the convention {keyPrefix}{EnumTypeName}_{Value}, then searching every registered ResourceManager in registration order.

string Get(Enum value, string keyPrefix = "Enum_")

Parameters

value Enum

The enumeration value to resolve.

keyPrefix string

The prefix prepended to the generated key. Defaults to Enum_.

Returns

string

The localized string for the generated key in CurrentCulture, or the configured missing-translation sentinel (by default !key!) if no registered resource manager contains it.

Exceptions

ArgumentNullException

value or keyPrefix is null.

Get(string)

Resolves the localized string for the specified key by searching every registered ResourceManager in registration order.

string Get(string key)

Parameters

key string

The resource key to resolve.

Returns

string

The localized string for key in CurrentCulture; Empty if key is null or empty; or the configured missing-translation sentinel (by default !key!) if no registered resource manager contains the key.

Get(string, params object?[])

Resolves the localized string for the specified key by searching every registered ResourceManager in registration order, then formats it as a composite format string with the supplied arguments in CurrentCulture - for example a resource value of Downloading {0} of {1}….

string Get(string key, params object?[] arguments)

Parameters

key string

The resource key to resolve.

arguments object[]

The values to format into the resolved string.

Returns

string

The formatted, localized string; Empty if key is null or empty; or the configured missing-translation sentinel (by default !key!), without applying arguments, if no registered resource manager contains the key.

Exceptions

ArgumentNullException

arguments is null.

FormatException

The resolved resource value is not a valid composite format string for arguments. That is a defect in the resource file you want to surface during development, not a missing translation, so it fails loudly.

Get(string, ResourceManager)

Resolves the localized string for the specified key from a single, explicit ResourceManager.

string Get(string key, ResourceManager resourceManager)

Parameters

key string

The resource key to resolve.

resourceManager ResourceManager

The resource manager to read the key from.

Returns

string

The localized string for key in CurrentCulture; Empty if key is null or empty; or the configured missing-translation sentinel (by default !key!) if resourceManager does not contain the key.

Exceptions

ArgumentNullException

resourceManager is null.

Get(string, ResourceManager, params object?[])

Resolves the localized string for the specified key from a single, explicit ResourceManager, then formats it as a composite format string with the supplied arguments in CurrentCulture.

string Get(string key, ResourceManager resourceManager, params object?[] arguments)

Parameters

key string

The resource key to resolve.

resourceManager ResourceManager

The resource manager to read the key from.

arguments object[]

The values to format into the resolved string.

Returns

string

The formatted, localized string; Empty if key is null or empty; or the configured missing-translation sentinel (by default !key!), without applying arguments, if resourceManager does not contain the key.

Exceptions

ArgumentNullException

resourceManager or arguments is null.

FormatException

The resolved resource value is not a valid composite format string for arguments.

GetAvailableCultures()

Discovers the cultures for which any registered ResourceManager ships its own resources - the natural source for a language picker.

IReadOnlyList<CultureInfo> GetAvailableCultures()

Returns

IReadOnlyList<CultureInfo>

The union of the available cultures across every registered resource manager, sorted by culture name, with InvariantCulture (the neutral resources) first when present. Empty when nothing is registered.

Remarks

The neutral (fallback) resources embedded in the main assembly are reported as InvariantCulture, because a ResourceManager does not expose which language they are written in. Map it to the language you declared in <NeutralLanguage> when building a picker.

Discovery probes every known culture for a satellite assembly, which is I/O-bound: call it once at startup and cache the result rather than per lookup or per binding.

GetAvailableCultures(ResourceManager)

Discovers the cultures for which a single ResourceManager ships its own resources. See GetAvailableCultures() for how neutral resources are reported and why the result should be cached.

IReadOnlyList<CultureInfo> GetAvailableCultures(ResourceManager resourceManager)

Parameters

resourceManager ResourceManager

The resource manager to probe.

Returns

IReadOnlyList<CultureInfo>

The available cultures, sorted by culture name, with InvariantCulture (the neutral resources) first when present.

Exceptions

ArgumentNullException

resourceManager is null.

RegisterResourceManager(ResourceManager)

Registers a ResourceManager to be searched by the key-only and enum lookups. Managers are searched in registration order on a first-match-wins basis; registering the same manager more than once has no effect.

void RegisterResourceManager(ResourceManager resourceManager)

Parameters

resourceManager ResourceManager

The resource manager to add to the search set.

Exceptions

ArgumentNullException

resourceManager is null.

UnregisterResourceManager(ResourceManager)

Removes a previously registered ResourceManager from the search-all set, for example when the plugin or module that owns its strings is unloaded. Typed and scoped lookups are unaffected - they never consult the registration set.

bool UnregisterResourceManager(ResourceManager resourceManager)

Parameters

resourceManager ResourceManager

The resource manager to remove from the search set.

Returns

bool

true when the manager was registered and has been removed; false when it was not registered.

Exceptions

ArgumentNullException

resourceManager is null.

Events

CultureChanged

Occurs after CurrentCulture changes, carrying the previous and current culture. Subscribe to refresh values that are not resolved through a binding.

event EventHandler<CultureChangedEventArgs> CultureChanged

Event Type

EventHandler<CultureChangedEventArgs>

TranslationNotFound

Occurs whenever a lookup misses - no resource file could resolve the key for the current culture and the sentinel (see MissingTranslationFormat) is about to be returned. Normal .NET resource fallback runs first; subscribe to log keys that remain unresolved across the complete parent and neutral fallback chain.

event EventHandler<TranslationNotFoundEventArgs> TranslationNotFound

Event Type

EventHandler<TranslationNotFoundEventArgs>
Edit this page