参考:https://learn.microsoft.com/zh-cn/aspnet/core/fundamentals/localization?view=aspnetcore-8.0

概述

术语

  • 全球化 (G11N):使应用支持不同语言和区域的过程。 缩写来自第一个和最后一个字母以及它们之间的字母数。
  • 本地化 (L10N):针对特定语言和区域自定义全球化应用的过程。
  • 国际化 (I18N):包括全球化和本地化。
  • 区域性:一种语言和/或区域。
  • 非特定区域性:具有指定语言但不具有区域的区域性(例如“en”、“es”)。
  • 特定区域性:具有指定语言但和区域的区域性(例如“en-US”、“en-GB”、“es-CL”)。
  • 父区域性:包含特定区域性的非特定区域性。(例如,“en”是“en-US”和“en-GB”的父区域性)。
  • 区域设置:区域设置与区域性相同。

本地化器

  • IStringLocalizer
  • IStringLocalizerFactory
  • IHtmlLocalizer
  • IViewLocalizer

IStringLocalizer

IStringLocalizerIStringLocalizer<>可以在运行时提供区域性资源,使用非常简单,就像操作字典一样,提供一个 Key,就能获取到指定区域的资源。另外,它还允许 Key 在资源中不存在,此时返回的就是 Key 自身。我们下面称这个 Key 为资源名。

下面是他们的结构定义:

public interface IStringLocalizer
{
// 通过资源名获取本地化文本,如果资源不存在,则返回 name 自身
LocalizedString this[string name] { get; } // 通过资源名获取本地化文本,并允许将参数值填充到文本中,如果资源不存在,则返回 name 自身
LocalizedString this[string name, params object[] arguments] { get; } // 获取所有的本地化资源文本
IEnumerable<LocalizedString> GetAllStrings(bool includeParentCultures);
} public interface IStringLocalizer<out T> : IStringLocalizer
{
}

在服务类中使用本地化

  1. 首先,注入本地化服务,并启用中间件
var builder = WebApplication.CreateBuilder(args);

// 注册服务
builder.Services.AddLocalization(options => options.ResourcesPath = "Resources"); var app = builder.Build(); // 启用中间件
app.UseRequestLocalization(options =>
{
var cultures = new[] { "zh-CN", "en-US", "zh-TW" };
options.AddSupportedCultures(cultures);
options.AddSupportedUICultures(cultures);
options.SetDefaultCulture(cultures[0]); // 当Http响应时,将 当前区域信息 设置到 Response Header:Content-Language 中
options.ApplyCurrentCultureToResponseHeaders = true;
}); app.MapControllerRoute(
name: "default",
pattern: "{controller=Home}/{action=Index}/{id?}"); app.Run();

首先,我们通过AddLocalization注册了IStringLocalizerFactoryIStringLocalizer<>,并指定了资源的根目录为“Resources”。

然后,我们又通过UseRequestLocalization启用了中间件RequestLocalizationMiddleware。默认情况下,该中间件支持的区域文化仅为当前区域文化,即CultureInfo.CurrentCultureCultureInfo.CurrentUICulture,我们可以通过AddSupportedCulturesAddSupportedUICultures自定义设置多个支持的区域文化:

  • Culture:影响日期、时间、数字或货币的展示格式
  • UICulture:影响查找哪些区域文化资源(如.resx、json文件等),也就是说,如果这里未添加某区域文化A,即使添加了对应区域文化A的资源文件,也无发生效。一般 Culture 和 UICulture 保持一致。

另外,当我们的服务接收到一个请求时,如果该请求未指明当前的区域文化,就会使用默认的,这里我们通过SetDefaultCulture指定了默认区域文化为 zh-CN

最后,通过设置ApplyCurrentCultureToResponseHeaderstrue,将当前区域信息设置到Http响应头的Content-Language中。

  1. 接下来,我们新建“Resources/Controllers”目录,在 Resources 目录下新建2个共享资源文件,在 Controllers 目录中新建2个HomeController类的资源文件,目录结构如下:
- Resources
- Controllers
- HomeController.en-US.resx
- HomeController.zh-CN.resx
- SharedResource.en-US.resx
- SharedResource.zh-CN.resx
  • SharedResource.en-US.resx
名称
CurrentTime Current Time:
  • SharedResource.zh-CN.resx
名称
CurrentTime 当前时间:
  • HomeController.en-US.resx
名称
HelloWorld Hello, World!
  • HomeController.zh-CN.resx
名称
HelloWorld 你好,世界!

这些文件默认为“嵌入的资源”

  1. 为了优雅地使用共享资源,我们在项目根目录下创建SharedResource伪类,用来代理共享资源。
public class SharedResource
{
// 里面是空的
}
  1. 最后,我们在HomeController中尝试一下效果
public class HomeController : Controller
{
// 用于提供 HomeController 的区域性资源
private readonly IStringLocalizer<HomeController> _localizer; // 通过代理伪类提供共享资源
private readonly IStringLocalizer<SharedResource> _sharedLocalizer; public HomeController(
IStringLocalizer<HomeController> localizer,
IStringLocalizer<SharedResource> sharedLocalizer
)
{
_localizer = localizer;
_sharedLocalizer = sharedLocalizer;
} [HttpGet]
public IActionResult GetString()
{
var content = $"当前区域文化:{CultureInfo.CurrentCulture.Name}\n" +
$"{_localizer["HelloWorld"]}\n" +
$"{_sharedLocalizer["CurrentTime"]}{DateTime.Now.ToLocalTime()}\n";
return Content(content);
}
}

