Globalization and Localization in .NET Core Web API: Building Multi-Language APIs

In today’s interconnected world, building applications that cater to a global audience is no longer optional; it’s essential. This means that applications must be able to handle different languages, cultures, and regions. Globalization and localization are key concepts that enable developers to create apps that transcend language and cultural barriers. In this post, we’ll explore how to implement globalization and localization in a .NET Core Web API, ensuring that your application is ready for a diverse user base.

What is Globalization?

Globalization refers to the process of designing and developing software that supports multiple cultures, languages, and regions. In a .NET Core Web API, this involves preparing your application to handle different formats for dates, numbers, currency, and more, based on the user’s culture settings.

What is Localization?

Localization is the process of adapting a globalized application to a specific culture and region. This includes translating the application’s text into different languages and adjusting cultural settings such as date formats, number formats, and currencies.

In essence, globalization is the design phase, and localization is the implementation for specific locales.

Why Globalization and Localization Matter in a Web API

Even though a Web API might not directly present a UI to the end-user, it still handles data that can be culture-specific. For example, when returning date or currency values to a client, you might need to format the response according to the user’s cultural preferences. Additionally, error messages, validation responses, or even specific data fields might need to be localized.

How Globalization and Localization Work in .NET Core

.NET Core provides built-in support for globalization and localization through several key classes and services. These include:

Resource Files (.resx): These files store localized text for various languages.

CultureInfo: This class provides information about specific cultures, including language, calendar system, and cultural conventions.

IStringLocalizer: Used to provide localized strings based on the current culture.

IObjectLocalizer: Localizes objects like validation messages or model states.

Setting Up Globalization and Localization in a .NET Core Web API

To enable globalization and localization in your .NET Core Web API, follow these steps:

1. Add Localization Services

In the Startup.cs file, you need to register the localization services in the ConfigureServices method:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();

    // Adding Localization Service
    services.AddLocalization(options => options.ResourcesPath = "Resources");

    // Configuring Supported Cultures
    var supportedCultures = new[] { "en-US", "fr-FR", "es-ES" };
    services.Configure<RequestLocalizationOptions>(options =>
    {
        options.DefaultRequestCulture = new RequestCulture("en-US");
        options.SupportedCultures = supportedCultures.Select(c => new CultureInfo(c)).ToList();
        options.SupportedUICultures = supportedCultures.Select(c => new CultureInfo(c)).ToList();
    });
}

2. Configure Request Localization Middleware

Next, in the Configure method, add the localization middleware to your application:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    app.UseHttpsRedirection();

    // Enable Request Localization Middleware
    var supportedCultures = new[] { "en-US", "fr-FR", "es-ES" };
    var localizationOptions = new RequestLocalizationOptions()
        .SetDefaultCulture("en-US")
        .AddSupportedCultures(supportedCultures)
        .AddSupportedUICultures(supportedCultures);

    app.UseRequestLocalization(localizationOptions);

    app.UseRouting();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

This middleware checks the Accept-Language header in incoming HTTP requests and sets the appropriate culture for the request.

3. Create Resource Files for Localization

In the Resources folder, create .resx resource files for each culture you want to support. For example:

• Messages.en-US.resx
• Messages.fr-FR.resx
• Messages.es-ES.resx

Each .resx file contains key-value pairs where the key is the identifier and the value is the localized string. Here’s an example of what the Messages.en-US.resx might look like:

<data name="HelloMessage" xml:space="preserve">
  <value>Hello, World!</value>
</data>

And for Messages.fr-FR.resx:

<data name="HelloMessage" xml:space="preserve">
  <value>Bonjour, le monde!</value>
</data>

4. Using IStringLocalizer in Controllers

Now that localization is set up, you can inject IStringLocalizer into your controllers and use it to localize strings:

[ApiController]
[Route("api/[controller]")]
public class GreetingController : ControllerBase
{
    private readonly IStringLocalizer<GreetingController> _localizer;

    public GreetingController(IStringLocalizer<GreetingController> localizer)
    {
        _localizer = localizer;
    }

    [HttpGet]
    public IActionResult GetGreeting()
    {
        var message = _localizer["HelloMessage"];
        return Ok(new { Message = message });
    }
}

When this API is called, it will return the greeting message based on the culture specified in the Accept-Language header of the request.

5. Testing Localization

You can test your API by sending requests with different Accept-Language headers. For example:

If the header is set to fr-FR, the response will be “Bonjour, le monde!”

If you send a request with the Accept-Language header set to en-US, the response will be “Hello, World!”

Globalization Considerations

When building a globalized application, be mindful of various other cultural differences. Here are a few considerations:

Right-to-Left (RTL) Languages: Some languages (e.g., Arabic, Hebrew) are written from right to left, and your API might need to handle these accordingly.

Date and Time Formats: Different cultures use different date and time formats (e.g., MM/dd/yyyy in the US vs dd/MM/yyyy in Europe).

Number and Currency Formats: Numbers are formatted differently in various regions (e.g., commas and periods for decimal points).

Conclusion

Globalizing and localizing a .NET Core Web API ensures that your application is ready to serve a diverse audience by adapting to their cultural and language preferences. By using the built-in support in .NET Core for localization and culture management, you can easily create APIs that deliver regionally accurate responses to clients across the globe.

This process may seem challenging at first, but with the right tools and techniques, it becomes manageable and highly beneficial. Start by setting up localization in your .NET Core Web API, and watch your application grow in usability and reach!