Share via

在 ASP.NET Core 應用程式中提供語言和文化特性的當地語系化資源

  • 發行項

由 Rick Anderson、Damien Bowden、Bart Calixto、Nadeem Afana 和 Hisham Bin Ateya 提供

應用程式當地語系化的其中一項工作就是在資源檔中提供當地語系化的字串。 本文是有關如何使用資源檔。

SupportedCultures 和 SupportedUICultures

ASP.NET Core 有兩個文化特性值的集合：SupportedCultures 和 SupportedUICultures。 SupportedCultures 物件的 CultureInfo 可決定文化特性相依函式的結果，例如日期、時間、數字及貨幣格式。 SupportedCultures 也可決定文字排列順序、大小寫慣例和字串比較。 如需伺服器如何取得文化特性的詳細資訊，請參閱 StringComparer.CurrentCulture。 SupportedUICultures 可決定 ResourceManager 要查閱哪些翻譯的字串 (來自 .resx 檔案)。 ResourceManager 只會查閱 CurrentUICulture 所決定的文化特性特有字串。 .NET 中的每個執行緒都有 CurrentCulture 和 CurrentUICulture 物件。 ASP.NET Core 會在轉譯文化特性相依函式時檢查這些值。 比方說，如果目前執行緒的文化特性設定為 "en-US" (英文 - 美國)，DateTime.Now.ToLongDateString() 會顯示 "Thursday, February 18, 2016"，但如果 CurrentCulture 設定為 "es-ES" (西班牙文 - 西班牙)，則輸出會是 "jueves, 18 de febrero de 2016"。

資源檔

注意：ResX 檢視器和編輯器提供替代機制，以使用 Visual Studio Code 處理資源檔。

資源檔是一種實用的機制，可讓您將可當地語系化的字串與代碼區隔開來。 非預設語言的翻譯字串會在 .resx 資源檔中隔離。 例如，您可以建立名為 Welcome.es.resx 的西班牙文資源檔，以包含翻譯的字串。 "es" 是西班牙文的語言代碼。 若要在 Visual Studio 中建立這個資源檔：

  1. 在 [方案總管] 中，以滑鼠右鍵按一下要放置資源檔的資料夾，然後選取 [新增]>[新增項目]。

    巢狀特色選單：方案總管會開啟 [資源] 的特色選單，接著針對 [新增] 開啟第二個特色選單，並反白顯示 [新增項目] 命令。

  2. 在 [Search installed templates] (搜尋已安裝的範本) 方塊中，輸入「資源」，並命名檔案。

    [新增項目] 對話方塊

  3. 在 [名稱] 資料行中輸入索引鍵值 (原生字串)，並在 [值] 資料行中輸入已翻譯的字串。

    Welcome.es.resx 檔案 (西班牙文的「歡迎使用」資源檔)，其中 [名稱] 資料行的文字為 Hello，而 [值] 資料行的文字為 Hola (Hello 的西班牙文)

    Visual Studio 會顯示 Welcome.es.resx 檔案。

    方案總管，其中顯示「歡迎使用」的西班牙文 (es) 資源檔

資源檔命名

資源的命名方式是以其類別的完整類型名稱去掉組件名稱而得。 例如，假設專案中的法文資源是 LocalizationWebsite.Web.Startup 類別、主要組件為 LocalizationWebsite.Web.dll，就會命名為 Startup.fr.resx。 LocalizationWebsite.Web.Controllers.HomeController 類別的資源會命名為 Controllers.HomeController.fr.resx。 如果目標類別的命名空間和組件名稱不相同，則需要使用完整類型名稱。 比方說，範例專案中 ExtraNamespace.Tools 類型的資源會命名為 ExtraNamespace.Tools.fr.resx。

在範例專案中，ConfigureServices 方法會將 ResourcesPath 設為 "Resources"，因此首頁控制器的法文資源檔專案相對路徑即為 Resources/Controllers.HomeController.fr.resx。 或者，您可以使用資料夾來收集資源檔。 若為首頁控制器，路徑會是 Resources/Controllers/HomeController.fr.resx。 如果您不使用 ResourcesPath 選項，.resx 檔案即會放置在專案的基底目錄中。 HomeController 的資源檔會命名為 Controllers.HomeController.fr.resx。 您可依據自己的資源檔收集方式，來選擇要使用點或路徑的命名慣例。