访问{your-host}/home/getstring,使用默认的区域文化zh-CN,获取结果如下:

highlighter- awk

当前区域文化:zh-CN
你好,世界!
当前时间:2023/6/2 11:19:08

此时查看响应头信息,可以发现

Content-Language: zh-CN

下面,我们通过 url 传递参数culture,指定区域文化为en-US,访问{your-host}/home/getstring?culture=en-US,获取结果如下:

highlighter- awk

当前区域文化:en-US
Hello, World!
Current Time:6/2/2023 11:47:50 AM

此时的响应头信息:

Content-Language: en-US

如果你的本地化果并不是预期的,并且当前区域文化没问题的情况下,可以通过SearchedLocation查看资源搜索位置(如 _localizer["HelloWord"].SearchedLocation),检查资源放置位置是否有误。

IStringLocalizerFactory

有时,我们可能想要使用一些没有代理类或代理类无法使用的区域资源,无法直接通过IStringLocalizer<>进行注入,那IStringLocalizerFactory就可以帮助我们获取对应的IStringLocalizer,该接口结构如下:

csharp

public interface IStringLocalizerFactory
{
IStringLocalizer Create(Type resourceSource); IStringLocalizer Create(string baseName, string location);
}

下面我们通过IStringLocalizerFactory来获取HomeController资源实例:

public class HomeController : Controller
{
private readonly IStringLocalizer _localizer; private readonly IStringLocalizer _localizer2; public HomeController(IStringLocalizerFactory localizerFactory)
{
_localizer = localizerFactory.Create(typeof(HomeController));
_localizer2 = localizerFactory.Create("Controllers.HomeController", Assembly.GetExecutingAssembly().FullName);
} [HttpGet]
public IActionResult GetString()
{
var content = $"当前区域文化:{CultureInfo.CurrentCulture.Name}\n" +
$"{_localizer["HelloWorld"]}\n" +
$"{_localizer2["HelloWorld"]}\n";
return Content(content);
}
}

这里演示了两种创建方式:

  • 一个是通过类型来创建,一般我们不会手动通过该方式获取,而是直接注入对应的泛型版本
  • 另一个是通过指定资源基础名称和所属程序集来创建,所谓资源基础名称,就是资源文件相对于资源根目录的相对路径+文件基础名称,例如对于 HomeController.XXX.resx 来说,资源根目录就是前面注册服务时设置的 Resources,相对路径为 Controllers,文件基础名为 HomeController,所以资源基础名称为 Controllers.HomeController

IHtmlLocalizer

相对于IStringLocalizerIHtmlLocalizerIHtmlLocalizer<>中的资源可以包含 HTML 代码,并使其能够在前端页面中正常渲染出来。

通常情况下,我们仅仅需要本地化文本内容,而不会包含 HTML。不过这里还是简单介绍一下。

  1. 首先调用AddViewLocalization注册服务
builder.Services
.AddControllersWithViews()
.AddViewLocalization(LanguageViewLocationExpanderFormat.Suffix);

此处我们注册了IHtmlLocalizerFactoryIHtmlLocalizer<>,以及接下来要讲的IViewLocalizer共3个服务,并且通过LanguageViewLocationExpanderFormat.Suffix指定了视图(View)语言资源命名格式为后缀,即 <view-name>.<language>.resx

  1. 接着在 SharedResource 的资源文件中添加以下内容:
  • SharedResource.en-US.resx
名称
Welcome Welcome {0}!
  • SharedResource.zh-CN.resx
名称
Welcome 欢迎 {0}!
  1. 最后自己可以在视图中看一下效果,文本确实被加粗了:
@inject IHtmlLocalizer<SharedResource> HtmlSharedResource

<div class="text-center">
@HtmlSharedResource["Welcome", "jjj"]
</div>

IViewLocalizer

IViewLocalizer是专门服务于视图的,他没有泛型版本,也没有工厂类,所以它只能用来获取当前视图资源文件中的资源,如果想要使用其他资源,可以使用IStringLocalizerIHtmlLocalizer

它继承自IHtmlLocalizer,所以它也支持资源中包含 HTML 代码:

public interface IViewLocalizer : IHtmlLocalizer { }

下面我们在Views/Home/Index.cshtml中演示一下效果。

上面我们已经通过AddViewLocalizationIViewLocalizer服务注册到容器中了。

  1. 首先在Resources/Views/Home目录下增加以下两个资源文件,并设置内容:
  • Index.en-US.resx
名称
Welcome Welcome {0} !!!
  • Index.zh-CN
名称
Welcome 欢迎 {0} !!!
  1. 在视图中使用并查看效果
@inject IViewLocalizer L 

<div class="text-center">
<h1>@L["Welcome", "jjj"]</h1>
</div>

资源文件

资源文件是将可本地化的字符串与代码分离的有用机制。 非默认语言的转换字符串在 .resx 资源文件中单独显示。 例如,你可能想要创建一个包含转换字符串、名为 Controllers.HomeController.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/Controllers.HomeController.fr.resx。 或者,你可以使用文件夹组织资源文件。 对于主控制器,该路径将为 Resources/Controllers/HomeController.fr.resx。 如果不使用 ResourcesPath 选项,.resx 文件将转到项目的基目录中。 HomeController 的资源文件将命名为 Controllers.HomeController.fr.resx。 是选择使用圆点还是路径命名约定,具体取决于你想如何组织资源文件。

强烈建议程序的程序集名称与根命名空间保持一致,这样可以省很多事。如果不一致,当然也有解决办法,例如有个DifferentController,它位于Different.Controllers命名空间下,那么资源文件需要放置于Resources/Different/Controllers目录下。

