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.
Do you find this information helpful? Please log in to provide feedback.