針對 ASP.NET Core 當地語系化進行疑難排解

  • 發行項

作者為 Hisham Bin Ateya

本文提供如何診斷 ASP.NET Core 應用程式當地語系化問題的指示。

當地語系化組態問題

當地語系化中介軟體順序
應用程式可能會因為當地語系化中介軟體並未如預期般排序而無法當地語系化。

若要解決此問題，請確定當地語系化中介軟體的註冊順序早於 MVC 中介軟體。 否則不會套用當地語系化中介軟體。

public void ConfigureServices(IServiceCollection services)
{
    services.AddLocalization(options => options.ResourcesPath = "Resources");

    services.AddMvc();
}

找不到當地語系化資源路徑

RequestCultureProvider 中支援的文化特性 (Culture) 與註冊的不相符

資源檔命名問題

ASP.NET Core 已為當地語系化資源檔案命名預先定義了規則和方針，如 ASP.NET Core 的全球化和當地語系化中所述。

缺少資源

找不到資源的常見原因包括：

  • 資源名稱在 .NET XML 資源檔 (.resx) 或當地語系化工具要求中拼錯。
  • 某些語言的資源檔中缺少這項資源，但其他語言皆有。
  • 如果您仍持續遇到問題，請查看當地語系化記錄訊息 (記錄在 Debug 記錄層級)，以獲取所缺少資源的詳細資料。

提示

使用 CookieRequestCultureProvider 時，請確認當地語系化 cookie 值中的文化特性 (Culture) 未使用單引號。 例如，c='en-UK'|uic='en-US' 是無效的 cookie 值，而 c=en-UK|uic=en-US 則是有效的。

資源與類別庫問題

ASP.NET Core 根據預設會提供讓類別庫能透過 ResourceLocationAttribute 找到資源檔的方法。

類別庫的常見問題包括：

CustomRequestCultureProvider 無法如預期般運作

RequestLocalizationOptions 類別有三個預設提供者：

CustomRequestCultureProvider 可讓您自訂當地語系化文化特性 (Culture) 的提供方式。 當預設提供者不符合您的需求時，會使用 CustomRequestCultureProvider。

自訂提供者無法正常運作的常見原因在於其不是 RequestCultureProviders 清單中的第一個提供者。 若要解決此問題：

  • 在 RequestCultureProviders 清單插入位於位置零的自訂提供者：

    options.AddInitialRequestCultureProvider(
    new CustomRequestCultureProvider(async context =>
    {
        // My custom request culture logic
        return new ProviderCultureResult("en");
    }));

  • 在 RequestCultureProviders 清單插入位於位置零的自訂提供者：

    options.RequestCultureProviders.Insert(0, 
    new CustomRequestCultureProvider(async context =>
    {
        // My custom request culture logic
        return new ProviderCultureResult("en");
    }));

根命名空間問題

當組件的根命名空間與組件名稱不同時，當地語系化根據預設無法運作。 若要避免此問題，請使用 RootNamespace 屬性，如 ASP.NET Core 中的全球化和當地語系化中所述。

警告

當專案的名稱不是有效的 .NET 識別碼時，可能會發生根命名空間問題。 例如，my-project-name.csproj 會使用根命名空間 my_project_name 和組件名稱 my-project-name，這會導致此錯誤。

資源和建置動作

如果您使用資源檔進行當地語系化，務必讓他們有適當的建置動作。 使用內嵌資源；否則 ResourceStringLocalizer 無法找到這些資源。

開發人員工具中使用 [感應器] 窗格的位置覆寫

透過 Google Chrome 或 Microsoft Edge 開發人員工具中的 [感應器] 窗格使用位置覆寫時，會在預先呈現之後重設後援語言。 避免在測試時使用 [感應器] 窗格來設定語言。 使用瀏覽器的語言設定來設定語言。

如需詳細資訊，請參閱 Blazor 當地語系化不適用於 InteractiveServer (dotnet/aspnetcore #53707)。

[GitHub 問題] 提供實用的問題解決秘訣