最后,如果你愿意,可以把SharedResource类放到 Resources 文件夹下,让它和它的资源文件在一起,不过要注意它的命名空间,确保该类够按照上述规则对应到资源文件上。你可能还需要在.csproj文件中进行如下配置(二选一,具体原因参考此文档):

<PropertyGroup>
<EmbeddedResourceUseDependentUponConvention>false</EmbeddedResourceUseDependentUponConvention>
</PropertyGroup>
<ItemGroup>
<EmbeddedResource Include="Resources/SharedResource.en-US.resx" DependentUpon="SharedResources" />
<EmbeddedResource Include="Resources/SharedResource.zh-CN.resx" DependentUpon="SharedResources" />
</ItemGroup>

区域性回退

当请求的区域资源未找到时,会回退到该区域的父区域资源,例如档区域文化为 zh-CN 时,HomeController资源文件查找顺序如下:

  • HomeController.zh-CN.resx
  • HomeController.zh.resx
  • HomeController.resx

如果都没找到,则会返回资源 Key 本身。

配置 CultureProvider

内置的 RequestCultureProvider

  1. QueryStringRequestCultureProvider:通过在 Query 中设置"culture"、"ui-culture"的值,例如 ?culture=zh-CN&ui-culture=zh-CN
  2. CookieRequestCultureProvider:通过Cookie中设置名为 ".AspNetCore.Culture" Key 的值,值形如 c=zh-CN|uic=zh-CN
  3. AcceptLanguageHeaderRequestCultureProvider:从请求头中设置 "Accept-Language" 的值

我们也可以在这3个的基础上进行自定义配置,例如通过在 Query 中设置"lang"的值来设置区域:

options.AddInitialRequestCultureProvider(new QueryStringRequestCultureProvider() { QueryStringKey = "lang" });

AddInitialRequestCultureProvider默认将新添加的 Provider 放置在首位。

内置的还有一个RouteDataRequestCultureProvider,不过它并没有被默认添加到提供器列表中。它默认可以通过在路由中设置 culture 的值来设置区域,就像微软官方文档一样。需要注意的是,一定要在 app.UseRouting() 之后再调用 app.UseRequestLocalization()

实现自定义 RequestCultureProvider

实现自定义RequestCultureProvider的方式有两种,分别是通过委托和继承抽象类RequestCultureProvider

下面,我们实现一个从自定义 Header 中获取区域文化信息的自定义RequestCultureProvider

  1. 通过委托实现自定义RequestCultureProviders
