---
title: Localization service
slug: cms-13/docs/localization-service
createdAt: 2026-07-30T20:22:11.634Z
---

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

```csharp
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.