Localization Generator

Microsoft.Extensions.Localization provides great abstractions, but you lose the strong typing and IDE tooling that .resx files originally gave you. This library fixes that — it source-generates a strongly-typed class for each .resx file, giving you compile-time safety, IntelliSense, and format-string methods with the correct number of parameters.

GitHub
Downloads

Frameworks

.NET

Features

• Strongly-typed localization classes generated from .resx files at compile time
• Properties for simple strings, methods for format strings ({0}, {1}, etc.)
• XML documentation comments generated from .resx comment fields — see default values in IntelliSense
• Full XAML and Razor binding support with IntelliSense
• Namespace follows folder structure automatically
• DI registration generated via AddStronglyTypedLocalizations()
• No empty stub classes: a .resx without a matching class gets one generated
• Generated classes follow the visibility of their class (public or internal)
• Reflection-free GeneratedLocalizers.All list, safe under trimming and NativeAOT

Setup

1. Install the NuGet packages:

   dotnet add package Microsoft.Extensions.Localization
   dotnet add package Shiny.Extensions.Localization.Generator

2. Register in your DI container:

   builder.Services.AddStronglyTypedLocalizations(); // also calls AddLocalization() internally

3. Create a .resx file. If it sits next to a class with the same name, that class is used; otherwise one is generated for you:

   MyViewModel.cs                ← optional
   MyViewModel.resx              ← default locale
   MyViewModel.fr-ca.resx        ← French-Canadian locale

4. Inject the generated {ClassName}Localized class:

   public class MyViewModel
   {
       public MyViewModel(MyViewModelLocalized localizer)
           => this.Localizer = localizer;
   
       public MyViewModelLocalized Localizer { get; }
   }

Note

IStringLocalizer<T> needs a T, so every .resx file is paired with a class of the same name in the same namespace. If you haven’t written one, the generator creates an empty partial class for it, and you still use it through DI by injecting the *Localized class. Add your own class at any time, partial or not, and the generated one goes away. Only the project being compiled is checked.

Caution

Turn off Visual Studio’s built-in resource generator for these files. In the .resx editor, set Access Modifier to No code generation; otherwise it adds <Generator>ResXFileCodeGenerator</Generator> to your project and writes a .Designer.cs class full of static properties. That class doesn’t break anything, since it’s simply used as the paired class, but it isn’t what you inject.

How It Works

Resource File

Create a .resx file with your localization keys:

<?xml version="1.0" encoding="utf-8"?>
<root>
  <data name="Welcome" xml:space="preserve">
    <value>Welcome to our app!</value>
    <comment>Greeting shown on the home page</comment>
  </data>
  <data name="UserGreeting" xml:space="preserve">
    <value>Hello {0}, welcome to {1}!</value>
    <comment>Personalized greeting with user name and app name</comment>
  </data>
  <data name="ItemCount" xml:space="preserve">
    <value>You have {0} items in your cart</value>
  </data>
</root>

Generated Class

The generator produces a class with properties for simple strings and methods for format strings:

public partial class MyViewModelLocalized
{
    readonly IStringLocalizer localizer;

    public MyViewModelLocalized(IStringLocalizer<MyViewModel> localizer)
        => this.localizer = localizer;

    /// <summary>
    /// Greeting shown on the home page
    /// Default: Welcome to our app!
    /// </summary>
    public string Welcome => this.localizer["Welcome"];

    /// <summary>
    /// Personalized greeting with user name and app name
    /// Default: Hello {0}, welcome to {1}!
    /// </summary>
    public string UserGreetingFormat(object parameter0, object parameter1)
        => string.Format(this.localizer["UserGreeting"], parameter0, parameter1);

    /// <summary>
    /// Default: You have {0} items in your cart
    /// </summary>
    public string ItemCountFormat(object parameter0)
        => string.Format(this.localizer["ItemCount"], parameter0);

    /// <summary>
    /// Access the underlying IStringLocalizer for edge cases
    /// </summary>
    public IStringLocalizer Localizer => this.localizer;
}

Key Naming Rules

• Dots (.), hyphens (-), and spaces in resource keys are converted to underscores (_)
• Format parameters ({0}, {1}, etc.) are detected automatically and generate a method
• Method names get a Format suffix unless the key already ends with Format

Directory Structure and Namespaces

The folder structure determines the generated namespace:

MyApp/
├── MyViewModel.cs
├── MyViewModel.resx                  → MyApp.MyViewModelLocalized
├── MyViewModel.fr-ca.resx
├── Errors.Validation.resx            → MyApp.Errors.ValidationLocalized
├── Errors.Validation.fr-ca.resx
├── Features/
│   ├── Settings/
│   │   ├── SettingsPage.cs
│   │   ├── SettingsPage.resx         → MyApp.Features.Settings.SettingsPageLocalized
│   │   └── SettingsPage.fr-ca.resx

Dots in a file name become namespace segments: Errors.Validation.resx pairs with the class Validation in MyApp.Errors. That’s the name MSBuild gives the embedded resource, so IStringLocalizer<T> finds it.

Note

Only default .resx files get a generated class. A file whose last segment is a culture (.fr-ca.resx, .de.resx) is a translation and is used by the localization framework at runtime. The generator takes that decision from MSBuild, so it always agrees with the satellite assemblies your build produces. A culture file with no default file next to it (Orphan.de.resx without Orphan.resx) raises warning SHINY0001.