Class LocalizationService

Provides the base class for service for localized resources for a specific culture.

Inheritance

System.Object

LocalizationService

MemoryLocalizationService

ProviderBasedLocalizationService

Namespace: EPiServer.Framework.Localization

Assembly: EPiServer.Framework.dll

Version: 12.0.3

Syntax

public abstract class LocalizationService : Object

Constructors

LocalizationService()

Exposed for easier usage in tests

Declaration

protected LocalizationService()

LocalizationService(ResourceKeyHandler)

Initializes a new instance of the LocalizationService class with default ICurrentCultureAccessor implementation.

Declaration

protected LocalizationService(ResourceKeyHandler keyHandler)

Parameters

Type	Name	Description
ResourceKeyHandler	keyHandler	The handler used to manipulate resource keys.

LocalizationService(ResourceKeyHandler, ICurrentCultureAccessor)

Initializes a new instance of the LocalizationService class.

Declaration

protected LocalizationService(ResourceKeyHandler keyHandler, ICurrentCultureAccessor currentCultureAccessor)

Parameters

Type	Name	Description
ResourceKeyHandler	keyHandler	The handler used to manipulate resource keys.
ICurrentCultureAccessor	currentCultureAccessor	The culture accessor used to resolve current culture

Fields

MissingMessageFormat

The formatting string that is used when a key is missing for a language.

Declaration

public static readonly string MissingMessageFormat

Field Value

Type	Description
System.String

Properties

AvailableLocalizations

Gets all available localizations that the LocalizationService has knowledge of.

Declaration

public abstract IEnumerable<CultureInfo> AvailableLocalizations { get; }

Property Value

Type	Description
System.Collections.Generic.IEnumerable<System.Globalization.CultureInfo>

Remarks

An available localizations does not need to contain any translations.

Available languages should never contain the System.Globalization.CultureInfo.InvariantCulture even though it may be supported by the LocalizationService.

Current

Gets the current LocalizationService instance.

Declaration

public static LocalizationService Current { get; }

Property Value

Type	Description
LocalizationService

Remarks

This is a shortcut to the ServiceLocator for the current service, but it is guaranteed to never be null.

CurrentCultureAccessor

Gets the accessor used to resolve current culture.

Declaration

protected ICurrentCultureAccessor CurrentCultureAccessor { get; }

Property Value

Type	Description
ICurrentCultureAccessor

FallbackBehavior

Gets or sets the fallback behavior to use when no resource is found.

Declaration

public virtual FallbackBehaviors FallbackBehavior { get; set; }

Property Value

Type	Description
FallbackBehaviors	The fallback behavior.

Remarks

The value can be set by configuration (see 'EPiServer.Framework.Configuration.LocalizationElement') or by code.

If contains Echo then if key does not start with a '#' of a '/', the resourceKey is returned back unmodified when no match is found.
If contains MissingMessage then if no match for key is found will return a message stating that the resource could not be found.

The reason for the possibility to use an echo behavior is to be able to use EPiServer web controls that use Translate for visible strings, where you might not have translations in place, or maybe do not want to translate the text.

FallbackCulture

Gets or sets the fallback culture to use if a resource is not found for the requested culture.

Declaration

public virtual CultureInfo FallbackCulture { get; set; }

Property Value

Type	Description
System.Globalization.CultureInfo	The fallback culture to use.

Remarks

Note that the FallbackBehaviors must contain the FallbackCulture flag for this culture to be used.

KeyHandler

Gets the handler that is used to manipulate resource keys.

Declaration

protected ResourceKeyHandler KeyHandler { get; }

Property Value

Type	Description
ResourceKeyHandler

Methods

GetAllStrings()

Gets all localized strings for the current UI culture.

Declaration

public IEnumerable<ResourceItem> GetAllStrings()

Returns

Type	Description
System.Collections.Generic.IEnumerable<ResourceItem>	All resource strings for the current UI culture.

