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

  • 项目

作者：Hisham Bin Ateya

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

本地化配置问题

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

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

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

    services.AddMvc();
}

找不到本地化资源路径

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

资源文件命名问题

ASP.NET Core 对于本地化资源文件的命名有预定义的规则和指南，如《ASP.NET Core 中的全球化和本地化》中所述。

缺少资源

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

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

提示

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

资源和类库问题

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

类库的常见问题包括：

CustomRequestCultureProvider 无法按预期工作

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

CustomRequestCultureProvider 允许自定义如何提供本地化语言文化。 在默认提供程序无法满足需求时，可使用 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 问题