Internationalization Options for WinUI 3

WinUI 3 完整支援多國語言功能。即便如此，目前最穩定的實作方式，仍是切換語言後重新啟動應用程式，才能確保顯示效果正常。雖然技術上可以做到不重新啟動就動態更新介面語言，但實作難度會大幅提升。我過去花了不少時間除錯，也曾無數次遇到切換語言後介面文字異常、程式崩潰等問題。經過反覆測試與修正，我歸納出一套穩固的 WinUI 3 多國語言執行流程，以下將逐步為各位說明。

首先在 App.xaml.cs 的程式後台加入語言初始化邏輯。倘若使用者未手動選擇專屬語言，應用程式會讀取作業系統預設語言；若該系統語言並未列入專案支援清單，就會預設使用英文。

protected override void OnLaunched(Microsoft.UI.Xaml.LaunchActivatedEventArgs args)
{
    const string LangSettingKey = "AppLanguageCode";
    // All supported language tags of project
    List<string> supportLangs = new() { "zh-CN", "en-US", "th-TH" };
    string finalLang = "en-US"; // Default language

    try
    {
        var localSetting = ApplicationData.Current.LocalSettings;

        // ① Use saved language if local configuration exists
        if (localSetting.Values.TryGetValue(LangSettingKey, out var savedVal))
        {
            finalLang = NormalizeLang(savedVal?.ToString() ?? "");
        }
        else
        {
            // ② No saved config: read system primary preferred language
            string sysLang = ApplicationLanguages.Languages.FirstOrDefault() ?? "";
            sysLang = NormalizeLang(sysLang);

            // ③ Use system language if supported, otherwise fall back to English
            finalLang = supportLangs.Contains(sysLang) ? sysLang : "en-US";
        }
    }
    catch
    {
        // Ignore exception when running unpackaged, ApplicationData unavailable
    }

    ApplicationLanguages.PrimaryLanguageOverride = finalLang;

    _window = new MainWindow();
    _window.Activate();
}

/// <summary>
/// Standardize culture code: map system returned zh-Hans-CN to zh-CN
/// </summary>
private static string NormalizeLang(string lang)
{
    if (string.IsNullOrEmpty(lang)) return lang;

    return lang switch
    {
        "zh-Hans-CN" => "zh-CN",
        "zh-Hant-TW" => "zh-TW", // For future Traditional Chinese support
        _ => lang
    };
}Code language: PHP (php)

這段程式仍有優化空間。為了讓程式碼更簡潔，建議不要在此處硬編碼支援語言清單，而是將其封裝至靜態工具類別內，日後只要調整語言相關設定，就能在專案各處共用同一組語言列表，範例如下：

    public class Languages
    {
        public static List<string> supportLangs = new() { "zh-CN", "en-US", "th-TH" };
    }Code language: PHP (php)

上述程式區段的核心作用，是在應用程式啟動時完成語言設定：優先載入使用者先前儲存的語言偏好，若無自訂設定則採用系統預設語言，最後再以英文作為最終備援選項。

建立獨立頁面用於語言切換

我們需要專屬介面讓使用者變更顯示語言，因此我另外建立一個獨立頁面，專門負責語言組態設定。

<?xml version="1.0" encoding="utf-8"?>
<Page
    x:Class="ThaiTong.Pages.LanguageSettingPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:ThaiTong.Pages"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    Background="{ThemeResource ApplicationPageBackgroundThemeBrush}"
    mc:Ignorable="d">
    <StackPanel Padding="20" Spacing="24">
        <TextBlock x:Uid="Txt_LangTip" FontSize="22"/>

        <ComboBox x:Name="cbLangSelect" Width="320" Height="40" CornerRadius="6">
            <ComboBoxItem Tag="zh-CN" Content="简体中文"/>
            <ComboBoxItem Tag="en-US" Content="English"/>
            <ComboBoxItem Tag="th-TH" Content="ภาษาไทย"/>
        </ComboBox>

        <StackPanel Orientation="Horizontal" Spacing="12">
            <Button x:Name="btnSave" x:Uid="Btn_Save" Content="Save" Click="BtnSave_Click" Width="120" Height="38" CornerRadius="5"/>
        </StackPanel>

        <TextBlock Foreground="Gray" Text="Note: After saving, page will refresh to apply language."/>
    </StackPanel>
</Page>
Code language: HTML, XML (xml)

對應的後端 C# 程式碼如下：