GetAllStrings(String)

Gets all localized strings for the current UI culture below the specified key.

Declaration

public IEnumerable<ResourceItem> GetAllStrings(string resourceKey)

Parameters

Type	Name	Description
System.String	resourceKey	The key that represents the localized string to get.

Returns

Type	Description
System.Collections.Generic.IEnumerable<ResourceItem>	All localized strings for the current UI culture below the specified key.

Remarks

If the key is empty, all strings will be returned.

GetString(String) for information on the format of resourceKey.

GetAllStringsByCulture(CultureInfo)

Gets all localized strings for the specified culture.

Declaration

public IEnumerable<ResourceItem> GetAllStringsByCulture(CultureInfo culture)

Parameters

Type	Name	Description
System.Globalization.CultureInfo	culture	The requested culture for the localized strings.

Returns

Type	Description
System.Collections.Generic.IEnumerable<ResourceItem>	All localized strings for the given culture.

GetAllStringsByCulture(String, CultureInfo)

Gets all localized strings for the specified culture below the specified key.

Declaration

public virtual IEnumerable<ResourceItem> GetAllStringsByCulture(string resourceKey, CultureInfo culture)

Parameters

Type	Name	Description
System.String	resourceKey	The key that represents the localized string to get.
System.Globalization.CultureInfo	culture	The requested culture for the localized strings.

Returns

Type	Description
System.Collections.Generic.IEnumerable<ResourceItem>	All localized strings below the specified key.

Remarks

If the key is empty, all strings will be returned.

GetString(String) for information on the format of resourceKey.

GetAllStringsByCulture(String, String[], CultureInfo)

Gets all localized strings for the specified culture below the specified key.

Declaration

protected abstract IEnumerable<ResourceItem> GetAllStringsByCulture(string originalKey, string[] normalizedKey, CultureInfo culture)

Parameters

Type	Name	Description
System.String	originalKey	The original key that was passed into any GetString method.
System.String[]	normalizedKey	The `originalKey` normalized and split into an array
System.Globalization.CultureInfo	culture	The requested culture for the localized strings.

Returns

Type	Description
System.Collections.Generic.IEnumerable<ResourceItem>	All localized strings below the specified key.

GetMissingMessage(String, CultureInfo)

Gets a missing message string

Declaration

public static string GetMissingMessage(string resourceKey, CultureInfo culture)

Parameters

Type	Name	Description
System.String	resourceKey	The resource that is missing
System.Globalization.CultureInfo	culture	The culture that the key is missing for

Returns

Type	Description
System.String	A missing message

GetString(String)

Gets the localized string for the specified key in the current UI culture.

Declaration

public string GetString(string resourceKey)

Parameters

Type	Name	Description
System.String	resourceKey	The key that represents the localized string to get.

Returns

Type	Description
System.String	A localized string.

Remarks

The resourceKey is default typically something like "/admin/settings/heading", where the expression closely follows the folder/file/usage pattern. You can also enter a '#' to automatically constuct a path to the current file. For example when calling GetString("#heading") from the file /templates/mypage.aspx it is equivalent to calling GetString("/templates/mypage/heading").

The return value when no match for resourceKey is found is dependent on the value of the FallbackBehavior property.

Multiple fallback behaviors can be combined, but fallback will always be evaluated in the follwing order (if specified):

FallbackCulture
Explicit fallback string
Echo
MissingMessage
Null

If no fallback is specified an empty string will be returned.

GetString(String, FallbackBehaviors)

Gets the localized string for the specified key in the current UI culture using the provided fallback behavior.

Declaration

public string GetString(string resourceKey, FallbackBehaviors fallbackBehavior)

Parameters

Type	Name	Description
System.String	resourceKey	The key that represents the localized string to get.
FallbackBehaviors	fallbackBehavior	The fallback behavior to use if the resource is not found.

Returns

Type	Description
System.String	A localized string.

Remarks

GetString(String) for information on the format of resourceKey.

