Localization service

The LocalizationService API is the preferred way to retrieve localized string resources in Optimizely CMS. Access the active instance through EPiServer.Framework.Localization.LocalizationService.Current. Alternatively, add a constructor dependency to LocalizationService when the service container creates your class.

Retrieve a localized string

The GetString method retrieves a single localized string by key, with automatic fallback through the culture chain.

Call the GetString method with a key that represents the requested resource. The key starts with a forward slash (/) and consists of sections separated by forward slashes, such as /somearea/somesection/myKey.

The following XML defines two resource strings:

<?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>

Retrieve the resource strings through LocalizationService:

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

Pass a CultureInfo to GetStringByCulture to retrieve a resource string for a specific language. When no culture is provided, the service uses the current UI culture. When a string is not found in the specified language, the service traverses up the culture chain. It checks the neutral culture first (if the specified language is not neutral), then tries the invariant culture.

Fallback values

Fallback values control what LocalizationService returns when a requested resource key is missing.

If no resource matches the given key and the key starts with /, GetString returns an empty string. Otherwise, the key itself is returned.

Control this behavior through the FallbackBehavior property on LocalizationOptions. When FallbackCulture is set, LocalizationService retrieves the resource from a default culture for missing resources. The fallback culture defaults to English (en). Set it through the FallbackCulture property on LocalizationOptions.

Add the MissingMessage flag to return an error message for missing resources during development. Remove the Echo flag to prevent the key from being returned.

Provide a fallback string through one of the GetString method overloads. When the fallback requires more than a string, use TryGetString to get a clear response about whether the resource was found.

Lists of localized strings

Batch retrieval of localized strings simplifies scenarios where multiple translations are needed at once.

Use the GetAllStrings method to retrieve all resource strings under a section. Pass the base key to return all strings under that key for the culture chain. Pass an empty base key to return all strings. GetAllStrings returns items that contain the localized string, key, and the specific culture where the string was specified. The returned list order does not necessarily match the source order.

Available languages

Verify which languages have loaded translations at runtime through the AvailableLocalizations property.

The AvailableLocalizations property indicates that localized strings exist in the returned cultures. It does not guarantee that translations cover the entire system.

Localization providers

The default localization service implementation is ProviderBasedLocalizationService. This class uses a provider system to retrieve localizations. The default configuration includes a single provider (in addition to system providers) that reads XML string resource files from a lang folder under the web root. Add localizations or override system strings by placing files in that folder. Translations in the lang directory override system-defined resources.