ASP.NET Core localization and translation with examples

Key terms in ASP.NET Core localization

Before diving into implementation, it helps to understand a few core terms used in ASP.NET Core localization:

• Localization (L10N)
  Adapting an application for a specific language and region, including translations and culture-specific formatting.

• Globalization (G11N)
  Designing an application so it can support multiple languages and regions from the start.

• Internationalization (I18N)
  The overall process that includes both globalization and localization.

• Culture
  A combination of a language and an optional region (for example, en-US or fr-FR) that determines how content is displayed.

• RESX file
  A .NET XML-based resource file used to store localized strings as key-value pairs for different languages.

Prerequisites

Before you begin, make sure you have:

• .NET 8.0 (LTS) or later
• Visual Studio 2022 or later
• Basic understanding of C# and ASP.NET

ASP.NET Core localization: Preparing project

First, let’s set up a basic ASP.NET Core project that we'll later turn into an internationalized web application.

Open Visual Studio and create a new project with the following configuration:

• Template: ASP.NET Core Empty (minimal hosting model)
• Name: ASPLokaliseDemo
• Target Framework: .NET 8.0 (LTS)
• Note: Tick the "Place solution and project in the same directory" option.

Setting up services and building the application

Next, open the Program.cs file and add the following code::

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddControllersWithViews();
builder.Services.AddRazorPages();

var app = builder.Build();

Key points:

• WebApplication.CreateBuilder(args) creates the builder used to configure services and the app.

• AddControllersWithViews() registers MVC services.

• AddRazorPages() registers Razor Pages services.

• builder.Build() creates the application instance.

Configuring the HTTP request pipeline

Now configure the HTTP request pipeline in the same file:

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

Key points:

• UseDeveloperExceptionPage() shows detailed error information during development.

• UseHttpsRedirection() redirects HTTP requests to HTTPS.

• UseStaticFiles() enables static files such as CSS, JavaScript, and images.

Adding routing and endpoint mapping

Finally, add routing and endpoint mapping in the same file:

app.UseRouting();

app.UseAuthorization();

app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

app.MapRazorPages();

app.Run();

Key points:

• UseRouting() matches incoming requests to endpoints.

• UseAuthorization() applies authorization rules.

• MapControllerRoute() sets the default MVC route.

• MapRazorPages() maps Razor Pages endpoints.

• app.Run() starts the application.

Creating the Home Controller

To set up a basic controller:

1. Create a Controllers directory in the project root (if it doesn’t exist).
2. Add the HomeController:
   • In Visual Studio, right-click the Controllers directory.
   • Select Add > New Item...
   • Choose MVC Controller - Empty and name it HomeController.cs.
3. Update HomeController.cs:
   • Visual Studio will generate a basic HomeController class with an Index method. This method will be the default action when users navigate to the root URL.

Here’s what the HomeController.cs should look like:

using Microsoft.AspNetCore.Mvc;

namespace ASPLokaliseDemo.Controllers
{
    public class HomeController : Controller
    {
        public IActionResult Index()
        {
            return View();
        }
    }
}

