Windows App SDK Documentation

Sample: Multilingual App

This sample demonstrates how to create a multilingual application using the Windows App SDK. It covers essential concepts like resource management, string localization, and runtime language switching.

Note: This sample requires Visual Studio 2022 and the Windows App SDK extension.

Overview

A truly global application needs to support users in their native language. The Windows App SDK provides robust mechanisms to manage and display your application's content in multiple languages. This sample showcases how to leverage these features to build an inclusive user experience.

Key Concepts

  • Resource Files (.resw): Storing localized strings and other resources.
  • ResourceLoader: Accessing localized resources at runtime.
  • Language Priotization: How the system determines the best language to use.
  • Runtime Language Switching: Enabling users to change the app's language without restarting.

Setting Up the Sample

  1. Clone the repository containing this sample.
  2. Open the solution file in Visual Studio 2022.
  3. Ensure you have the latest Windows App SDK NuGet package installed.
  4. Build and run the application.

Project Structure

The project is organized to separate localized resources from the main application code:

  • Strings/en-US/Resources.resw: English resources.
  • Strings/fr-FR/Resources.resw: French resources.
  • Strings/es-ES/Resources.resw: Spanish resources.
  • MainPage.xaml: The main UI page.
  • MainPage.xaml.cs: Code-behind for MainPage, demonstrating resource loading.
  • App.xaml.cs: Application entry point, potentially handling global settings.

Implementing Localization

Localized strings are stored in .resw files. Each file corresponds to a specific language and culture. For example:

<!-- Strings/en-US/Resources.resw -->
<data name="WelcomeMessage" xml:space="preserve">
  <value>Welcome to the Multilingual App!</value>
</data>

<!-- Strings/fr-FR/Resources.resw -->
<data name="WelcomeMessage" xml:space="preserve">
  <value>Bienvenue dans l'application multilingue !</value>
</data>

In your XAML, you can bind to these resources directly. For instance, to display the WelcomeMessage:

<TextBlock Text="{x:Bind ResourceLoader.Get("WelcomeMessage"), Mode=OneWay}"/>

And in your C# code-behind, you would use ResourceLoader:

using Microsoft.Windows.ApplicationModel.Resources;

public sealed partial class MainPage : Page
{
    // Create an instance of ResourceLoader.
    // If no filename is specified, it defaults to "Resources.resw".
    private readonly ResourceLoader _resourceLoader = new ResourceLoader();

    public MainPage()
    {
        this.InitializeComponent();
        // Example of getting a string directly in code-behind
        string welcomeMessage = _resourceLoader.GetString("WelcomeMessage");
        // You could then use this string to set a TextBlock's Text property
        // or in other UI elements.
    }
}

Runtime Language Switching

To allow users to change the app's language on the fly, you can programmatically set the application's current culture. The Windows App SDK helps manage this, often by leveraging Windows.Globalization.ApplicationLanguages.PrimaryLanguageOverride.

A common approach is to provide a dropdown or menu for language selection. When a user selects a new language, you update the override and potentially restart the relevant UI elements or the entire application for changes to take full effect.

Tip: For a smoother experience, consider reloading only the affected UI elements instead of the entire app when changing language.

Here's a simplified example of how you might handle language selection:

// Assuming you have a ComboBox named LanguageComboBox
// and a method to update the language
private void LanguageComboBox_SelectionChanged(object sender, SelectionChangedEventArgs e)
{
    var selectedLanguage = e.AddedItems[0].ToString(); // e.g., "fr-FR", "en-US"

    // Set the runtime language override
    Windows.Globalization.ApplicationLanguages.PrimaryLanguageOverride = selectedLanguage;

    // To apply changes immediately, you might need to re-initialize parts of the UI
    // or restart the application. For simplicity, we might just inform the user.
    // In a real app, you'd likely have a more robust reload mechanism.
    var dialog = new ContentDialog
    {
        Title = "Language Changed",
        Content = $"The application language has been set to {selectedLanguage}. Please restart the app for all changes to take effect.",
        CloseButtonText = "Ok"
    };
    await dialog.ShowAsync();

    // Alternatively, you might navigate to the same page again to force a refresh
    // this.Frame.Navigate(typeof(MainPage));
}

Testing Your Localization

Thoroughly test your application with different language settings. Ensure that:

  • All UI elements display correctly.
  • Date, time, and number formats are localized.
  • User-generated content (if applicable) is handled appropriately.
  • The application looks good even with longer or shorter strings in different languages.

Further Reading