using Microsoft.UI.Xaml;
using Microsoft.UI.Xaml.Controls;
using Microsoft.UI.Xaml.Controls.Primitives;
using Microsoft.UI.Xaml.Data;
using Microsoft.UI.Xaml.Input;
using Microsoft.UI.Xaml.Media;
using Microsoft.UI.Xaml.Navigation;
using Microsoft.Windows.ApplicationModel.Resources;
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Runtime.InteropServices.WindowsRuntime;
using ThaiTong.Common;
using Windows.Foundation;
using Windows.Foundation.Collections;
using Windows.Globalization;
using Windows.Storage;

// To learn more about WinUI, the WinUI project structure,
// and more about our project templates, see: http://aka.ms/winui-project-info.

namespace ThaiTong.Pages
{
    /// <summary>
    /// An empty page that can be used on its own or navigated to within a Frame.
    /// </summary>
    public sealed partial class LanguageSettingPage : Page
    {

        private const string LangSettingKey = "AppLanguageCode";
        private string _currentLang;

        private readonly ResourceLoader _resLoader;

        public LanguageSettingPage()
        {
            InitializeComponent();
            _resLoader = new ResourceLoader();

            var setting = ApplicationData.Current.LocalSettings;
            if (setting.Values.TryGetValue(LangSettingKey, out var saveLang))
            {
                _currentLang = saveLang.ToString();
            }
            else
            {
                string sysLang = ApplicationLanguages.Languages.FirstOrDefault() ?? "";
                _currentLang = Languages.supportLangs.Contains(sysLang) ? sysLang : "en-US";
            }

            // Pre-select matched language in dropdown list
            foreach (var item in cbLangSelect.Items)
            {
                if (item is ComboBoxItem cbi && cbi.Tag.ToString() == _currentLang)
                {
                    cbLangSelect.SelectedItem = item;
                    break;
                }
            }
        }

        // Save selected language setting
        private async void BtnSave_Click(object sender, RoutedEventArgs e)
        {
            if (cbLangSelect.SelectedItem is not ComboBoxItem selectItem) return;
            string newLang = selectItem.Tag.ToString();
            if (_currentLang == newLang) return;

            ApplicationData.Current.LocalSettings.Values[LangSettingKey] = newLang;
            _currentLang = newLang;
            ApplicationLanguages.PrimaryLanguageOverride = newLang;

            // Load localized text from resw resource file
            ContentDialog tipDialog = new ContentDialog()
            {
                XamlRoot = this.XamlRoot,
                Title = _resLoader.GetString("Dlg_LangChange_Title"),
                Content = _resLoader.GetString("Dlg_LangChange_Content"),
                CloseButtonText = _resLoader.GetString("Dlg_LangChange_BtnOk")
            };
            await tipDialog.ShowAsync();
        }


    }
}
Code language: HTML, XML (xml)

每當使用者儲存新的語言設定後，我們會提示重新啟動應用程式，讓所有介面文字完整更新。

WinUI 3 的在地化實作分為兩大區塊：XAML 標記語法與 C# 後端程式的文字讀取作業。

若是 XAML 控制項，請使用 x:Uid 屬性，寫法範例如下：

<TextBlock x:Uid="Txt_LangTip" FontSize="22"/>Code language: HTML, XML (xml)

接著規劃在地化資源資料夾結構：在專案根目錄建立名為 Strings 的資料夾，再依照各個地區代碼建立子資料夾（例如 en-US 代表美式英文）。於每個語言資料夾內新增 Resources.resw 資源檔，檔案中以鍵值組的形式存放翻譯內容。

  <data name="Btn_Save.Content" xml:space="preserve">
      <value>儲存</value>
  </data>Code language: HTML, XML (xml)

name 欄位即為查詢索引鍵，後方附加的 .Content 則對應控制項的目標屬性。前文提到的 Txt_LangTip 欄位，設定方式如下：

<data name="Txt_LangTip.Text" xml:space="preserve"><value>選擇應用程式語言</value></data>Code language: HTML, XML (xml)

此處加上 .Text，是因為我們要綁定 TextBlock 控制項的 Text 屬性。

至於 C# 後端程式內的動態文字，需先初始化 ResourceLoader 執行個體：

 private readonly ResourceLoader _resLoader;

 public LanguageSettingPage()
 {
     InitializeComponent();
     _resLoader = new ResourceLoader();Code language: PHP (php)

初始化完成後，即可透過 GetString 方法在程式各處載入在地化文字：

Title = _resLoader.GetString("Dlg_LangChange_Title"),Code language: JavaScript (javascript)

Previous: 上架微軟應用市集時碰到的各類打包報錯問題

Next: WinUI 3 應用程式異常狀況處理

建立獨立頁面用於語言切換

發佈留言 取消回覆

發佈留言取消回覆