在 ASP.NET Core 中配置可移植对象本地化

作者：Sébastien Ros 和 Scott Addie

本文演示通过 Orchard Core 框架在 ASP.NET Core 应用程序中使用可移植对象 (PO) 文件的步骤。

注意： Orchard Core 不是 Microsoft 产品。 因此，Microsoft 不提供针对此功能的支持。

查看或下载示例代码（如何下载）

什么是 PO 文件？

PO 文件作为包含给定语言的已转换字符串的文本文件分发。 使用 PO 文件替代 .resx 文件的一些优势包括：

• PO 文件支持复数形式；而 .resx 文件不支持复数形式。
• PO 文件的编译方法与 .resx 文件不同。 同样，无需专用工具和生成步骤。
• PO 文件可很好地与协作联机编辑工具结合使用。

示例

下面是一个包含两个法语字符串（其中一个具有复数形式）转换的示例 PO 文件：

fr.po

#: Services/EmailService.cs:29
msgid "Enter a comma separated list of email addresses."
msgstr "Entrez une liste d'emails séparés par une virgule."

#: Views/Email.cshtml:112
msgid "The email address is \"{0}\"."
msgid_plural "The email addresses are \"{0}\"."
msgstr[0] "L'adresse email est \"{0}\"."
msgstr[1] "Les adresses email sont \"{0}\""

此示例使用下列语法：

• #:：用于指示要转换的字符串的上下文的注释。 根据使用的位置，可对相同字符串进行不同转换。
• msgid：未转换的字符串。
• msgstr：已转换的字符串。

在支持复数形式的情况下，可定义多个条目。

• msgid_plural：未转换的复数形式字符串。
• msgstr[0]：针对事例 0 的已转换的字符串。
• msgstr[N]：针对事例 N 的已转换的字符串。

可在此处找到 PO 文件规范。

在 ASP.NET Core 中配置 PO 文件支持

此示例基于从 Visual Studio 2017 项目模板中生成的 ASP.NET Core MVC 应用程序。

引用包

添加对 OrchardCore.Localization.Core NuGet 包的引用。 它可在 MyGet 上的以下包源中获得： https://www.myget.org/F/orchardcore-preview/api/v3/index.json

.csproj 文件现在包含类似于以下内容的行（版本号可能不同）：

<PackageReference Include="OrchardCore.Localization.Core" Version="1.0.0-beta1-3187" />

注册服务

将所需服务添加到 Startup.cs 的 ConfigureServices 方法：

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc()
        .AddViewLocalization(LanguageViewLocationExpanderFormat.Suffix);

    services.AddPortableObjectLocalization();

    services.Configure<RequestLocalizationOptions>(options =>
        {
            var supportedCultures = new List<CultureInfo>
            {
                new CultureInfo("en-US"),
                new CultureInfo("en"),
                new CultureInfo("fr-FR"),
                new CultureInfo("fr")
            };

            options.DefaultRequestCulture = new RequestCulture("en-US");
            options.SupportedCultures = supportedCultures;
            options.SupportedUICultures = supportedCultures;
        });
}

将所需中间件添加到 Startup.cs 的 Configure 方法：

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
        app.UseBrowserLink();
    }
    else
    {
        app.UseExceptionHandler("/Home/Error");
    }

    app.UseStaticFiles();

    app.UseRequestLocalization();

    app.UseMvcWithDefaultRoute();
}

将以下代码添加到所选的 Razor 视图中。 在此示例中，使用了 About.cshtml。

@using Microsoft.AspNetCore.Mvc.Localization
@inject IViewLocalizer Localizer

<p>@Localizer["Hello world!"]</p>

注入了 IViewLocalizer 实例并将其用于转换文本“Hello world！”。

创建 PO 文件

在应用程序根文件夹中创建名为 <culture code>.po 的文件。 在此示例中，文件名为 fr.po，因为使用了法语：

msgid "Hello world!"
msgstr "Bonjour le monde!"

此文件存储了要转换的字符串和已转换为法语的字符串。 如有必要，转换将还原为其父级区域性。 在此示例中，如果请求的区域性为 fr-FR 或 fr-CA，则使用 fr.po 文件。

测试应用程序

运行应用程序并导航到 URL /Home/About。 此时将显示文本 Hello world! 。

导航到 URL /Home/About?culture=fr-FR。 此时将显示文本 Bonjour le monde! 。

复数形式

PO 文件支持复数形式，在相同字符串需要基于基数以不同方式进行转换时，这非常有用。 此任务较为复杂，因为每种语言均定义了自定义规则，以基于基数选择要使用的字符串。

Orchard 本地化包提供了一个 API 以自动调用这些不同的复数形式。

创建复数形式 PO 文件