資源名稱 點或路徑命名
Resources/Controllers.HomeController.fr.resx 點
Resources/Controllers/HomeController.fr.resx 路徑

在 Razor 檢視中使用 @inject IViewLocalizer 的資源檔會遵循類似的模式。 您可以使用點命名或路徑命名方式，來命名檢視的資源檔。 Razor 檢視的資源檔會模仿其相關聯檢視檔案的路徑。 假設我們將 ResourcesPath 設為 "Resources"，與 Views/Home/About.cshtml 檢視建立關聯的法文資源檔可為下列其一：

  • Resources/Views/Home/About.fr.resx

  • Resources/Views.Home.About.fr.resx

如果您不使用 ResourcesPath 選項，則檢視的 .resx 檔案會與檢視位於相同資料夾中。

RootNamespaceAttribute

RootNamespaceAttribute 屬性會在組件的根命名空間與組件名稱不同時，提供組件的根命名空間。

警告

若專案名稱不是有效的 .NET 識別碼，就會發生這種情況。 例如，my-project-name.csproj 會使用根命名空間 my_project_name 和組件名稱 my-project-name，因而導致此錯誤。

如果組件的根命名空間與組件名稱不同：

  • 根據預設，當地語系化無法運作。
  • 在組件中搜尋資源的方式造成當地語系化失敗。 RootNamespace 是建置時間值，無法用於執行處理序。

如果 RootNamespace 與 AssemblyName 不同，請將下列內容納入 AssemblyInfo.cs (參數值取代為實際值)：

using System.Reflection;
using Microsoft.Extensions.Localization;

[assembly: ResourceLocation("Resource Folder Name")]
[assembly: RootNamespace("App Root Namespace")]

上述程式碼可成功解析 resx 檔案。

文化特性後援行為

搜尋資源時，當地語系化會使用「文化特性後援」。 從所要求的文化特性開始，如果找不到，就會還原成該文化特性的父文化特性。 另外，CultureInfo.Parent 屬性代表父文化特性。 這通常 (但並非一定) 表示從語言與文化特性代碼中移除國家意符 (Signifier)。 例如，墨西哥的西班牙文方言是 "es-MX"。 它具有父系 "es" — 西班牙文不是任何國家/地區的特定項目。

假設您的網站收到使用文化特性 "fr-CA" 之 "Welcome" 資源的要求。 當地語系化系統會依照順序尋找下列資源，並選取第一個相符項目：

  • Welcome.fr-CA.resx
  • Welcome.fr.resx
  • Welcome.resx (如果 NeutralResourcesLanguage 是 "fr-CA")

舉例來說，如果您移除 ".fr" 文化特性指示項，並將文化特性設定為法文，則系統會讀取預設資源檔，並將字串當地語系化。 當沒有任何項目符合您要求的文化特性時，資源管理員即會指定預設資源或後援資源。 如果您只想在要求的文化特性缺少資源時傳回索引鍵，就不能使用預設資源檔。

使用 Visual Studio 產生資源檔

如果您在 Visual Studio 中建立資源檔，但檔案名稱中不含文化特性 (例如 Welcome.resx)，則 Visual Studio 會針對每個字串的屬性建立 C# 類別。 但這通常不是您使用 ASP.NET Core 的初衷。 一般來說，您不會有預設的 .resx 資源檔 (不含文化特性名稱的 .resx 檔案)。 因此，建議您建立含有文化特性名稱的 .resx 檔案 (例如 Welcome.fr.resx)。 當您建立含有文化特性名稱的 .resx 檔案時，Visual Studio 就不會產生類別檔案。

新增其他文化特性

每種語言和文化特性的組合 (非預設語言) 都需要唯一的資源檔。 若要建立不同文化特性和地區設定的資源檔，您可以建立新的資源檔並將語言代碼作為檔名的一部分 (例如 en-us、fr-ca 和 en-gb)。 您應將這些代碼置於檔案名稱和 .resx 副檔名之間，例如 Welcome.es-MX.resx (西班牙文/墨西哥)。

