Localizing using ResX

Localization is a crucial step in delivering a great user experience for a global audience. In .NET, the ResXResourceReader and ResXResourceWriter classes are used to read and write resources in an XML-based format (.resx). This guide will walk you through the process of localizing an Avalonia application using ResX files.

Localization - Sample on GitHub

Add ResX Files to the Project

Before localizing, you need to include ResX files for each language you want to support. For this guide, we'll consider three ResX files, one for each of the following cultures:

• Resources.fil-PH.resx (Filipino)
• Resources.ja-JP.resx (Japanese)
• Resources.resx (Default language, usually English)

Each ResX file will contain translated text that corresponds to the keys used in the application.

In this example, we added new files to a new folder called Lang. Since .NET generator creates namespaces depending on folder structure, it might be different for you.

warning

If you add the files into the Assets folder make sure to switch Build Action to Embedded resource, otherwise the code generation may fail.

Set the Culture

To use a specific language in the application, you need to set the current culture. This can be done in the App.axaml.cs file. The following example sets the culture to Filipino (fil-PH):

App.xaml.cs

public partial class App : Application
{
    public override void Initialize()
    {
        AvaloniaXamlLoader.Load(this);
    }

    public override void OnFrameworkInitializationCompleted()
    {
        Lang.Resources.Culture = new CultureInfo("fil-PH");
        if (ApplicationLifetime is IClassicDesktopStyleApplicationLifetime desktop)
        {
            desktop.MainWindow = new MainWindow
            {
                DataContext = new MainWindowViewModel(),
            };
        }

        base.OnFrameworkInitializationCompleted();
    }
}

Replace "fil-PH" with the appropriate culture code as required.

Use Localized Text in the View

To use the localized text in a view, you can refer to the resources statically in XAML:

<TextBlock Text="{x:Static lang:Resources.GreetingText}"/>

In the above example, GreetingText is the key that corresponds to a string in the ResX file. The {x:Static} markup extension is used to reference a static property that's been defined in a .NET class, which, in this case, is the resources file (lang:Resources.GreetingText).

That's it! You've now successfully localized your Avalonia application using ResX. By setting the culture to a different locale, you can display the user interface in the selected language, thereby creating an application that supports multiple languages and caters to a global audience.

warning

For the localized properties to be available from XAML, the code generated from the resource file must be publicly accessible. By default, the Resources class is generated by ResXFileCodeGenerator and is internal. Make sure to change the custom tool to PublicResXFileCodeGenerator. The relevant part of the csproj should look like this:

<ItemGroup>
  <EmbeddedResource Update="Resources.resx">
    <Generator>PublicResXFileCodeGenerator</Generator>
    <LastGenOutput>Resources.Designer.cs</LastGenOutput>
  </EmbeddedResource>
</ItemGroup>

<ItemGroup>
  <Compile Update="Resources.Designer.cs">
    <DesignTime>True</DesignTime>
    <AutoGen>True</AutoGen>
    <DependentUpon>Resources.resx</DependentUpon>
  </Compile>
</ItemGroup>

NB: also note that only the default resource file (Resources.resx) should generate code.