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

本文内容

作者:Hisham Bin Ateya

本文说明了如何诊断 ASP.NET Core 应用本地化问题。

本地化配置问题Localization configuration issues

本地化中间件顺序由于本地化中间件未按预期方式排序,因此应用可能未本地化。

要解决此问题,请确保在 MVC 中间件之前注册本地化中间件。否则,不会应用本地化中间件。

  1. public void ConfigureServices(IServiceCollection services)
  2. {
  3. services.AddLocalization(options => options.ResourcesPath = "Resources");
  4. services.AddMvc();
  5. }

找不到本地化资源路径

RequestCultureProvider 中受支持的区域性与注册的区域性不匹配

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

ASP.NET Core 具有针对本地化资源文件命名的预定义规则和指导,此处是其详细描述。

缺少资源Missing resources

找不到资源的常见原因包括:

  • resx 文件或本地化工具请求中资源名称拼写错误。
  • resx 中缺少某些语言的资源,但存在其他语言的资源。
  • 如果仍有问题,请检查本地化日志消息(在 Debug 日志级别),了解有关缺少资源的详细信息。

提示: 使用 CookieRequestCultureProvider 时,验证未对本地化 cookie 值内的区域性使用单引号。例如,c='en-UK'|uic='en-US' 是无效的 cookie 值,而 c=en-UK|uic=en-US 有效。

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

默认情况下,ASP.NET Core 提供一种方法,允许类库通过 ResourceLocationAttribute 查找其资源文件。

类库的常见问题包括:

  • 类库中缺少 ResourceLocationAttribute 会使 ResourceManagerStringLocalizerFactory 无法发现资源。
  • 资源文件命名。有关详细信息,请参阅资源文件命名部分。
  • 更改类库的根命名空间。有关详细信息,请参阅根命名空间问题部分。

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

RequestLocalizationOptions 类具有三个默认提供程序:

  • QueryStringRequestCultureProvider
  • CookieRequestCultureProvider
  • AcceptLanguageHeaderRequestCultureProvider
    CustomRequestCultureProvider 可用于自定义在应用中提供本地化区域性的方式。在默认提供程序无法满足需求时,可使用 CustomRequestCultureProvider
  • 自定义提供程序未正常工作的一个常见原因是它不是 RequestCultureProviders 列表中的第一个提供程序。若要解决此问题,请执行以下操作:

  • RequestCultureProviders 列表的位置 0 处插入自定义提供程序,如下所示:

  1. options.RequestCultureProviders.Insert(0, new CustomRequestCultureProvider(async context =>
  2. {
  3. // My custom request culture logic
  4. return new ProviderCultureResult("en");
  5. }));
  1. options.AddInitialRequestCultureProvider(new CustomRequestCultureProvider(async context =>
  2. {
  3. // My custom request culture logic
  4. return new ProviderCultureResult("en");
  5. }));
  • 使用 AddInitialRequestCultureProvider 扩展方法将自定义提供程序设置为初始提供程序。

根命名空间问题Root Namespace issues

如果程序集的根命名空间不同于程序集名称,则默认情况下本地化无法工作。若要避免此问题,请使用 RootNamespace此处是其详细描述

警告

当项目名称不是有效的 .NET 标识符时,可能会发生这种情况。例如,my-project-name.csproj 将使用根命名空间 my_project_name 和导致此错误的程序集名称 my-project-name

设置和生成操作Resources & Build Action

如果使用资源文件进行本地化,则该资源文件必须具有相应的生成操作。它们应是“嵌入的资源” ,否则 ResourceStringLocalizer 找不到这些资源。