下一步

當地語系化應用程式也涉及下列工作：

其他資源

由 Rick Anderson、Damien Bowden、Bart Calixto、Nadeem Afana 和 Hisham Bin Ateya 提供

應用程式當地語系化的其中一項工作就是在資源檔中提供當地語系化的字串。 本文是有關如何使用資源檔。

SupportedCultures 和 SupportedUICultures

ASP.NET Core 有兩個文化特性值的集合：SupportedCultures 和 SupportedUICultures。 SupportedCultures 物件的 CultureInfo 可決定文化特性相依函式的結果，例如日期、時間、數字及貨幣格式。 SupportedCultures 也可決定文字排列順序、大小寫慣例和字串比較。 如需伺服器如何取得文化特性的詳細資訊，請參閱 StringComparer.CurrentCulture。 SupportedUICultures 可決定 ResourceManager 要查閱哪些翻譯的字串 (來自 .resx 檔案)。 ResourceManager 只會查閱 CurrentUICulture 所決定的文化特性特有字串。 .NET 中的每個執行緒都有 CurrentCulture 和 CurrentUICulture 物件。 ASP.NET Core 會在轉譯文化特性相依函式時檢查這些值。 比方說，如果目前執行緒的文化特性設定為 "en-US" (英文 - 美國)，DateTime.Now.ToLongDateString() 會顯示 "Thursday, February 18, 2016"，但如果 CurrentCulture 設定為 "es-ES" (西班牙文 - 西班牙)，則輸出會是 "jueves, 18 de febrero de 2016"。

資源檔

資源檔是一種實用的機制，可讓您將可當地語系化的字串與代碼區隔開來。 非預設語言的翻譯字串會在 .resx 資源檔中隔離。 例如，您可以建立名為 Welcome.es.resx 的西班牙文資源檔，以包含翻譯的字串。 "es" 是西班牙文的語言代碼。 若要在 Visual Studio 中建立這個資源檔：

  1. 在 [方案總管] 中，以滑鼠右鍵按一下要放置資源檔的資料夾，然後選取 [新增]>[新增項目]。

    巢狀特色選單：方案總管會開啟 [資源] 的特色選單，接著針對 [新增] 開啟第二個特色選單，並反白顯示 [新增項目] 命令。

  2. 在 [Search installed templates] (搜尋已安裝的範本) 方塊中，輸入「資源」，並命名檔案。

    [新增項目] 對話方塊

  3. 在 [名稱] 資料行中輸入索引鍵值 (原生字串)，並在 [值] 資料行中輸入已翻譯的字串。

    Welcome.es.resx 檔案 (西班牙文的「歡迎使用」資源檔)，其中 [名稱] 資料行的文字為 Hello，而 [值] 資料行的文字為 Hola (Hello 的西班牙文)

    Visual Studio 會顯示 Welcome.es.resx 檔案。

    方案總管，其中顯示「歡迎使用」的西班牙文 (es) 資源檔

資源檔命名

資源的命名方式是以其類別的完整類型名稱去掉組件名稱而得。 例如，假設專案中的法文資源是 LocalizationWebsite.Web.Startup 類別、主要組件為 LocalizationWebsite.Web.dll，就會命名為 Startup.fr.resx。 LocalizationWebsite.Web.Controllers.HomeController 類別的資源會命名為 Controllers.HomeController.fr.resx。 如果目標類別的命名空間和組件名稱不相同，則需要使用完整類型名稱。 比方說，範例專案中 ExtraNamespace.Tools 類型的資源會命名為 ExtraNamespace.Tools.fr.resx。

在範例專案中，ConfigureServices 方法會將 ResourcesPath 設為 "Resources"，因此首頁控制器的法文資源檔專案相對路徑即為 Resources/Controllers.HomeController.fr.resx。 或者，您可以使用資料夾來收集資源檔。 若為首頁控制器，路徑會是 Resources/Controllers/HomeController.fr.resx。 如果您不使用 ResourcesPath 選項，.resx 檔案即會放置在專案的基底目錄中。 HomeController 的資源檔會命名為 Controllers.HomeController.fr.resx。 您可依據自己的資源檔收集方式，來選擇要使用點或路徑的命名慣例。