将以下内容添加到前面所述的 fr.po 文件：

msgid "There is one item."
msgid_plural "There are {0} items."
msgstr[0] "Il y a un élément."
msgstr[1] "Il y a {0} éléments."

有关此示例中每个条目所表示的内容的说明，请参阅什么是 PO 文件？。

使用不同的复数形式添加语言

前面的示例中使用了英语和法语字符串。 英语和法语只有两种复数形式且拥有相同形式规则，即一的基数映射到第一种复数形式。 任何其他基数映射到第二种复数形式。

并非所有语言都拥有相同的规则。 捷克语就是一个例子，它具有三种复数形式。

如下所示，创建 cs.po 文件，并记下复数形式如何需要三种不同转换：

msgid "Hello world!"
msgstr "Ahoj světe!!"

msgid "There is one item."
msgid_plural "There are {0} items."
msgstr[0] "Existuje jedna položka."
msgstr[1] "Existují {0} položky."
msgstr[2] "Existuje {0} položek."

若要接受捷克语本地化，请将 "cs" 添加到 ConfigureServices 方法中受支持的区域性列表：

var supportedCultures = new List<CultureInfo>
{
    new CultureInfo("en-US"),
    new CultureInfo("en"),
    new CultureInfo("fr-FR"),
    new CultureInfo("fr"),
    new CultureInfo("cs")
};

编辑 Views/Home/About.cshtml 文件以呈现一些基数的已本地化复数形式字符串：

<p>@Localizer.Plural(1, "There is one item.", "There are {0} items.")</p>
<p>@Localizer.Plural(2, "There is one item.", "There are {0} items.")</p>
<p>@Localizer.Plural(5, "There is one item.", "There are {0} items.")</p>

注意： 在实际方案中，将使用变量表示计数。 此处，我们通过三个不同的值重复相同代码，以公开非常特定的事例。

切换区域性时，将显示如下内容：

对于 /Home/About：

There is one item.
There are 2 items.
There are 5 items.

对于 /Home/About?culture=fr：

Il y a un élément.
Il y a 2 éléments.
Il y a 5 éléments.

对于 /Home/About?culture=cs：

Existuje jedna položka.
Existují 2 položky.
Existuje 5 položek.

请注意，对于捷克语区域性，这三种转换各不相同。 对于最后两个已转换字符串，法语和英语区域性具有相同构造。

高级任务

将字符串置于上下文中理解

应用程序通常包含要在多个位置中进行转换的字符串。 在应用中的特定位置（Razor 视图或类文件），相同字符串可能具有不同转换。 PO 文件支持文件上下文概念，此概念可用于对所表示的字符串进行分类。 使用文件上下文，可将字符串进行不同转换，具体取决于文件上下文（或缺乏文件上下文）。

PO 本地化服务使用完整类的名称或转换字符串时使用的视图。 这通过在 msgctxt 条目上设置值来完成。

请考虑对以前的 fr.po 示例作一点小小的补充。 可通过设置保留的 msgctxt 条目的值将位于 Views/Home/About.cshtml 的 Razor 视图定义为文件上下文：

msgctxt "Views.Home.About"
msgid "Hello world!"
msgstr "Bonjour le monde!"

这样设置 msgctxt 后，导航到 /Home/About?culture=fr-FR 时将发生文本转换。 而导航到 /Home/Contact?culture=fr-FR 时，则不发生转换。

当没有特定条目与给定文件上下文相匹配时，Orchard Core 的回退机制将在没有上下文的情况下查找适当的 PO 文件。 假设不存在针对 Views/Home/Contact.cshtml 定义的特定文件上下文，导航到 /Home/Contact?culture=fr-FR，加载 PO 文件，如：

msgid "Hello world!"
msgstr "Bonjour le monde!"

更改 PO 文件的位置

可以在 ConfigureServices 中更改 PO 文件的默认位置：

services.AddPortableObjectLocalization(options => options.ResourcesPath = "Localization");

在此示例中，从本地化文件夹加载 PO 文件。

实现用于查找本地化文件的自定义逻辑

当需要更复杂的逻辑以查找 PO 文件时，可实现 OrchardCore.Localization.PortableObject.ILocalizationFileLocationProvider 接口并将其注册为服务。 在可将 PO 文件存储于不同位置或在文件夹层次结构中找到文件时，这非常有用。

使用不同默认复数形式语言

此包包含特定于两种复数形式的 Plural 扩展方法。 对于需要更多复数形式的语言，请创建扩展方法。 通过扩展方法，无需提供默认语言的任何本地化文件 — 可在代码中直接使用原始字符串。

可使用更加广泛的、接受转换的字符串数组的 Plural(int count, string[] pluralForms, params object[] arguments) 重载。