Configuring a built-in localization provider

This document describes how to configure the initialization of one of the EPiServer provided (built-in) localization providers. One of the features of the new localization system of EPiServer is that you can configure different localization providers.

You have the following options:

• To configure it in the episerver.framework section of your web.config. There you can also control the behavior of all providers registered on your site as well as disable the built-in providers.
• To register a provider in the localization service through code during initialization of the website.

One possible use for this could be that you want to place your language documents in another location than the default lang folder. Below are examples on how this can be achieved using the different options available. Remember that you might be required to modify access rights in the file system to enable access to the folder for the application pool in IIS.

Using the configuration option

When adding a provider that reads XML language documents through configuration, your only option is to specify a physical path to a physical folder. One limitation to be aware of when using the configuration option is that we do not support specifying a path to a virtual path provider (VPP). For details about the different attributes available on the “localization”-element, please refer to the SDK documentation for EPiServer.Framework.Configuration.LocalizationElement class.

The example configuration below demonstrates how this can be accomplished. Note that the addDefaultProviders attribute is set to false. This means that the lang folder will be ignored when the site is initialized and therefore no language documents located there will be included.

Example configuration:

<episerver.framework>
  ...
  <localization fallbackBehavior="FallbackCulture, MissingMessage, Echo" fallbackCulture="en">
    <providers>
      <add physicalPath="c:\temp\resourceFolder"
           name="customResources"
           type="EPiServer.Framework.Localization.XmlResources.FileXmlLocalizationProvider" />
    </providers>
  </localization>
  ...
</episerver.framework>

Using the code only option

Registration of any localization provider should be done during initialization of the site. The preferred way of doing this is to implement the IInitializableModule interface and handle the registration in the Initialize method.

The first example shows a possible way to create an IInitializableModule that registers a similar provider as in the configuration option above but this time through code.

Example code using physical path:

using System;
using System.Collections.Specialized;
using System.IO;
using System.Linq;
using EPiServer.Framework;
using EPiServer.Framework.Initialization;
using EPiServer.Framework.Localization;
using EPiServer.Framework.Localization.XmlResources;

namespace CodeSamples
{
    [InitializableModule]
    [ModuleDependency(typeof(FrameworkInitialization))]
    public class CustomLanguageProviderInitializationWithPhysicalPath : IInitializableModule
    {
        private const string ProviderName = "customResources";
        public void Initialize(InitializationEngine context)
        {
             //Casts the current LocalizationService to a ProviderBasedLocalizationService to get access to the current list of providers
            ProviderBasedLocalizationService localizationService = context.Locate.Advanced.GetInstance<LocalizationService>() as ProviderBasedLocalizationService;
            if (localizationService != null)
            {
                string langFolder = @"c:\temp\resourceFolder";
                if (Directory.Exists(langFolder))
                {
                    NameValueCollection configValues = new NameValueCollection();
                    //This config value tells the provider where to find XML language documents.
                    configValues.Add(FileXmlLocalizationProvider.PhysicalPathKey, langFolder);
                    FileXmlLocalizationProvider localizationProvider = new FileXmlLocalizationProvider();
                    //Instanciates the provider
                    localizationProvider.Initialize(ProviderName, configValues);
                    //Adds it at the end of the list of providers.
                    localizationService.Providers.Add(localizationProvider);
                }
            }
        }

        public void Uninitialize(InitializationEngine context)
        {
            //Casts the current LocalizationService to a ProviderBasedLocalizationService to get access to the current list of providers
            ProviderBasedLocalizationService localizationService = context.Locate.Advanced.GetInstance<LocalizationService>() as ProviderBasedLocalizationService;
            if (localizationService != null)
            {
                //Gets any provider that has the same name as the one initialized.
                LocalizationProvider localizationProvider = localizationService.Providers.FirstOrDefault(p => p.Name.Equals(ProviderName, StringComparison.Ordinal));
                if (localizationProvider != null)
                {
                    //If found, remove it.
                    localizationService.Providers.Remove(localizationProvider);
                }
            }
        }

        public void Preload(string[] parameters) { }
    }
}

EPiServer also provides two convenience classes named VirtualPathXmlLocalizationProviderInitializer and EmbeddedXmlLocalizationProviderInitializer located in the EPiServer.Framework.Localization.XmlResources namespace that can be used when registering localization providers. For details about the different classes please refer to the SDK documentation.

The second example demonstrates how you can use one of those convenience classes to read XML language documents from a specified virtual path. A prerequisite for this sample to work is that you configure a VPP under your <episerver> section in web.config. It is the virtual path registered there that is used as virtual path in the example. Also note that this module is dependent on the EPiServer CMS InitializationModule. This is required in order to be able to use a VPP since the VPPs are initialized during CMS start up.

Example code using virtual path:

using System;
using System.Linq;
using EPiServer.Framework;
using EPiServer.Framework.Initialization;
using EPiServer.Framework.Localization;
using EPiServer.Framework.Localization.XmlResources;
using EPiServer.Web.Hosting;

namespace CodeSamples
{
    [InitializableModule]
    //A dependency to EPiServer CMS initialization is needed to be able to use a VPP
    [ModuleDependency(typeof(EPiServer.Web.InitializationModule))] 
    public class CustomLanguageProviderInitializationWithVirtualPath : IInitializableModule
    {
        private const string ProviderName = "CustomProviderName";

        public void Initialize(InitializationEngine context)
        {
            //Casts the current LocalizationService to a ProviderBasedLocalizationService to get access to the current list of providers
            ProviderBasedLocalizationService localizationService = context.Locate.Advanced.GetInstance<LocalizationService>() as ProviderBasedLocalizationService;
            if (localizationService != null)
            {
                VirtualPathXmlLocalizationProviderInitializer localizationProviderInitializer = 
                    new VirtualPathXmlLocalizationProviderInitializer(GenericHostingEnvironment.VirtualPathProvider);
                //a VPP with the path below must be registered in the sites configuration.
                string virtualPath = "~/MyCustomLanguageVPP/";
                FileXmlLocalizationProvider localizationProvider = localizationProviderInitializer.GetInitializedProvider(virtualPath, ProviderName);
                //Inserts the provider first in the provider list so that it is prioritized over default providers.
                localizationService.Providers.Insert(0, localizationProvider);
            }
        }

        public void Uninitialize(InitializationEngine context)
        {
            //Casts the current LocalizationService to a ProviderBasedLocalizationService to get access to the current list of providers
            ProviderBasedLocalizationService localizationService = context.Locate.Advanced.GetInstance<LocalizationService>() as ProviderBasedLocalizationService;
            if (localizationService != null)
            {
                //Gets any provider that has the same name as the one initialized.
                LocalizationProvider localizationProvider = localizationService.Providers.FirstOrDefault(p => p.Name.Equals(ProviderName, StringComparison.Ordinal));
                if (localizationProvider != null)
                {
                    //If found, remove it.
                    localizationService.Providers.Remove(localizationProvider);
                }
            }
        }

        public void Preload(string[] parameters) { }
    }
}