Retrieve localization service
Describes how to retrieve the currently configured and active EPiServer.Framework.Localization.LocalizationService, and use the EPiServer.Framework.Localization.LocalizationService.Current static property. It also describes how to add a constructor dependency to LocalizationService if your class is created by the service container.
The preferred way to retrieve localized string resources in Optimizely Content Management System (CMS) is through the LocalizationService
API. To retrieve the currently configured and active EPiServer.Framework.Localization.LocalizationService
, use the EPiServer.Framework.Localization.LocalizationService.Current
static property, or add a constructor dependency to LocalizationService
if the service container creates your class.
Retrieve a localized string
To retrieve a localized string, call the GetString
method with a key that represents the requested resource. The key normally starts with a forward slash (/) and can consist of several sections, each separated by a forward slash, like /somearea/somesection/myKey
.
Example:
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<languages>
<language name="English" id="en">
<mystring>my string</mystring>
<subnode>
<myotherstring>my other string</myotherstring>
</subnode>
</language>
</languages>
Getting the resource strings using the LocalizationService
:
LocalizationService.Current.GetString("/mystring");
LocalizationService.Current.GetString("/subnode/myotherstring");
If you want the resource string for a specific language, provide the language in the form of a CultureInfo
to the GetStringByCulture
method. If no culture is given, the current UI culture is used. If a string is not found in the provided or implied language, the localization service traverses up the culture chain and looks for the resource in the neutral (if the given language is not neutral). Then, the invariant culture is tried.
Fallback values
If no resource matching the given key is found, and the key starts with / GetString
 returns an empty string. Otherwise, the key itself is returned.
To change this behavior, modify the FallbackBehavior
property on LocalizationOptions
. If the DefaultCulture
is set, the LocalizationService
tries to get the resource from a default culture for missing resources. By default, the fallback culture is set to English (en), but you can set it explicitly using the FallbackCulture
property on LocalizationOptions
.
If you add the MissingMessage
flag, it returns an error message for missing resources, which can be convenient in a development environment. If the Echo
flag is removed, the key is never returned.
You also can provide a fallback string using one of the GetString
method overloads. If the fallback requires more than just a simple string, use one of the TryGetString
methods to get a clear response if the resource string was found.
Lists of localized strings
If you need all resource strings under a certain section, use the GetAllStrings
method because (when providing the base key) it returns strings under that base key for the culture chain in question or strings if the provided base key is empty. GetAllStrings
returns a list of items that contain 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
Languages available through the localization service are also available through the AvailableLocalizations
property, which 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, besides the system ones, is configured to look for XML string resource files in a folder under the web root named lang
. You can add your localizations or override system strings by adding files to this location. Translations that you add to an XML file in the lang
directory override system-defined resources.
Updated 9 months ago