app.UseRequestLocalization(options =>
{
var cultures = new[] { "zh-CN", "en-US", "zh-TW" };
options.AddSupportedCultures(cultures);
options.AddSupportedUICultures(cultures);
options.SetDefaultCulture(cultures[0]); options.RequestCultureProviders.Insert(0, new CustomRequestCultureProvider(context =>
{
ArgumentException.ThrowIfNullOrEmpty(nameof(context));
// 从请求头“X-Lang”中获取区域文化信息
var acceptLanguageHeader = context.Request.GetTypedHeaders().GetList<StringWithQualityHeaderValue>("X-Lang"); if (acceptLanguageHeader == null || acceptLanguageHeader.Count == 0)
{
return Task.FromResult(default(ProviderCultureResult));
} var languages = acceptLanguageHeader.AsEnumerable(); // 如果值包含多,我们只取前3个
languages = languages.Take(3); var orderedLanguages = languages.OrderByDescending(h => h, StringWithQualityHeaderValueComparer.QualityComparer)
.Select(x => x.Value).ToList(); if (orderedLanguages.Count > 0)
{
return Task.FromResult(new ProviderCultureResult(orderedLanguages));
} return Task.FromResult(default(ProviderCultureResult));
}));
}

需要注意的是,当未获取到区域文化信息时,若想要接着让后面的RequestCultureProvider继续解析获取,则记得一定要返回default(ProviderCultureResult),否则建议直接返回默认区域文化,即new ProviderCultureResult(options.DefaultRequestCulture.Culture.Name

  1. 通过继承抽象类RequestCultureProvider
public interface IRequestCultureProvider
{
// 确定当前请求的区域性,我们要实现这个接口
Task<ProviderCultureResult?> DetermineProviderCultureResult(HttpContext httpContext);
} public abstract class RequestCultureProvider : IRequestCultureProvider
{
// 指代空区域性结果
protected static readonly Task<ProviderCultureResult?> NullProviderCultureResult = Task.FromResult(default(ProviderCultureResult)); // 中间件 RequestLocalizationMiddleware 的选项
public RequestLocalizationOptions? Options { get; set; } public abstract Task<ProviderCultureResult?> DetermineProviderCultureResult(HttpContext httpContext);
} public class CustomHeaderRequestCultureProvider : RequestCultureProvider
{
// Header 名称,默认为 Accept-Language
public string HeaderName { get; set; } = HeaderNames.AcceptLanguage; // 当 Header 值有多个时,最多取前 n 个
public int MaximumHeaderValuesToTry { get; set; } = 3; public override Task<ProviderCultureResult> DetermineProviderCultureResult(HttpContext httpContext)
{
ArgumentException.ThrowIfNullOrEmpty(nameof(httpContext));
ArgumentException.ThrowIfNullOrEmpty(nameof(HeaderName)); var acceptLanguageHeader = httpContext.Request.GetTypedHeaders().GetList<StringWithQualityHeaderValue>(HeaderName); if (acceptLanguageHeader == null || acceptLanguageHeader.Count == 0)
{
return NullProviderCultureResult;
} var languages = acceptLanguageHeader.AsEnumerable(); if (MaximumHeaderValuesToTry > 0)
{
languages = languages.Take(MaximumHeaderValuesToTry);
} var orderedLanguages = languages.OrderByDescending(h => h, StringWithQualityHeaderValueComparer.QualityComparer)
.Select(x => x.Value).ToList(); if (orderedLanguages.Count > 0)
{
return Task.FromResult(new ProviderCultureResult(orderedLanguages));
} return NullProviderCultureResult;
}
} app.UseRequestLocalization(options =>
{
var cultures = new[] { "zh-CN", "en-US", "zh-TW" };
options.AddSupportedCultures(cultures);
options.AddSupportedUICultures(cultures);
options.SetDefaultCulture(cultures[0]); options.RequestCultureProviders.Insert(0, new CustomHeaderRequestCultureProvider { HeaderName = "X-Lang" });
}

使用 Json 资源文件

你可能和我一样,不太喜欢 .resx 资源文件,想要将多语言配置到 json 文件中,虽然微软并没有提供完整地实现,但是社区已经有大佬根据接口规范为我们写好了,这里推荐使用My.Extensions.Localization.Json

ASP.NET Core 也支持 PO 文件,如果有兴趣,请自行了解。

只需要将AddLocalization替换为AddJsonLocalization即可:

builder.Services.AddJsonLocalization(options => options.ResourcesPath = "JsonResources");

后面就是在 json 文件中配置多语言了,例如:

  • HomeController.en-US.json
{
"HelloWorld": "Hello,World!"
}
  • HomeController.zh-CN.json
{
"HelloWorld": "你好,世界!"
}

设计原理

现在,基础用法我们已经了解了,接下来就一起学习一下它背后的原理吧。

鉴于涉及到的源码较多,所以为了控制文章长度,下面只列举核心代码。

IStringLocalizerFactory & IStringLocalizer

先来看下AddLocalization中注册的默认实现:

public static class LocalizationServiceCollectionExtensions
{
internal static void AddLocalizationServices(IServiceCollection services)
{
services.TryAddSingleton<IStringLocalizerFactory, ResourceManagerStringLocalizerFactory>();
services.TryAddTransient(typeof(IStringLocalizer<>), typeof(StringLocalizer<>));
}
}

一共注册了两个实现,分别是ResourceManagerStringLocalizerFactoryStringLocalizer<>,先来看一下工厂:

public interface IStringLocalizerFactory
{
IStringLocalizer Create(Type resourceSource); IStringLocalizer Create(string baseName, string location);
} public class ResourceManagerStringLocalizerFactory : IStringLocalizerFactory
{
private readonly IResourceNamesCache _resourceNamesCache = new ResourceNamesCache();
private readonly ConcurrentDictionary<string, ResourceManagerStringLocalizer> _localizerCache =
new ConcurrentDictionary<string, ResourceManagerStringLocalizer>();
private readonly string _resourcesRelativePath; public ResourceManagerStringLocalizerFactory(
IOptions<LocalizationOptions> localizationOptions)
{
_resourcesRelativePath = localizationOptions.Value.ResourcesPath ?? string.Empty; if (!string.IsNullOrEmpty(_resourcesRelativePath))
{
// 将目录分隔符“/”和“\”全部替换为“.”
_resourcesRelativePath = _resourcesRelativePath.Replace(Path.AltDirectorySeparatorChar, '.')
.Replace(Path.DirectorySeparatorChar, '.') + ".";
}
} protected virtual string GetResourcePrefix(TypeInfo typeInfo)
{
// 代码不列了,直接说一下逻辑吧:
// 1. 如果资源根路径(_resourcesRelativePath)为空,即项目的根目录,那么直接返回 typeInfo.FullName
// 2. 如果资源根路径(_resourcesRelativePath)不为空,那么需要将资源根目录拼接在 typeInfo.FullName 中间, 按照如下格式拼接(注意里面的是减号):"{RootNamespace}.{ResourceLocation}.{FullTypeName - RootNamespace}"
} protected virtual string GetResourcePrefix(string baseResourceName, string baseNamespace)
{
// 逻辑同上
} public IStringLocalizer Create(Type resourceSource)
{
var typeInfo = resourceSource.GetTypeInfo(); var baseName = GetResourcePrefix(typeInfo); var assembly = typeInfo.Assembly; return _localizerCache.GetOrAdd(baseName, _ => CreateResourceManagerStringLocalizer(assembly, baseName));
} public IStringLocalizer Create(string baseName, string location)
{
return _localizerCache.GetOrAdd($"B={baseName},L={location}", _ =>
{
var assemblyName = new AssemblyName(location);
var assembly = Assembly.Load(assemblyName);
baseName = GetResourcePrefix(baseName, location); return CreateResourceManagerStringLocalizer(assembly, baseName);
});
} protected virtual ResourceManagerStringLocalizer CreateResourceManagerStringLocalizer(
Assembly assembly,
string baseName)
{
return new ResourceManagerStringLocalizer(
new ResourceManager(baseName, assembly), // 指定了资源的基础名和所属程序集
assembly,
baseName,
_resourceNamesCache);
}
}

可以看到,Create(Type resourceSource)Create(string baseName, string location)的实现都是通过CreateResourceManagerStringLocalizer来创建的,并且实例类型就是ResourceManagerStringLocalizer。另外,还通过_localizerCache将已创建的资源实例缓存了下来,避免了重复创建的开销,只不过由于缓存 Key 的构造规则不同,两者创建的实例并不能共享。

如果你现在就想要验证一下 HomeController 中的 Localizer 是否是相同的,你会发现通过构造函数直接注入的 IStringLocalizer<>._localizer 才是真正干活,你可以参考这段代码来获取它:typeof(Microsoft.Extensions.Localization.StringLocalizer<GlobalizationAndLocalization.SharedResource>).GetField("_localizer", BindingFlags.NonPublic | BindingFlags.GetField | BindingFlags.Instance).GetValue(mySharedLocalizer)

接着看ResourceManagerStringLocalizer的实现细节:

public interface IStringLocalizer
{
LocalizedString this[string name] { get; } LocalizedString this[string name, params object[] arguments] { get; } IEnumerable<LocalizedString> GetAllStrings(bool includeParentCultures);
} public class ResourceManagerStringLocalizer : IStringLocalizer
{
// 将不存在的资源 Key 进行缓存
private readonly ConcurrentDictionary<string, object?> _missingManifestCache = new ConcurrentDictionary<string, object?>();
// 用于操作 .resx 资源文件
private readonly ResourceManager _resourceManager;
private readonly IResourceStringProvider _resourceStringProvider;
private readonly string _resourceBaseName; public ResourceManagerStringLocalizer(
ResourceManager resourceManager,
Assembly resourceAssembly,
string baseName, // 资源的基础名称,类似于 xxx.xxx.xxx
IResourceNamesCache resourceNamesCache)
: this(
resourceManager,
new AssemblyWrapper(resourceAssembly),
baseName,
resourceNamesCache)
{
} internal ResourceManagerStringLocalizer(
ResourceManager resourceManager,
AssemblyWrapper resourceAssemblyWrapper,
string baseName,
IResourceNamesCache resourceNamesCache
: this(
resourceManager,
new ResourceManagerStringProvider(
resourceNamesCache,
resourceManager,
resourceAssemblyWrapper.Assembly,
baseName),
baseName,
resourceNamesCache)
{
} internal ResourceManagerStringLocalizer(
ResourceManager resourceManager,
IResourceStringProvider resourceStringProvider,
string baseName,
IResourceNamesCache resourceNamesCache)
{
_resourceStringProvider = resourceStringProvider;
_resourceManager = resourceManager;
_resourceBaseName = baseName;
_resourceNamesCache = resourceNamesCache;
} public virtual LocalizedString this[string name]
{
get
{
var value = GetStringSafely(name, culture: null); // LocalizedString 包含了 资源名、资源值、资源是否不存在、资源搜索位 等信息
return new LocalizedString(name, value ?? name, resourceNotFound: value == null, searchedLocation: _resourceBaseName);
}
} public virtual LocalizedString this[string name, params object[] arguments]
{
get
{
var format = GetStringSafely(name, culture: null);
var value = string.Format(CultureInfo.CurrentCulture, format ?? name, arguments); return new LocalizedString(name, value, resourceNotFound: format == null, searchedLocation: _resourceBaseName);
}
} public virtual IEnumerable<LocalizedString> GetAllStrings(bool includeParentCultures) =>
GetAllStrings(includeParentCultures, CultureInfo.CurrentUICulture); protected IEnumerable<LocalizedString> GetAllStrings(bool includeParentCultures, CultureInfo culture)
{
// 通过 culture 获取所有资源,原理与通过资源名获取类似
// 需要注意的是,它是通过 yield return 返回的
} // 所谓 Safely,就是当 资源名 不存在时,不会抛出异常,而是返回 null
protected string? GetStringSafely(string name, CultureInfo? culture)
{
var keyCulture = culture ?? CultureInfo.CurrentUICulture; var cacheKey = $"name={name}&culture={keyCulture.Name}"; // 资源已缓存为不存在,直接返回 null
if (_missingManifestCache.ContainsKey(cacheKey))
{
return null;
} try
{
// 通过 ResourceManager 获取资源
return _resourceManager.GetString(name, culture);
}
catch (MissingManifestResourceException)
{
// 若资源不存在,则缓存
_missingManifestCache.TryAdd(cacheKey, null);
return null;
}
}
}

好了,资源的加载流程我们已经清楚了,还有一个StringLocalizer<>需要看一下:

public interface IStringLocalizer<out T> : IStringLocalizer
{
} public class StringLocalizer<TResourceSource> : IStringLocalizer<TResourceSource>
{
private readonly IStringLocalizer _localizer; public StringLocalizer(IStringLocalizerFactory factory)
{
_localizer = factory.Create(typeof(TResourceSource));
} public virtual LocalizedString this[string name] => _localizer[name]; public virtual LocalizedString this[string name, params object[] arguments] => _localizer[name, arguments]; public IEnumerable<LocalizedString> GetAllStrings(bool includeParentCultures) =>
_localizer.GetAllStrings(includeParentCultures);
}

其实很简单,本质上还是通过工厂创建的本地化实例,真正干活的其实是它的私有变量_localizer,泛型只是一层包装。

DataAnnotationsLocalization

现在StringLocalizer的原理我们已经搞清楚了,但是数据注解本地化是如何实现的呢?它啊,其实也是通过StringLocalizer实现的,看:

public static IMvcCoreBuilder AddDataAnnotationsLocalization(
this IMvcCoreBuilder builder,
Action<MvcDataAnnotationsLocalizationOptions>? setupAction)
{
AddDataAnnotationsLocalizationServices(services, setupAction);
return builder;
} public static void AddDataAnnotationsLocalizationServices(
IServiceCollection services,
Action<MvcDataAnnotationsLocalizationOptions>? setupAction)
{
services.AddLocalization(); // 如果传入的 setup 委托不为空则使用该委托配置 MvcDataAnnotationsLocalizationOptions,
if (setupAction != null)
{
services.Configure(setupAction);
}
// 否则使用默认的 MvcDataAnnotationsLocalizationOptionsSetup 进行配置
else
{
services.TryAddEnumerable(
ServiceDescriptor.Transient
<IConfigureOptions<MvcDataAnnotationsLocalizationOptions>,
MvcDataAnnotationsLocalizationOptionsSetup>());
}
} internal class MvcDataAnnotationsLocalizationOptionsSetup : IConfigureOptions<MvcDataAnnotationsLocalizationOptions>
{
public void Configure(MvcDataAnnotationsLocalizationOptions options)
{
options.DataAnnotationLocalizerProvider = (modelType, stringLocalizerFactory) =>
stringLocalizerFactory.Create(modelType);
}
}

可以看到,MvcDataAnnotationsLocalizationOptions提供了一个委托DataAnnotationLocalizerProvider,它接收两个参数,TypeIStringLocalizerFactory,返回一个IStringLocalizer。从这里我们就可以看出来,它的本地化就是通过IStringLocalizer来实现的。

默认情况下,它的本地化器指向当前模型类资源,我上面提到过,可以将其自定义为从共享资源中获取,这下你就理解为啥所有模类都会受影响了吧。

RequestLocalizationMiddleware

RequestLocalizationMiddleware的作用主要是解析并设置当前请求的区域文化,以便于本地化器可以正常工作。

我们可以通过RequestLocalizationOptions对该中间件进行配置,可配置项如下:

public class RequestLocalizationOptions
{
private RequestCulture _defaultRequestCulture =
new RequestCulture(CultureInfo.CurrentCulture, CultureInfo.CurrentUICulture); public RequestLocalizationOptions()
{
RequestCultureProviders = new List<IRequestCultureProvider>
{
new QueryStringRequestCultureProvider { Options = this },
new CookieRequestCultureProvider { Options = this },
new AcceptLanguageHeaderRequestCultureProvider { Options = this }
};
} // 默认请求区域文化,默认值:当前区域文化
public RequestCulture DefaultRequestCulture
{
get => _defaultRequestCulture;
set
{
if (value == null)
{
throw new ArgumentNullException(nameof(value));
} _defaultRequestCulture = value;
}
} // 是否允许回退到父区域文化,默认值:true
public bool FallBackToParentCultures { get; set; } = true; // 是否允许回退到父UI区域文化,默认值:true
public bool FallBackToParentUICultures { get; set; } = true; // 是否要将当前请求的区域文化设置到响应头 Content-Language 中,默认值:false
public bool ApplyCurrentCultureToResponseHeaders { get; set; } // 受支持的区域文化列表,默认仅支持当前区域文化
public IList<CultureInfo>? SupportedCultures { get; set; } = new List<CultureInfo> { CultureInfo.CurrentCulture }; // 受支持的UI区域文化列表,默认仅支持当前UI区域文化
public IList<CultureInfo>? SupportedUICultures { get; set; } = new List<CultureInfo> { CultureInfo.CurrentUICulture }; // 请求区域文化提供器列表
public IList<IRequestCultureProvider> RequestCultureProviders { get; set; } // 设置受支持的区域文化(注意,它的行为是 Set,而不是 Add)
public RequestLocalizationOptions AddSupportedCultures(params string[] cultures)
{
var supportedCultures = new List<CultureInfo>(cultures.Length); foreach (var culture in cultures)
{
supportedCultures.Add(new CultureInfo(culture));
} SupportedCultures = supportedCultures;
return this;
} // 设置受支持的UI区域文化(注意,它的行为是 Set,而不是 Add)
public RequestLocalizationOptions AddSupportedUICultures(params string[] uiCultures)
{
var supportedUICultures = new List<CultureInfo>(uiCultures.Length);
foreach (var culture in uiCultures)
{
supportedUICultures.Add(new CultureInfo(culture));
} SupportedUICultures = supportedUICultures;
return this;
} // 设置默认区域文化
public RequestLocalizationOptions SetDefaultCulture(string defaultCulture)
{
DefaultRequestCulture = new RequestCulture(defaultCulture);
return this;
}
}

下面看一下RequestLocalizationMiddleware中间件的实现:

public class RequestLocalizationMiddleware
{
// 区域文化回退最大深度,5 层已经很足够了
private const int MaxCultureFallbackDepth = 5; private readonly RequestDelegate _next;
private readonly RequestLocalizationOptions _options; public RequestLocalizationMiddleware(RequestDelegate next, IOptions<RequestLocalizationOptions> options)
{
_next = next ?? throw new ArgumentNullException(nameof(next));
_options = options.Value;
} public async Task Invoke(HttpContext context)
{
// 默认当前请求区域文化为 options 中配置的默认值
var requestCulture = _options.DefaultRequestCulture; IRequestCultureProvider? winningProvider = null; // 如果存在 Provider,则通过 Provider 解析当前请求中设置的区域文化
if (_options.RequestCultureProviders != null)
{
foreach (var provider in _options.RequestCultureProviders)
{
var providerResultCulture = await provider.DetermineProviderCultureResult(context);
// 如果解析出来为 null,则继续让后续的 Provider 继续解析
if (providerResultCulture == null)
{
continue;
}
var cultures = providerResultCulture.Cultures;
var uiCultures = providerResultCulture.UICultures; CultureInfo? cultureInfo = null;
CultureInfo? uiCultureInfo = null;
if (_options.SupportedCultures != null)
{
// 检查区域文化(可能有多个)是否支持,如果不支持则返回 null
cultureInfo = GetCultureInfo(
cultures,
_options.SupportedCultures,
_options.FallBackToParentCultures);
} if (_options.SupportedUICultures != null)
{
// 检查UI区域文化(可能有多个)是否支持,如果不支持则返回 null
uiCultureInfo = GetCultureInfo(
uiCultures,
_options.SupportedUICultures,
_options.FallBackToParentUICultures);
} // 如果区域文化和UI区域文化均不受支持,则视为解析失败,继续让下一个 Provider 解析
if (cultureInfo == null && uiCultureInfo == null)
{
continue;
} // 两种区域文化若有为 null 的,则赋 options 中设置的默认值
// 注意:我们上面讲 Provider 时提到过,如果只传了 culture 和 ui-culture 其中的一个值,会将该值赋值到两者,这个行为是 Provider 中执行的,不要搞混咯
cultureInfo ??= _options.DefaultRequestCulture.Culture;
uiCultureInfo ??= _options.DefaultRequestCulture.UICulture; var result = new RequestCulture(cultureInfo, uiCultureInfo);
requestCulture = result;
winningProvider = provider; // 解析成功,直接跳出
break;
}
} context.Features.Set<IRequestCultureFeature>(new RequestCultureFeature(requestCulture, winningProvider)); // 将当前区域文化信息设置到当前请求的线程,便于后续本地化器读取
SetCurrentThreadCulture(requestCulture); if (_options.ApplyCurrentCultureToResponseHeaders)
{
var headers = context.Response.Headers;
headers.ContentLanguage = requestCulture.UICulture.Name;
} await _next(context);
} private static void SetCurrentThreadCulture(RequestCulture requestCulture)
{
CultureInfo.CurrentCulture = requestCulture.Culture;
CultureInfo.CurrentUICulture = requestCulture.UICulture;
} private static CultureInfo? GetCultureInfo(
IList<StringSegment> cultureNames,
IList<CultureInfo> supportedCultures,
bool fallbackToParentCultures)
{
foreach (var cultureName in cultureNames)
{
if (cultureName != null)
{
// 里面通过递归查找支持的区域文化(包括回退的)
var cultureInfo = GetCultureInfo(cultureName, supportedCultures, fallbackToParentCultures, currentDepth: 0);
if (cultureInfo != null)
{
return cultureInfo;
}
}
} return null;
}
}

总结

通过以上内容,我们可以总结出以下核心知识点:

  • ASP.NET Core 提供了3种本地化器:

    • IStringLocalizerIStringLocalizer<>:文本本地化器,是最常用的,可以通过依赖注入获取,也可以通过IStringLocalizerFactory来获取。IStringLocalizer<>是对IStringLocalizer的一层包装。
    • IHtmlLocalizerIHtmlLocalizer<>:HTML本地化器,顾名思义,可以本地化HTML文本而不会对其编码。可以通过依赖注入获取,也可以通过IHtmlLocalizerFactory来获取。
    • IViewLocalizer:视图本地化器,用于前端视图的本地化。
  • 通过AddLocalization设置资源根目录,并注册本地化服务IStringLocalizer<>IStringLocalizerFactory

  • 通过AddDataAnnotationsLocalization注册数据注解本地化服务,主要是设置DataAnnotationLocalizerProvider委托

  • 通过AddViewLocalization注册视图本地化服务IViewLocalizerIHtmlLocalizer<>IHtmlLocalizerFactory

  • 通过UseRequestLocalization

    启用请求本地化中间件 RequestLocalizationMiddleware,它可以从请求中解析出当前请求的区域文化信息并设置到当前的处理线程中。

    • 通过AddSupportedCulturesAddSupportedUICultures配置受支持的 Cultures 和 UICultures
    • 通过SetDefaultCulture配置默认 Culture
    • 默认提供了三种 RequestCultureProvider:
      • QueryStringRequestCultureProvider:通过在 Query 中设置"culture"、"ui-culture"的值,例如 ?culture=zh-CN&ui-culture=zh-CN
      • CookieRequestCultureProvider:通过Cookie中设置名为 ".AspNetCore.Culture" Key 的值,值形如 c=zh-CN|uic=zh-CN
      • AcceptLanguageHeaderRequestCultureProvider:从请求头中设置 "Accept-Language" 的值
    • 通过AddInitialRequestCultureProvider添加自定义RequestCultureProvider,可以通过委托传入解析逻辑,也可以继承RequestCultureProvider抽象类来编写更复杂的逻辑。
  • 可以通过 Nuget 包My.Extensions.Localization.Json将资源文件(.resx)更换为 Json 文件。

问题

Only the invariant culture is supported in globalization-invariant mode.

报错显示:这个问题是由于.NET Core应用程序在全球化不变的模式下运行,而该模式只支持不变的文化,而不支持其他任何文化。

解决方法:

    将.csproj中的 <InvariantGlobalization>true</InvariantGlobalization>里面的内容改成false即可。

Asp .Net Core 系列:国际化多语言配置的更多相关文章

  1. asp.net core系列 28 EF模型配置(字段,构造函数,拥有实体类型)

    一. 支持字段 EF允许读取或写入字段而不是一个属性.在使用实体类时,用面向对象的封装来限制或增强应用程序代码对数据访问的语义时,这可能很有用.无法使用数据注释配置.除了约定,还可以使用Fluent ...

  2. asp.net core系列 29 EF模型配置(查询类型,关系数据库建模)

    一.查询类型 此功能是EF Core 2.1中的新功能. EF Core除了实体类型之外,EF Core模型还可以包含查询类型,这些查询类型是针对“未映射到实体类型”的数据获取.比如视图,或只读数据表 ...

  3. asp.net core系列 24 EF模型配置(主键,生成值,最大长度,并发标记)

    一.主键 键用作每个实体实例的主要唯一标识符. 使用关系数据库时,这会映射到主键的概念. 还可以配置不是主键的唯一标识符.按照约定,名为 Id 或 <type name>Id 的属性会配置 ...

  4. asp.net core系列 23 EF模型配置(概述, 类型和属性的包含与排除)

    一.模型配置概述 EF使用一组约定基于实体类的定义来构建模型. 可指定其他配置以补充或替代约定的内容.本系列介绍的配置可应用于面向任何数据存储的模型,以及面向任意关系数据库时可应用的配置. 数据库提供 ...

  5. asp.net core系列 27 EF模型配置(索引,备用键,继承)

    一.索引 索引是许多数据存储中的常见概念.虽然它们在数据存储中的实现可能会有所不同,但它们可用于更有效地基于列(或列集)进行查找.按照约定,用作外键每个属性 (或组的属性) 会自动创建索引.无法使用数 ...

  6. asp.net core系列 26 EF模型配置(实体关系)

    一.概述 EF实体关系定义了两个实体互相关联起来(主体实体和依赖实体的关系,对应数据库中主表和子表关系). 在关系型数据库中,这种表示是通过外键约束来体现.本篇主要讲一对多的关系.先了解下描述关系的术 ...

  7. asp.net core系列 25 EF模型配置(隐藏属性)

    一. 隐藏属性概述 隐藏属性也叫影子属性,该属性不是在.net实体类中定义的属性,而是在EFCore模型中为该实体类型定义的属性.这些属性的值和状态完全在变更跟踪器中维护.它有二个功能:(1)当数据库 ...

  8. 【目录】asp.net core系列篇

    随笔分类 - asp.net core系列篇 asp.net core系列 68 Filter管道过滤器 摘要: 一.概述 本篇详细了解一下asp.net core filters,filter叫&q ...

  9. asp.net core系列 40 Web 应用MVC 介绍与详细示例

    一. MVC介绍 MVC架构模式有助于实现关注点分离.视图和控制器均依赖于模型. 但是,模型既不依赖于视图,也不依赖于控制器. 这是分离的一个关键优势. 这种分离允许模型独立于可视化展示进行构建和测试 ...

  10. 技术的正宗与野路子 c#, AOP动态代理实现动态权限控制(一) 探索基于.NET下实现一句话木马之asmx篇 asp.net core 系列 9 环境(Development、Staging 、Production)

    黄衫女子的武功似乎与周芷若乃是一路,飘忽灵动,变幻无方,但举手抬足之间却是正而不邪,如说周芷若形似鬼魅,那黄衫女子便是态拟神仙. 这段描写出自<倚天屠龙记>第三十八回. “九阴神抓”本是& ...

随机推荐

  1. 可能是迄今为止最好用的WPF加载动画功能(没有之一)

    前言 当我们在开发应用程序时,用户体验往往是至关重要的一环.在应用程序加载大量数据或执行复杂操作时,为用户提供一个良好的加载体验变得至关重要.加载动画是其中一个有效的方式,它不仅能够告知用户应用程序正 ...

  2. 一个可以让你有更多时间摸鱼的WPF控件(二)

    前言 上文介绍了如何通过一个Form自定义控件来简化数据的录入,并自动实现数据校验,自动布局排列等功能.本文继续介绍如何优化表格控件的使用,缩减代码量,实现工作效率的提升. 一.功能实现 上文中分析了 ...

  3. 【已解决】启动Hmaster失败 master.HMaster: Unhandled exception. Starting shutdown.

  4. ubuntu 联网

    使用NAT

  5. 【WiFi开发全攻略】WIFI常用工具汇总

    [WiFi开发全攻略]WIFI常用工具汇总 本节主要介绍我们开发过程中,WiFi常用的开发工具,内容主要介绍工具种类以及基本的使用方法,更多使用可以见后面章节. 1.iwconfig iwconfig ...

  6. #min-max容斥#51nod 1355 斐波那契的最小公倍数

    题目 对于 \(n\leq 50000,a_i\leq 10^6\),求 \(\large lcm(fib(a_1),fib(a_2),\dots,fib(a_{n-1}),fib(a_n))\) 分 ...

  7. #矩阵乘法#洛谷 3702 [SDOI2017]序列计数

    题目链接 分析 考虑容斥,用总方案减去全是合数的方案数, 可以发现 \(n\) 很大,\(p\) 很小,直接用矩阵乘法转移即可 代码 #include <cstdio> #include ...

  8. #区间dp,离散#D 弱者对决

    分析 设\(dp[i][j][x]\)表示当前区间为\([i,j]\),最小值为\(x\)的最大总分, 状态转移方程可以用后缀最大值优化到\(O(n^3m)\),主要难点是输出方案 后缀最大值需要记录 ...

  9. Maven的build生命周期和常用plugin

    目录 简介 lifecycle和Phases Phases和Goals 常用plugin介绍 maven-dependency-plugin maven-jar-plugin 总结 简介 Maven和 ...

  10. SQL(Structured Query Language)简介和常见 SQL 命令示例

    简介 SQL(Structured Query Language)是一种用于访问和操作关系型数据库的标准语言.它是一个功能强大的语言,用于执行各种数据库操作,包括检索数据.插入新记录.更新记录.删除记 ...