对 ASP.NET Core 本地化进行故障排除Troubleshoot ASP.NET Core Localization

作者:Hisham Bin AteyaBy Hisham Bin Ateya

本文说明了如何诊断 ASP.NET Core 应用本地化问题。This article provides instructions on how to diagnose ASP.NET Core app localization issues.

本地化配置问题Localization configuration issues

本地化中间件顺序Localization middleware order
由于本地化中间件未按预期方式排序,因此应用可能未本地化。The app may not localize because the localization middleware isn't ordered as expected.

要解决此问题,请确保在 MVC 中间件之前注册本地化中间件。To resolve this issue, ensure that localization middleware is registered before MVC middleware. 否则,不会应用本地化中间件。Otherwise, the localization middleware isn't applied.

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

    services.AddMvc();
}

找不到本地化资源路径Localization resources path not found

RequestCultureProvider 中受支持的区域性与注册的区域性不匹配Supported Cultures in RequestCultureProvider don't match with registered once

资源文件命名问题Resource file naming issues

ASP.NET Core 具有针对本地化资源文件命名的预定义规则和指导,此处是其详细描述。ASP.NET Core has predefined rules and guidelines for localization resources file naming, which are described in detail here.

缺少资源Missing resources

找不到资源的常见原因包括:Common causes of resources not being found include:

  • resx 文件或本地化工具请求中资源名称拼写错误。Resource names are misspelled in either the resx file or the localizer request.
  • resx 中缺少某些语言的资源,但存在其他语言的资源。The resource is missing from the resx for some languages, but exists in others.
  • 如果仍有问题,请检查本地化日志消息(在 Debug 日志级别),了解有关缺少资源的详细信息。If you're still having trouble, check the localization log messages (which are at Debug log level) for more details about the missing resources.

提示: 使用 CookieRequestCultureProvider 时,验证未对本地化 cookie 值内的区域性使用单引号。例如,c='en-UK'|uic='en-US' 是无效的cookie 值,而 c=en-UK|uic=en-US 有效。Hint: When using CookieRequestCultureProvider, verify single quotes are not used with the cultures inside the localization cookie value. For example, c='en-UK'|uic='en-US' is an invalid cookie value, while c=en-UK|uic=en-US is a valid.

资源和类库问题Resources & Class Libraries issues

默认情况下,ASP.NET Core 提供一种方法,允许类库通过 ResourceLocationAttribute 查找其资源文件。ASP.NET Core by default provides a way to allow the class libraries to find their resource files via ResourceLocationAttribute.

类库的常见问题包括:Common issues with class libraries include:

  • 类库中缺少 ResourceLocationAttribute 会使 ResourceManagerStringLocalizerFactory 无法发现资源。Missing the ResourceLocationAttribute in a class library will prevent ResourceManagerStringLocalizerFactory from discovering the resources.
  • 资源文件命名。Resource file naming. 有关详细信息,请参阅资源文件命名部分。For more information, see Resource file naming issues section.
  • 更改类库的根命名空间。Changing the root namespace of the class library. 有关详细信息,请参阅根命名空间问题部分。For more information, see Root Namespace issues section.

CustomRequestCultureProvider 未按预期工作CustomRequestCultureProvider doesn't work as expected

RequestLocalizationOptions 类具有三个默认提供程序:The RequestLocalizationOptions class has three default providers:

  1. QueryStringRequestCultureProvider
  2. CookieRequestCultureProvider
  3. AcceptLanguageHeaderRequestCultureProvider

CustomRequestCultureProvider 可用于自定义在应用中提供本地化区域性的方式。The CustomRequestCultureProvider allows you to customize how the localization culture is provided in your app. 在默认提供程序无法满足需求时,可使用 CustomRequestCultureProviderThe CustomRequestCultureProvider is used when the default providers don't meet your requirements.

  • 自定义提供程序未正常工作的一个常见原因是它不是 RequestCultureProviders 列表中的第一个提供程序。A common reason custom provider don't work properly is that it isn't the first provider in the RequestCultureProviders list. 若要解决此问题,请执行以下操作:To resolve this issue:

  • RequestCultureProviders 列表的位置 0 处插入自定义提供程序,如下所示:Insert the custom provider at the position 0 in the RequestCultureProviders list as the following:

options.RequestCultureProviders.Insert(0, new CustomRequestCultureProvider(async context =>
    {
        // My custom request culture logic
        return new ProviderCultureResult("en");
    }));
options.AddInitialRequestCultureProvider(new CustomRequestCultureProvider(async context =>
    {
        // My custom request culture logic
        return new ProviderCultureResult("en");
    }));
  • 使用 AddInitialRequestCultureProvider 扩展方法将自定义提供程序设置为初始提供程序。Use AddInitialRequestCultureProvider extension method to set the custom provider as initial provider.

根命名空间问题Root Namespace issues

如果程序集的根命名空间不同于程序集名称,则默认情况下本地化无法工作。When the root namespace of an assembly is different than the assembly name, localization doesn't work by default. 若要避免此问题,请使用 RootNamespace此处是其详细描述To avoid this issue use RootNamespace, which is described in detail here

警告

当项目名称不是有效的 .NET 标识符时,可能会发生这种情况。This can occur when a project's name is not a valid .NET identifier. 例如,my-project-name.csproj 将使用根命名空间 my_project_name 和导致此错误的程序集名称 my-project-nameFor instance my-project-name.csproj will use the root namespace my_project_name and the assembly name my-project-name leading to this error.

设置和生成操作Resources & Build Action

如果使用资源文件进行本地化,则该资源文件必须具有相应的生成操作。If you use resource files for localization, it's important that they have an appropriate build action. 它们应是“嵌入的资源” ,否则 ResourceStringLocalizer 找不到这些资源。They should be Embedded Resource, otherwise the ResourceStringLocalizer is not able to find these resources.