---
title: Configure a custom localization provider
slug: cms-13/docs/configure-a-custom-localization-provider
docTags: 
createdAt: 2026-07-30T20:22:07.220Z
---

Custom localization providers extend the default translation system in CMS. These providers serve translations from sources beyond the default XML files. Configure providers through `LocalizationOptions` or the `AddLocalizationProvider` and `AddEmbeddedLocalization` extension methods on `IServiceCollection`.

:::hint{type="info"}
**Note**
Too many providers increase string lookup time. For best performance, keep the number of localization providers to a minimum.
:::

## Register a localization provider

Register localization providers during the configuration phase of site initialization. Use `IServiceCollection` from the `Startup` class. Alternatively, create an initialization module that implements `IConfigurableModule`. Handle registration in `ConfigureContainer` by configuring `LocalizationOptions` or calling `AddLocalizationProvider` on `IServiceCollection`.

Register a localization provider from the `ConfigureServices` method in the `Startup` class:

```csharp
services.AddLocalizationProvider<FileXmlLocalizationProvider,NameValueCollection>(o => {
    o[FileXmlLocalizationProvider.PhysicalPathKey] = @ "c:\temp\resourceFolder";
  });
```

CMS also includes a provider for reading localization resources from embedded XML files: `EPiServer.Framework.Localization.XmlResources.EmbeddedXmlLocalizationProviderInitializer`.

Add a localization provider that reads embedded XML files from an assembly:

```csharp
using System;
using EPiServer.Framework;
using EPiServer.Framework.Initialization;
using EPiServer.Framework.Localization;

namespace CodeSamples {
  [InitializableModule]
  [ModuleDependency(typeof (FrameworkInitialization))]
  public class CustomLocalizationProviderInitialization: IConfigurableModule {
    public void ConfigureContainer(ServiceConfigurationContext context) {
      // ClassInMyAssembly can be any class in the Assembly where the resources are embedded
      context.Services.AddEmbeddedLocalization<ClassInMyAssembly>();
    }

    public void Initialize(InitializationEngine context) {}
    public void Uninitialize(InitializationEngine context) {}
  }
}
```

## ProviderBasedLocalizationService

`ProviderBasedLocalizationService` provides direct access to the localization service API for advanced provider management.

:::hint{type="info"}
**Note**
This API is deprecated. Use `LocalizationOptions` or extension methods instead.
:::