Data-driven Localization for .NET REST APIs

public interface ICultureProvider
{
    /// <summary>Get the default culture name</summary>
    string DefaultCultureName { get; }

    /// <summary>Get the current culture</summary>
    CultureInfo CurrentCulture { get; }

   /// <summary>Get the current UI culture</summary>
    CultureInfo CurrentUICulture { get; }

    /// <summary>Set the current application und UI culture</summary>
    void SetCurrentCulture(string cultureName);

    /// <summary>Get the culture by name</summary>
    CultureInfo? GetCulture(string cultureName);

    /// <summary>Get the supported cultures</summary>
    IList<CultureInfo> GetSupportedCultures();

    /// <summary>Get the supported culture descriptions</summary>
    IList<CultureDescription> GetSupportedCultureDescriptions();
}

public static void Main(string[] args)
{
    var builder = WebApplication.CreateBuilder(args);
    ...

    // localization
    builder.Services.AddLocalization(
        cultureScope: new(
            neutral: true,
            specific: true,
            installed: true,
            custom: false,
            replacement: false),
        supportedCultures: new[]
            {
                "en", "en-US", "en-GB",
                "de", "de-DE", "de-AT", "de-CH",
                "zh",
            },
        defaultCulture: "en-US");

    var app = builder.Build();
    ...
}

The `CultureScope` basically defines which system cultures are available. These can be further restricted with the `SupportedCultures`. Restricting the available cultures makes sense if it is known in advance into which languages the data can be localized. For generic REST APIs, where it is not known into which languages the data will be translated, this restriction is not necessary.

> The Culture Provider contains all the information required for ASP.NET Core localization [Request Localization](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/localization/select-language-culture).

The Culture Provider is registered as a singleton in the DI and can be used in the REST API controller to serve information from the Culture API:

[HttpGet(Name = "GetCultures")]
public IEnumerable<string> GetCultures() =>
    CultureProvider.GetSupportedCultures()
        .Select(x => x.Name).ToList();

[HttpGet("description", Name = "GetCultureDescriptions")]
public IEnumerable<CultureDescription> GetCultureDescriptions() =>
    CultureProvider.GetSupportedCultureDescriptions();

This example returns the list of culture names with `GetCultures` and the list of readable descriptions in English and native with the `GetCultureDescriptions` endpoint.

## Data Localization
The localization is based on the convention of a C# class property. The localization is stored as a string/value dictionary in a property named `<PropertyName>Localizations`. The sample product localizes the `Name` property with `NameLocalizations` and the `Price` property with `PriceLocalizations`.
![Object Localization](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/smlheal8e6sjvy7f6obp.png)

## Localization Extension Methods
The localizations library contains several extension methods for object localization.

### Product Localization
The following products are available for the Fruit Online Store.

The product is described by the following DTO:

In the product controller, the `GetProducts` endpoint returns the localizable products and the `GetProductsDto` method returns the DTOs for the store.

[HttpGet(Name = "GetProducts")]
public IEnumerable<Product> GetProducts()
{
    var products = new ProductService().GetProducts();
    return products;
}

[HttpGet("dto", Name = "GetProductsDto")]
public IEnumerable<ProductDto> GetProductsDto(
    [FromQuery] string? culture = null)
{
    // map products to dto objects
    var config = new MapperConfiguration(
        cfg => cfg.CreateMap<Product, ProductDto>());
    var mapper = new Mapper(config);

    var products = new ProductService().GetProducts();
    var dataProducts = products.ConvertAll(
        // map object
        x => mapper.Map<ProductDto>(x)
            // map localizations
            .MapLocalizations(x, culture)).ToList();
    return dataProducts;
}

To convert the product to the DTO, the object is first mapped with [AutoMapper](https://github.com/AutoMapper/AutoMapper) `mapper.Map<ProductDto>` and then `MapLocalizations()` is used to apply the localization to the DTO.

The REST API of this example can be started with the Visual Studio solution `ObjectLocalization.WebApi.sln`.
![Localization REST API](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/rzxjtdw0ypfs359p23ui.png)

> To keep the example simple, the products are stored in local JSON files.

## Blazor Client Application
To illustrate localization in clients, there is a Blazor application that uses the open source [MudBlazor](https://github.com/MudBlazor/MudBlazor) UI framework.

The application lists the available languages of the REST API on the `Cultures` page.
![Localization App Cultures](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/x50viuvs7ukllj82cntq.png)

The `Products` page lists the products, including all translations, as well as the DTOs listed.
![Localization App Products](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/14jw8bhbm5emd0po90uo.png)

The DTO product adapts accordingly as the `Culture` changes.

## Relational Persistence of Localization Data
Localized data can be implemented in relational databases in several ways:
- `Table`: The localizations are maintained in a separate table.
- `Column`: The localizations are managed as JSON in an additional column.

Which variant makes sense depends on several factors
- Are the localizations indexable (performance) -> Table
- Is the localization addressable (model references) -> Table
- Is the localization searchable (REST requests) -> Table (simple) or Column (complex)
- Should the localized object remain compact (audits) -> Column
- Should the data model be kept as simple as possible -> Column

### Localization Tables
This variant creates a localization table for each localizable field.
![Localization ERD](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/pvd8z1o2aa2ci8jg1in3.png)

### Localization Column
When localized data is stored in an additional column, it is serialized as JSON.
![Localization ERD Minimal](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/urz074i16mv9x1epmxxj.png)

Most ORM tools provide the ability to serialize dictionaries in a field.

#### Entity Framework Code First Localization
Use the [NotMapped](https://learn.microsoft.com/en-us/ef/core/modeling/entity-properties) attribute with an additional string field that contains the serialized JSON.

public decimal Price { get; set; }
[NotMapped]
public Dictionary<string, decimal> PriceLocalizations  { get; set; }
public decimal PriceLocalizationsJson
{
    get => JsonSerializer.
           Serialize<Dictionary<string, decimal>>(PriceLocalizations);
    set => PriceLocalizations = JsonSerializer.
           Deserialize<Dictionary<string, decimal>>(value);
}

#### Dapper Localization
With Dapper, you can convert the data with a custom type handler.

public override Dictionary<string, TValue> Parse(object value)
{
    var json = value as string;
    if (string.IsNullOrWhiteSpace(json))
    {
        return null;
    }
    return JsonSerializer.
           Deserialize<Dictionary<string, TValue>>(json);
}

The type handler must be registered at program start with `SqlMapper.AddTypeHandler(new NamedDictionaryTypeHandler<object>());`.