The HomeController matches the default route configured earlier in Program.cs. When a user opens the root URL (for example, https://localhost:5001/), the request is routed to the Index action.

Creating the Razor view for the Index action

With your HomeController set up, it’s time to create the view for the Index action:

1. Create a Views directory in the project root (if it doesn’t exist).
2. Add a Home folder inside the Views directory.
3. Add the Index.cshtml file:
   • Right-click the Home folder.
   • Select Add > New Item...
   • Choose Razor View and name it Index.cshtml.
4. Fill in Index.cshtml with the following code:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8" />
    <title>ASP.NET localization demo | Lokalise</title>
</head>
<body>
    <p>Ready to get localized!</p>
</body>
</html>

Razor views generate HTML on the server. The Index.cshtml file corresponds to the Index action in HomeController. By convention, ASP.NET Core looks for this view in the Views/Home/ folder when the action is executed.

At this point, the project is ready for adding ASP.NET Core localization services and middleware.

Resource (RESX) files for ASP.NET localization

Before adding localization logic, you need to define language resources in your ASP.NET Core project. Localized strings are stored in .resx files and are resolved at runtime based on the current culture.

How ASP.NET Core organizes resource files

ASP.NET Core uses .resx files to store localized strings for controllers, services, and views. Each file contains key-value pairs for a specific language.

These files are mapped to classes or views using naming conventions.

Resource file naming conventions

Resource file names depend on the class namespace:

• Matching namespace: If the namespace matches the project assembly, name the file after the class.
  • Example: For ASPNETCoreL10n.HomeController, name the resource file HomeController.resx.
• Non-matching namespace: If the namespace differs, use the full type name.
  • Example: For ASPNETCoreUtils.StringFormatter, name the resource file ASPNETCoreUtils.StringFormatter.resx.

Resource files can be placed:

• next to the class/view they localize

• or inside a shared Resources folder

Supporting multiple locales

To support multiple languages, create separate .resx files per culture:

• Neutral culture: <resource-file-name>.<language>.resx
  • Example: HomeController.en.resx (for English)
• Specific culture: <resource-file-name>.<language>-<region>.resx
  • Example: HomeController.fr-FR.resx (for French-France)

Culture codes follow ISO standards, such as:

• en-US (English, United States)

• fr-FR (French, France)

Creating resource files for localization

To add English and French localization for HomeController:

1. Create the Resources directory:
   • In the root of your project, create a new folder named Resources.
2. Add resource files:
   • Inside the Resources folder, add two resource files named Controllers.HomeController.en-US.resx and Controllers.HomeController.fr-FR.resx
3. Adding keys to resource files:
   • Open one of the resource files, like Controllers.HomeController.en-US.resx, in Visual Studio.
   • Click on the “plus” icon (or “Add Resource” if you see that option).
   • A dialog will appear, prompting you to enter the details of the new resource.
     • Name: Enter welcome . This is the key that you’ll use in your code to reference this resource.
     • Value: Enter Welcome!. This is the English text that will be displayed to users when the welcome key is accessed.
   • Click “Add” or “OK” to save the resource.
4. Handling multiple locales:
   • After adding the key to one resource file, repeat the process for the other file (Controllers.HomeController.fr-FR.resx).
   • In the French resource file, set the Value for the welcome key to Bienvenue!.
5. Fallback resource file:
   • Once you add resources, you might notice that a default Controllers.HomeController.resx file is created in the same directory. This file acts as a fallback for when a specific localization isn’t available. Open it, and you should see the welcome key listed. However, this file typically remains empty or contains neutral/default values.
6. Review the resource table:
   • In each resource file, you’ll see a table where your welcome key is listed along with its corresponding values. For the en-US file, you’ll have Welcome!, and for the fr-FR file, you’ll have Bienvenue!. These values will be used based on the user’s locale.

By following these steps, you've successfully set up localized resources for your HomeController in English and French!

Implementing ASP.NET core localization with IStringLocalizer

In ASP.NET Core, IStringLocalizer is the recommended way to access localized strings. It integrates with the framework and lets you retrieve translations without hardcoding them.

Setting up localization in the application

First, configure localization in your Program.cs file:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllersWithViews();
builder.Services.AddRazorPages();

// Add localization services
builder.Services.AddLocalization(options =>
{
    options.ResourcesPath = "Resources";
});

var app = builder.Build();

// Enable request localization middleware
app.UseRequestLocalization();

app.Run();

This setup does two things:

• AddLocalization() registers localization services and tells ASP.NET Core where to find .resx files.

• UseRequestLocalization() enables culture detection for each request.

Note: This is a minimal setup. In real applications, you’ll usually configure supported cultures and default culture explicitly.

Localizing strings in the HomeController

Now, let's modify the HomeController to use IStringLocalizer for fetching localized strings. Here’s how to do it:

1. Open the HomeController.cs file.
2. Update the class to inject IStringLocalizer and use it to retrieve the localized strings:

using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Localization;

namespace ASPLokaliseDemo.Controllers
{
    public class HomeController(IStringLocalizer<HomeController> localizer) : Controller
    {
        public IActionResult Index()
        {
            ViewData["greeting"] = localizer["welcome"];
            return View();
        }
    }
}

How it works:

• IStringLocalizer<HomeController> is injected into the controller.

• It automatically looks for resource files that match the controller name.

• localizer["welcome"] retrieves the value for the welcome key based on the current culture.

Displaying the localized message in the view

Finally, let’s update the view to display the localized message. Open the Views/Home/Index.cshtml file and modify it as follows:

<body>
    <h1>@ViewData["greeting"]</h1>
</body>

When the page loads, ASP.NET Core resolves the correct translation and displays it based on the user’s culture.

Switching locales in ASP.NET Core

By default, an ASP.NET Core app may always use the same culture (for example, en-US). This happens because supported cultures are not configured yet.

To properly switch between languages, you need to define which cultures your application supports and enable culture detection.

Defining supported cultures

ASP.NET Core uses two properties to control localization:

• SupportedCultures
  Affects culture-specific formatting (dates, numbers, etc.)

• SupportedUICultures
  Controls UI translations (text from .resx files)

If these are not configured, the app won’t know which cultures it can handle.

Configuring request localization middleware

Now update Program.cs to enable culture switching:

using System.Globalization;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllersWithViews();
builder.Services.AddRazorPages();

builder.Services.AddLocalization(options =>
{
    options.ResourcesPath = "Resources";
});

var app = builder.Build();

// Define supported cultures
var supportedCultures = new[]
{
    new CultureInfo("en-US"),
    new CultureInfo("fr-FR")
};

// Configure localization options
var localizationOptions = new RequestLocalizationOptions
{
    DefaultRequestCulture = new RequestCulture("en-US"),
    SupportedCultures = supportedCultures,
    SupportedUICultures = supportedCultures
};

// Enable localization middleware
app.UseRequestLocalization(localizationOptions);

app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();

app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

app.MapRazorPages();

app.Run();

How it works

• SupportedCultures defines which cultures affect formatting.

• SupportedUICultures defines which cultures are used for UI translations.

• DefaultRequestCulture sets the fallback culture (en-US in this example).

• UseRequestLocalization() applies the correct culture to each request.

By default, ASP.NET Core will detect the user’s culture from the browser’s Accept-Language header, unless you override it with other providers (such as query string or cookies).

Enhancing locale switching with RequestCultureProviders

To improve how your app detects and switches cultures, you can configure multiple RequestCultureProviders. Each provider checks a different source (query string, cookies, or browser settings).

Update your localization setup:

var supportedCultures = new[]
{
    new CultureInfo("en-US"),
    new CultureInfo("fr-FR")
};

var localizationOptions = new RequestLocalizationOptions
{
    DefaultRequestCulture = new RequestCulture("en-US"),
    SupportedCultures = supportedCultures,
    SupportedUICultures = supportedCultures,
    RequestCultureProviders =
    [
        new QueryStringRequestCultureProvider(),
        new CookieRequestCultureProvider(),
        new AcceptLanguageHeaderRequestCultureProvider()
    ]
};

app.UseRequestLocalization(localizationOptions);

You can now test culture switching directly in the URL: https://localhost:5001/?culture=fr-FR.

How RequestCultureProviders work

Each provider tries to determine the culture for the current request:

• QueryStringRequestCultureProvider
  Reads culture from the query string.
  Example: ?culture=fr-FR&ui-culture=fr-FR

• CookieRequestCultureProvider
  Reads culture from a cookie.
  Useful for persisting user preferences across sessions.

• AcceptLanguageHeaderRequestCultureProvider
  Uses the browser’s Accept-Language header.
  This reflects the user’s browser language settings.

Provider order matters

Providers are evaluated in order. ASP.NET Core uses the first one that returns a valid culture.

A typical order:

1. Query string — explicit user choice

2. Cookie — stored preference

3. Browser header — fallback

Date and time localization

After setting up text localization, you also need to format dates and times based on the user’s culture. Different regions use different formats, and ASP.NET Core automatically handles this using the current culture.

Displaying a localized date on the home page

To demonstrate, let's add the current date to the home page and ensure it's localized based on the selected culture.

In your HomeController, pass the current date and time to the view. ASP.NET Core will automatically format this date according to the current culture.

Here's how to modify the Index action:

using System.Globalization;

public IActionResult Index()
{
    ViewData["greeting"] = localizer["welcome"];
    ViewData["currentDate"] = DateTime.Now.ToString("D", CultureInfo.CurrentCulture);
    return View();
}

What’s happening:

• "D" formats the date using the long date pattern (for example, Monday, August 16, 2024).

• CultureInfo.CurrentCulture ensures the format matches the user’s selected culture.

• The culture is set earlier by the localization middleware and providers.

Now, update the Index.cshtml view to display the localized date alongside the greeting message:

<body>
    <h1>@ViewData["greeting"]</h1>
    <p>@ViewData["currentDate"]</p>
</body>

The date will now be displayed using the correct format for the active culture.

Custom date format example

If you prefer a different format, such as "Monday, August 16, 2024", you can specify it directly:

ViewData["currentDate"] =
    DateTime.Now.ToString("dddd, MMMM dd yyyy", CultureInfo.CurrentCulture);

Handling time zones

If your application serves users in different time zones, you may want to convert the date and time to the user's local time zone before displaying it:

var userTimeZone = TimeZoneInfo.FindSystemTimeZoneById("Central European Standard Time");

var localTime = TimeZoneInfo.ConvertTime(DateTime.Now, userTimeZone);

ViewData["currentDate"] =
    localTime.ToString("F", CultureInfo.CurrentCulture);

"F" produces a full date and time string, including both date and time.