GetString(String, String)

Gets the localized string for the specified key in the current UI culture.

Declaration

public string GetString(string resourceKey, string fallback)

Parameters

Type	Name	Description
System.String	resourceKey	The key that represents the localized string to get.
System.String	fallback	The string to return if no match was found for `resourceKey`.

Returns

Type	Description
System.String	A localized string or `fallback`.

Remarks

GetString(String) for information on the format of resourceKey.

GetStringByCulture(String, FallbackBehaviors, CultureInfo)

Gets the localized string for the specified key in the specified culture using the provided fallback behavior.

Declaration

public virtual string GetStringByCulture(string resourceKey, FallbackBehaviors fallbackBehavior, CultureInfo culture)

Parameters

Type	Name	Description
System.String	resourceKey	The key that represents the localized string to get.
FallbackBehaviors	fallbackBehavior	The fallback behavior to use if the resource is not found.
System.Globalization.CultureInfo	culture	The requested culture for the localized string.

Returns

Type	Description
System.String	A localized string.

Remarks

GetString(String) for information on the format of resourceKey.

GetStringByCulture(String, FallbackBehaviors, String, CultureInfo)

Gets the localized string for the specified key in the specified culture using the provided fallback behavior.

Declaration

public virtual string GetStringByCulture(string resourceKey, FallbackBehaviors fallbackBehavior, string fallback, CultureInfo culture)

Parameters

Type	Name	Description
System.String	resourceKey	The key that represents the localized string to get.
FallbackBehaviors	fallbackBehavior	The fallback behavior to use if the resource is not found.
System.String	fallback	A string that should be returned if no match was found for `resourceKey`.
System.Globalization.CultureInfo	culture	The requested culture for the localized string.

Returns

Type	Description
System.String	A localized string.

Remarks

GetString(String) for information on the format of resourceKey.

GetStringByCulture(String, CultureInfo)

Gets the localized string for the specified key in the specified culture using the standard fallback behavior.

Declaration

public string GetStringByCulture(string resourceKey, CultureInfo culture)

Parameters

Type	Name	Description
System.String	resourceKey	The key that represents the localized string to get.
System.Globalization.CultureInfo	culture	The requested culture for the localized string.

Returns

Type	Description
System.String	A localized string.

GetStringByCulture(String, String, CultureInfo)

Gets the localized string for the specified key in the specified culture.

Declaration

public string GetStringByCulture(string resourceKey, string fallback, CultureInfo culture)

Parameters

Type	Name	Description
System.String	resourceKey	The key that represents the localized string to get.
System.String	fallback	The string to return if no match was found for `resourceKey`.
System.Globalization.CultureInfo	culture	The requested culture for the localized string.

Returns

Type	Description
System.String	A localized string or `fallback`.

Remarks

GetString(String) for information on the format of resourceKey.

LoadString(String[], String, CultureInfo)

Gets the localized string for the specified key in the specified culture.

Declaration

protected abstract string LoadString(string[] normalizedKey, string originalKey, CultureInfo culture)

Parameters

Type	Name	Description
System.String[]	normalizedKey	The `originalKey` normalized and split into an array.
System.String	originalKey	The original key that was passed into any GetString method.
System.Globalization.CultureInfo	culture	The requested culture for the localized string.

Returns

Type	Description
System.String	A localized string or `null` if no resource is found for the given key and culture.

Remarks

Any implementation must make sure that if no resource is found for the given key and culture, null must be returned.

NormalizeKey(String)

