Replacing LanguageManager with LocalizationService

Introduction

With EPiServer 7 a new localization service was introduced in the EPiServer Framework, replacing the previously used localization models. The purpose with this consolidation is to make the localization procedure faster and easier.

The purpose of this change was the following:

• Keep the simplicity of the current CMS localization.
• Remove the requirement to put XML files in a folder named lang under the web root.
• Still support simple XML files in a web folder.
• Make it easier to create testable code that uses localization.
• Make the service replaceable and extendable.

The new solution consists of two main component types, the localization service and the localization providers. The localization service is the service you use when you want to retrieve a localized string resource. The service contains an abstract base class that serve as the main entry point, and a default implementation that uses providers in the background to retrieve localized resources from various locations in the system. Additional providers can be configured and added to the service if required, either in the web.config file or using the API.

Using the LocalizationService

Migrating from the CMS LanguageManager

Most of the functionality contained by the EPiServer.Core.LanguageManager class has now been migrated to the new EPiServer.Framework.Localization.LocalizationService class, and the LanguageManager has been marked as obsolete. You can still use the LanguageManager as it will redirect requests to the LocalizationService.

• The currently configured and active LocalizationService can be retrieved using the LocalizationService.Current static property or by requesting it from the service locator using the EPiServer.ServiceLocation.ServiceLocator.Current.GetInstance method.
• Where you previously used the Translate method on the LanguageManager you should now use GetString on LocalizationService. If you want the string on a specific language, you need to use GetStringByCulture and provide the language in the form of a CultureInfo object instead of a language id string as previously.
• Where you previously used the TranslateWithFallback method you can now use one of the overloads of the GetString method on the LocalizationService.
• The responsibilities of the TranslateForScript method have now been split into two classes. The normal GetString is used to retrieve the localized string, and the ScriptResourceHelper contains utility methods to prepare the string for usage in client scripts.
• The equivalent of TranslateRaw can be achieved using the GetString method providing null as the fallback string.
• If you have been using the convenience methods for translations on PageBase and UserControlBase, you can continue to do so, but only from inside Pages or UserControls as they have been marked protected. If you have used them outside of these classes, we recommend that you use the LocalizationService directly.
• Even though we have tried to map all features of the now obsolete LanguageManager to the LocalizationService, there are some parts that we could not or did not want to replicate in the new system as we no longer require localization to be based on XML files. It is no longer possible to traverse the languages and strings using the LanguageDocument property and the Directory property, GetLanguage method and the Reload method, are no longer in use.
• You might also notice that you will stop getting the “[Missing test ‘key’ for ‘en’]” message when a key is missing. If you want to restore this behavior you can do so by changing the FallbackBehavior property on the LocationService using either the API or in web.config. See the documentation on the FallbackBehavior for detailed information.

XML Language files

Though strictly not needed, the lang folder under the web directory will continue to work as before and any language XML files placed here will be read by a default localization provider that is added automatically. If you do not wish for this to happen, you can just remove the folder or set the value of the addDefaultProvider attribute of the resources element to false.

If you want to override the system localizations that are shipped with EPiServer products, you will notice that the language files are no longer installed in the lang folder. They are now instead embedded in the assemblies but just as before you can override individual string by placing your own language XML in the lang folder. Of course you can include your localizations through any other LocalizationProvider and they will take precedence over the system localizations as long as the provider is registered before the system ones.