DEV Community

Cover image for Data-driven Localization for .NET REST APIs
Jani Giannoudis
Jani Giannoudis

Posted on • Updated on • Originally published at

Data-driven Localization for .NET REST APIs

Because of the high level of automation in the cloud, software models and data are becoming increasingly dynamic. Let's take the example of an online fruit shop that sells its products in several countries. New products are entered by users in different languages.

When designing REST APIs with localized model data, the following considerations must be taken into account

  • What languages need to be supported?
  • What data needs to be localized (text, numbers, images, etc.)?
  • Which endpoints will be required to manage the localized objects?
  • Which endpoints will deliver the localized data?
  • How will the localized data be managed in relational database systems?

Scalable REST APIs separate information into translatable and readable data. Model data management endpoints contain all localization data. Within the online store endpoints, the data is delivered in a specific language. This saves resources and often provides ensures that not all information is distributed in all languages.

In addition to data localization, the following considerations are also important for REST APIs that rely on cultural settings to convert numeric, currency, and date data.

REST API product localization:
REST API Product Localization

  1. The REST client identifies available cultures.
  2. Products are captured and submitted in multiple languages.
  3. The REST client requests the products in a specific language as a query string, HTTP request header, or cookie.
  4. The REST API returns the localized product data.

NuGet Package

To use the localization features described here, the NuGet package RestApiLocalization.NET must be installed. The package includes the management of supported system cultures (Culture Provider) as well as the extension methods for localizing data.

Culture - The Localization Foundation

NET cultures have a unique name according to the rules of RFC4646/ISO639/ISO3166, which defines three levels for determining the culture:
.NET Culture Stack

The languages registered in the Windows system can be selected according to the following criteria:

  • Neutral culture such as en or de.
  • Specific culture such as en-US or de-DE.
  • Installed culture, which is installed on the REST API computer.
  • Custom custom user cultures.
  • Replacement culture for replaced default cultures.

Read mote about the .NET Culture Types.

Culture Provider

The system culture functions are specified in the ICultureProvider interface and provide the ability to limit the available cultures and control the working culture when processing API requests.

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();
Enter fullscreen mode Exit fullscreen mode

In the REST application, the localization service is set up at startup.

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

    // localization
        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",
        defaultCulture: "en-US");

    var app = builder.Build();
Enter fullscreen mode Exit fullscreen mode

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](

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:
Enter fullscreen mode Exit fullscreen mode

public class CulturesController : ControllerBase
private ICultureProvider CultureProvider { get; }
public CulturesController(ICultureProvider cultureProvider)
CultureProvider = cultureProvider;

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

[HttpGet("description", Name = "GetCultureDescriptions")]
public IEnumerable<CultureDescription> GetCultureDescriptions() =>
Enter fullscreen mode Exit fullscreen mode


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](

## Localization Extension Methods
The localizations library contains several extension methods for object localization.
Enter fullscreen mode Exit fullscreen mode

/// Test if localization property exists
bool IsLocalizable(this Type type, string propertyName);

/// Get the property localization values
Dictionary GetLocalizations(
this TObject obj, string propertyName);

/// Get an optional localized property value
object? GetOptionalLocalization(
this TObject obj, string propertyName, string? culture = null);

/// Get an optional localized property value
TValue? GetOptionalLocalization(
this TObject obj, string propertyName, string? culture = null);

/// Get the localized property value
TValue GetLocalization(
this TObject obj, string propertyName, string? culture = null);

/// Map all source object localized values to the target object base properties
TTarget MapLocalizations(
this TTarget target, TSource source, string? culture = null);

/// Map a source object localized value to the target object base property
void MapLocalization(
this TTarget target, TSource source, string propertyName,
string? culture = null)

### Product Localization
The following products are available for the Fruit Online Store.
Enter fullscreen mode Exit fullscreen mode

"name": "Nectarine",
"nameLocalizations": {
"en": "Nectarine",
"de": "Nektarine",
"zh-CN": "油桃"
"price": 0,
"priceLocalizations": {
"en": 3,
"de": 3.6,
"de-CH": 3.9,
"zh-CN": 2.8
"name": "GoldenMelon",
"nameLocalizations": {
"en": "Golden Melon",
"de": "Honigmelone",
"zh-CN": "金瓜"
"price": 0,
"priceLocalizations": {
"en": 4.5,
"de": 5.7,
"de-CH": 6.2,
"zh-CN": 4

The product is described by the following DTO:
Enter fullscreen mode Exit fullscreen mode

public class ProductDto
public string Name { get; set; } = string.Empty;
public decimal Price { get; set; }

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

public class ProductsController : ControllerBase

[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;
Enter fullscreen mode Exit fullscreen mode


To convert the product to the DTO, the object is first mapped with [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](

> 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]( UI framework.

The application lists the available languages of the REST API on the `Cultures` page.
![Localization App Cultures](

The `Products` page lists the products, including all translations, as well as the DTOs listed.
![Localization App Products](

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](

### Localization Column
When localized data is stored in an additional column, it is serialized as JSON.
![Localization ERD Minimal](

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

#### Entity Framework Code First Localization
Use the [NotMapped]( attribute with an additional string field that contains the serialized JSON.
Enter fullscreen mode Exit fullscreen mode

using System.Text.Json;
public class Product
public string Name { get; set; }
public Dictionary NameLocalizations { get; set; }
public string NameLocalizationsJson
get => JsonSerializer.
set => NameLocalizations = JsonSerializer.

public decimal Price { get; set; }
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);
Enter fullscreen mode Exit fullscreen mode


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

using System.Text.Json;
public class NamedDictionaryTypeHandler :
public override void SetValue(IDbDataParameter parameter,
Dictionary value)
parameter.Value = JsonSerializer.

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);
Enter fullscreen mode Exit fullscreen mode


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

Top comments (0)