Try our conversational search powered by Generative AI!

AI OnAI Off

Class LocalizationService

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

Inheritance
System.Object
LocalizationService
MemoryLocalizationService
ProviderBasedLocalizationService
Inherited Members
System.Object.ToString()
System.Object.Equals(System.Object)
System.Object.Equals(System.Object, System.Object)
System.Object.ReferenceEquals(System.Object, System.Object)
System.Object.GetHashCode()
System.Object.GetType()
System.Object.MemberwiseClone()
Namespace: EPiServer.Framework.Localization
Assembly: EPiServer.Framework.dll
Version: 11.20.7
Syntax
public abstract class LocalizationService

Constructors

LocalizationService(ResourceKeyHandler)

Initializes a new instance of the LocalizationService class.

Declaration
protected LocalizationService(ResourceKeyHandler keyHandler)
Parameters
Type Name Description
ResourceKeyHandler keyHandler

The handler used to manipulate resource keys.

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.

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

  1. FallbackCulture
  2. Explicit fallback string
  3. Echo
  4. MissingMessage
  5. 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

See Also