Localization Service

Introduction

Starting with the EPiServer 7 release the preferred way to retrieve localized string resources are through the LocalizationService API. The currently configured and active EPiServer.Framework.Localization.LocalizationService can be retrieved using the EPiServer.Framework.Localization.LocalizationService.Current static property or by requesting it from the service locator using the EPiServer.ServiceLocation.ServiceLocator.Current property and GetInstance method.

Retrieving a Localized String

To retrieve a localized string, simply call the GetString method with a key that represents the requested resource. The key should normally start with a forward slash ‘/’ and can be made up by several sections, each separated by a forward slash. The key can also start with the hash # character indicating that the key should be prefixed with the current request path, for example, calling GetString with the key “#myKey” from the template located at “/templates’page.aspx” will be the equivalent of calling it with the key “/templates/page/myKey”.

Example:

CopyXML

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<languages>
    <language name="English" id="en">
        <mystring>my string</mystring>
        <subnode>
            <myotherstrin>my other string</myotherstring>
        </subnode>
    </language>
</languages>

Getting the resource strings using the LocalizationService:

CopyC#

 LocalizationService.Current.GetString("/mystring");
LocalizationService.Current.GetString("/subnode/myotherstring");

If you want the resource string for a specific language, you need to provide the language in the form of a CultureInfo to the GetStringByCulture method. If no culture is given, the current UI culture will be used. If a string is not found in the provided or implied language, the localization service will traverse up the culture chain and look for the resource in the neutral (if not the given language is neutral already) and then the invariant culture will be tried.

Fallback Values

If no resource matching the given key can be found GetString will return an empty string if the key starts with one of the key identifiers characters described above (‘/’ or ‘#’), otherwise the key itself will be returned. This behavior can be changed by modifying the FallbackBehavior property either through the API or in the web.config. If the 'DefaultCulture' is set the LocalizationService will try to get the resource from a default culture for any missing resources. The fallback culture is by default set to English ("en") but can be set explicitly using the FallbackCulture property in the API or configuration.
If the ‘MissingMessage’ flag is added an error message is returned for all missing resources which can be convenient in a development environment.
If the ‘Echo’ flag is removed the key itself is never returned.

You can also provide a fallback string using one of the GetString method overloads. If the fallback requires more than just a simple string you can use one of the TryGetString methods instead to get a clear response if the resource string was found or not.

Lists of Localized Strings

If you need all resource strings under a certain section the GetAllStrings method can be useful. When providing the base key, it will return all strings under that base key for the culture chain in question or all strings if the provided base key is empty. GetAllStrings returns a list of items that each contains the localized string, key and the specific culture where the string was specified. Note that the order of the list is not guaranteed to be the same as it was specified.

Available Languages

All languages available through the localization service are available through the AvailableLocalizations property. This property only indicates that localized strings exist in the returned cultures, not that the localization includes the whole system.

Localization Providers

The default localization service implementation is the ProviderBasedLocalizationService. This class uses a provider system to retrieve localizations. By default a single provider, in addition to the system ones, is configured to look for XML string resource files in a folder under the web root named ‘lang’. By adding files to this location you can add your own localizations or override system strings.