資源名稱 點或路徑命名
Resources/Controllers.HomeController.fr.resx 點
Resources/Controllers/HomeController.fr.resx 路徑

在 Razor 檢視中使用 @inject IViewLocalizer 的資源檔會遵循類似的模式。 您可以使用點命名或路徑命名方式，來命名檢視的資源檔。 Razor 檢視的資源檔會模仿其相關聯檢視檔案的路徑。 假設我們將 ResourcesPath 設為 "Resources"，與 Views/Home/About.cshtml 檢視建立關聯的法文資源檔可為下列其一：

  • Resources/Views/Home/About.fr.resx

  • Resources/Views.Home.About.fr.resx

如果您不使用 ResourcesPath 選項，則檢視的 .resx 檔案會與檢視位於相同資料夾中。

RootNamespaceAttribute

RootNamespaceAttribute 屬性會在組件的根命名空間與組件名稱不同時，提供組件的根命名空間。

警告

若專案名稱不是有效的 .NET 識別碼，就會發生這種情況。 例如，my-project-name.csproj 會使用根命名空間 my_project_name 和組件名稱 my-project-name，因而導致此錯誤。

如果組件的根命名空間與組件名稱不同：

  • 根據預設，當地語系化無法運作。
  • 在組件中搜尋資源的方式造成當地語系化失敗。 RootNamespace 是建置時間值，無法用於執行處理序。

如果 RootNamespace 與 AssemblyName 不同，請將下列內容納入 AssemblyInfo.cs (參數值取代為實際值)：

using System.Reflection;
using Microsoft.Extensions.Localization;

[assembly: ResourceLocation("Resource Folder Name")]
[assembly: RootNamespace("App Root Namespace")]

上述程式碼可成功解析 resx 檔案。

文化特性後援行為

搜尋資源時，當地語系化會使用「文化特性後援」。 從所要求的文化特性開始，如果找不到，就會還原成該文化特性的父文化特性。 另外，CultureInfo.Parent 屬性代表父文化特性。 這通常 (但並非一定) 表示從語言與文化特性代碼中移除國家意符 (Signifier)。 例如，墨西哥的西班牙文方言是 "es-MX"。 它具有父系 "es" — 西班牙文不是任何國家/地區的特定項目。

假設您的網站收到使用文化特性 "fr-CA" 之 "Welcome" 資源的要求。 當地語系化系統會依照順序尋找下列資源，並選取第一個相符項目：

  • Welcome.fr-CA.resx
  • Welcome.fr.resx
  • Welcome.resx (如果 NeutralResourcesLanguage 是 "fr-CA")

舉例來說，如果您移除 ".fr" 文化特性指示項，並將文化特性設定為法文，則系統會讀取預設資源檔，並將字串當地語系化。 當沒有任何項目符合您要求的文化特性時，資源管理員即會指定預設資源或後援資源。 如果您只想在要求的文化特性缺少資源時傳回索引鍵，就不能使用預設資源檔。

使用 Visual Studio 產生資源檔

如果您在 Visual Studio 中建立資源檔，但檔案名稱中不含文化特性 (例如 Welcome.resx)，則 Visual Studio 會針對每個字串的屬性建立 C# 類別。 但這通常不是您使用 ASP.NET Core 的初衷。 一般來說，您不會有預設的 .resx 資源檔 (不含文化特性名稱的 .resx 檔案)。 因此，建議您建立含有文化特性名稱的 .resx 檔案 (例如 Welcome.fr.resx)。 當您建立含有文化特性名稱的 .resx 檔案時，Visual Studio 就不會產生類別檔案。

新增其他文化特性

每種語言和文化特性的組合 (非預設語言) 都需要唯一的資源檔。 若要建立不同文化特性和地區設定的資源檔，您可以建立新的資源檔並將語言代碼作為檔名的一部分 (例如 en-us、fr-ca 和 en-gb)。 您應將這些代碼置於檔案名稱和 .resx 副檔名之間，例如 Welcome.es-MX.resx (西班牙文/墨西哥)。

下一步

當地語系化應用程式也涉及下列工作：

其他資源