Normalizes the resource key to an array of key parts split on forward slash (/). If the key starts with a hash (#), it will use the current request path to resolve the key.

Declaration

protected virtual string[] NormalizeKey(string resourceKey)

Parameters

Type	Name	Description
System.String	resourceKey	The resource key to normalize. The key must start with '/' or '#' for the key to be normalized.

Returns

Type	Description
System.String[]	An normalized array with key parts.

Remarks

Raises the KeyNormalized event once normalization is complete. This event allows for external code to modify the standard normalization behavior.

OnKeyNormalized(ResourceKeyNormalizedEventArgs)

Raises the KeyNormalized event.

Declaration

protected virtual void OnKeyNormalized(ResourceKeyNormalizedEventArgs args)

Parameters

Type	Name	Description
ResourceKeyNormalizedEventArgs	args	The ResourceKeyNormalizedEventArgs instance containing the event data.

TryGetString(String, out String)

Tries to get the localized string for the specified key in the current UI culture.

Declaration

public bool TryGetString(string resourceKey, out string localizedString)

Parameters

Type	Name	Description
System.String	resourceKey	The key that represents the localized string to get.
System.String	localizedString	The localized string that if found will be populated. If not found it will be set to null.

Returns

Type	Description
System.Boolean	`true` if a localized string is found; otherwise `false`.

Remarks

GetString(String) for information on the format of resourceKey.

TryGetStringByCulture(String, CultureInfo, out String)

Tries to get the localized string for the specified key in the specified culture.

Declaration

public virtual bool TryGetStringByCulture(string resourceKey, CultureInfo culture, out string localizedString)

Parameters

Type	Name	Description
System.String	resourceKey	The key that represents the localized string to get.
System.Globalization.CultureInfo	culture	The requested culture for the localized string.
System.String	localizedString	The localized string that if found will be populated. If not found it will be set to null.

Returns

Type	Description
System.Boolean	`true` if a localized string is found; otherwise `false`.

Remarks

GetString(String) for information on the format of resourceKey.

TryGetStringByCulture(String, String[], CultureInfo, CultureInfo, out String)

Tries to get the localized string for the specified key in the specified culture.

Declaration

protected virtual bool TryGetStringByCulture(string originalKey, string[] normalizedKey, CultureInfo culture, CultureInfo fallbackCulture, out string localizedString)

Parameters

Type	Name	Description
System.String	originalKey	The original key that was passed into any GetString method.
System.String[]	normalizedKey	The `originalKey` normalized and split into an array
System.Globalization.CultureInfo	culture	The requested culture for the localized string.
System.Globalization.CultureInfo	fallbackCulture	The fallback culture that should be used if no string is found for the requested culture or it's parents.
System.String	localizedString	The localized string that if found will be populated. If not found it will be set to null.

Returns

Type	Description
System.Boolean	`true` if a localized string is found; otherwise `false`.

TryGetStringByCulture(String, String[], CultureInfo, out String)

Tries to get the localized string for the specified key in the specified culture.

Declaration

protected virtual bool TryGetStringByCulture(string originalKey, string[] normalizedKey, CultureInfo culture, out string localizedString)

Parameters

Type	Name	Description
System.String	originalKey	The original key that was passed into any GetString method.
System.String[]	normalizedKey	The `originalKey` normalized and split into an array
System.Globalization.CultureInfo	culture	The requested culture for the localized string.
System.String	localizedString	The localized string that if found will be populated. If not found it will be set to null.

Returns

Type	Description
System.Boolean	`true` if a localized string is found; otherwise `false`.

Events

ResourceKeyNormalized

Occurs when a resource key has been normalized. At this time you have the opportunity to modify the contents of this array.

Declaration

public event EventHandler<ResourceKeyNormalizedEventArgs> ResourceKeyNormalized

Event Type

Type	Description
System.EventHandler<ResourceKeyNormalizedEventArgs>

Remarks

If you modify the contents of the normalized array, you should always ensure that it is not null.

Extension Methods

IdentityObjectExtensions.GetIdentity(Object)

IdentityObjectExtensions.SetIdentity(Object, Identity)

PropertyBagObjectsExtensions.ToPropertyBag(Object)

PropertyBagObjectsExtensions.ToPropertyBag(Object, IEnumerable<String>)

RuntimeModelExtensions.GetOriginalType(Object)