本地化

本地化是为给定语言和地区定制应用程序的过程。BootstrapBlazor 组件允许您将其 UI 元素转换为所需的语言。这包括按钮、过滤器操作符属性等文本。组件内部默认使用当前请求 UI 文化语言,本文将向您展示如何在应用程序中使用此功能:

本地化在组件中的工作原理

BootstrapBlazor 组件额外支持使用 Json 类型的键值信息作为资源文件,将其解析为 UI 中呈现的字符串。BootstrapBalzor 包自带以下资源文件。
  • 中文(zh)
  • 英语(en)
  • 德语(de)
  • 葡萄牙语(pu)
组件内置本地化语言回退机制,如请求文化为 zh-CN 时,如未提供相对应的文化资源文件时,内置逻辑通过父级文化进行尝试本地化,以 zh-CN 为例回退机制如下:zh-CNzh
如果设置的本地化语言未提供资源文件回落后仍无法找到资源文件后,使用 FallbackCulture 参数设置的文化信息进行本地化,默认为 en
特别注意:
由于某些系统如 Centos Ubuntu mac 等程序运行后线程无法获得文化信息,可以通过配置文件设置默认文化信息:

{
  "BootstrapBlazorOptions": {
    "DefaultCultureInfo": "en"
  }
}

开启本地化功能

Server-Side App

1. 配置文件

通过 FallbackCultureName 设置回退文化信息,即未找到当前请求的文化信息时使用此配置文化,通过 SupportedCultures 设置支持的文化集合

{
  "BootstrapBlazorOptions": {
    "FallbackCultureName": "en",
    "SupportedCultures": [
      "zh-CN",
      "en-US"
    ]
  }
}

2. 启用 .NET 核心本地化服务

builder.Services.AddRazorPages();
builder.Services.AddServerSideBlazor();

// 增加 Bootstrap Blazor 组件
builder.Services.AddBootstrapBlazor();

// 增加多语言支持配置信息
builder.Services.AddRequestLocalization<IOptionsMonitor<BootstrapBlazorOptions>>((localizerOption, blazorOption)=>
{
    blazorOption.OnChange(op => Invoke(op));
    Invoke(blazorOption.CurrentValue);

    void Invoke(BootstrapBlazorOptions option)
    {
        var supportedCultures = option.GetSupportedCultures();
        localizerOption.SupportedCultures = supportedCultures;
        localizerOption.SupportedUICultures = supportedCultures;
    }
});

var app = builder.Build();

// 启用本地化
var option = app.Services.GetService<IOptions<RequestLocalizationOptions>>();
if (option != null)
{
    app.UseRequestLocalization(option.Value);
}
public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        // 增加 BootstrapBlazor 组件
        services.AddBootstrapBlazor();

        // 增加本地化服务配置信息
        services.AddRequestLocalization<IOptions<BootstrapBlazorOptions>>((localizerOption, blazorOption) =>
        {
            var supportedCultures = blazorOption.Value.GetSupportedCultures();

            localizerOption.SupportedCultures = supportedCultures;
            localizerOption.SupportedUICultures = supportedCultures;
        });
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        // 启用本地化中间件并设置支持的文化信息
        app.UseRequestLocalization(app.ApplicationServices.GetService<IOptions<RequestLocalizationOptions>>()!.Value);
    }
}

3. 实现 UI 本地化信息存储(例如,cookie)

[Route("[controller]/[action]")]
public class CultureController : Controller
{
    public IActionResult SetCulture(string culture, string redirectUri)
    {
        if (!string.IsNullOrEmpty(culture))
        {
            HttpContext.Response.Cookies.Append(
                CookieRequestCultureProvider.DefaultCookieName,
                CookieRequestCultureProvider.MakeCookieValue(new RequestCulture(culture, culture)));
        }

        return LocalRedirect(redirectUri);
    }

    public IActionResult ResetCulture(string redirectUri)
    {
        HttpContext.Response.Cookies.Delete(CookieRequestCultureProvider.DefaultCookieName);

        return LocalRedirect(redirectUri);
    }
}

3. 添加允许用户更改本地化的 UI

@inherits BootstrapComponentBase
@inject IOptions<BootstrapBlazorOptions> BootstrapOptions
@inject NavigationManager NavigationManager
@inject ICultureStorage CultureStorage

<div @attributes="@AdditionalAttributes" class="@ClassString">
    <label>请选择语言:</label>
    <Select Value="@SelectedCulture" OnSelectedItemChanged="@SetCulture">
        <Options>
            @foreach (var kv in Configuration.GetSupportCultures())
            {
                <SelectOption Text="@kv.Key" Value="@kv.Value" />
            }
        </Options>
    </Select>
</div>

@code {
    private string? ClassString => CssBuilder.Default("culture-selector")
        .AddClassFromAttributes(AdditionalAttributes)
        .Build();

    private string SelectedCulture { get; set; } = CultureInfo.CurrentUICulture.Name;

    private async Task SetCulture(SelectedItem item)
    {
        if (CultureStorage.Mode == CultureStorageMode.Webapi)
        {
            // 使用 api 方式 适用于 Server-Side 模式
            if (SelectedCulture != item.Value)
            {
                var culture = item.Value;
                var uri = new Uri(NavigationManager.Uri).GetComponents(UriComponents.PathAndQuery, UriFormat.Unescaped);
                var query = $"?culture={Uri.EscapeDataString(culture)}&redirectUri={Uri.EscapeDataString(uri)}";

                // use a path that matches your culture redirect controller from the previous steps
                NavigationManager.NavigateTo("/Culture/SetCulture" + query, forceLoad: true);
            }
        }
        else
        {
            var cultureName = item.Value;
            if (cultureName != CultureInfo.CurrentCulture.Name)
            {
                await JSRuntime.InvokeAsync<string>(identifier: "$.blazorCulture.set", cultureName);
                var culture = new CultureInfo(cultureName);
                CultureInfo.CurrentCulture = culture;
                CultureInfo.CurrentUICulture = culture;

                NavigationManager.NavigateTo(NavigationManager.Uri, forceLoad: true);
            }
        }
    }
}

4. 附加 Json 资源文件

BootstrapBlazor 组件库即支持微软默认的 resx 格式资源,也支持嵌入式 json 格式资源,以及特定物理 json 文件

资源文件为合并关系,寻址规则优先级为
  • 微软 resx 嵌入式资源文件
  • 外置 json 物理文件
  • json 嵌入式资源文件
  • 内置 json 资源文件

public void ConfigureServices(IServiceCollection services)
{
    services.AddBootstrapBlazor(null, options =>
    {
        // 忽略文化信息丢失日志
        options.IgnoreLocalizerMissing = true;

        // 设置 RESX 格式多语言资源文件 如 Program.{CultureName}.resx
        options.ResourceManagerStringLocalizerType = typeof(Program);

        // 设置 Json 格式嵌入式资源文件
        options.AdditionalJsonAssemblies = new[] { typeof(BootstrapBlazor.Shared.App).Assembly };

        // 设置 Json 物理路径文件
        options.AdditionalJsonFiles = new string[]
        {
            @"D:\Argo\src\BootstrapBlazor\src\BootstrapBlazor.Server\Locales\zh-TW.json",
            @"D:\Argo\src\BootstrapBlazor\src\BootstrapBlazor.Server\Locales\zh-CN.json"
        };
    });
}

或者使用服务扩展方法 ConfigureJsonLocalizationOptions

public void ConfigureServices(IServiceCollection services)
{
    services.AddBootstrapBlazor();
    services.ConfigureJsonLocalizationOptions(options =>
    {
        // 忽略本地化键值文化信息丢失
        options.IgnoreLocalizerMissing = true;

        // 附加自己的 json 多语言文化资源文件 如 zh-TW.json
        options.AdditionalJsonAssemblies = new Assembly[]
        {
            typeof(BootstrapBlazor.Shared.App).Assembly,
        };

        // 设置 Json 物理路径文件
        options.AdditionalJsonFiles = new string[]
        {
            @"D:\Argo\src\BootstrapBlazor\src\BootstrapBlazor.Server\Locales\zh-TW.json",
            @"D:\Argo\src\BootstrapBlazor\src\BootstrapBlazor.Server\Locales\zh-CN.json"
        };
    });
}

Web Assembly

1. 启用 .NET 核心本地化服务

public static async Task Main(string[] args)
{
    var builder = WebAssemblyHostBuilder.CreateDefault(args);

    builder.RootComponents.Add<App>("app");

    builder.Services.AddTransient(sp => new HttpClient { BaseAddress = new Uri(builder.HostEnvironment.BaseAddress) });

    // 增加 BootstrapBlazor 组件
    builder.Services.AddBootstrapBlazor();

    builder.Services.AddSingleton<ICultureStorage, DefaultCultureStorage>();

    // 增加本地化
    builder.Services.Configure<BootstrapBlazorOptions>(op =>
    {
        op.ToastDelay = 4000;
        op.SupportedCultures = new List<string> { "zh-CN", "en-US" };
    });

    var host = builder.Build();

    await GetCultureAsync(host);

    await host.RunAsync();
}

private static async Task GetCultureAsync(WebAssemblyHost host)
{
    var jsRuntime = host.Services.GetRequiredService<IJSRuntime>();
    var cultureName = await jsRuntime.InvokeAsync<string>("$.blazorCulture.get") ?? "zh-CN";
    var culture = new CultureInfo(cultureName);
    CultureInfo.DefaultThreadCurrentCulture = culture;
    CultureInfo.DefaultThreadCurrentUICulture = culture;
}

internal class DefaultCultureStorage : ICultureStorage
{
    public CultureStorageMode Mode { get; set; } = CultureStorageMode.LocalStorage;
}

2. 实现 UI 本地化信息存储(例如,localStorage)

与 Server-Side 一致

更改默认语言设置

public static async Task Main(string[] args)
{
    // 设置默认文化为 zh-CN
    CultureInfo.CurrentCulture = new CultureInfo("zh-CN");
    CultureInfo.CurrentUICulture = new CultureInfo("zh-CN");

    // ...

    var host = builder.Build();

    await GetCultureAsync(host);

    await host.RunAsync();
}

配置是否显示缺失本地化资源信息

"BootstrapBlazorOptions": {
    "IgnoreLocalizerMissing": true
}
var builder = WebApplication.CreateBuilder(args);

// 增加 BootstrapBlazor 服务
builder.Services.AddBootstrapBlazor(null, options =>
{
    // 忽略本地化键值文化信息丢失
    options.IgnoreLocalizerMissing = true;
});

B 站相关视频链接

Themes
Bootstrap
Motronic
Ant Design (完善中)
LayUI (完善中)
An error has occurred. This application may no longer respond until reloaded. Reload
Seems like the connection with the server has been lost. It can be due to poor or broken network. Please hang on while we're trying to reconnect...
Oh snap! Failed to reconnect with the server. This is typically caused by a longer network outage, or if the server has been taken down. You can try to reconnect, but if that does not work, you need to reload the page.
Oh man! The server rejected the attempt to reconnect. The only option now is to reload the page, but be prepared that it won't work, since this is typically caused by a failure on the server.
Bootstrap Blazor 组件库 更新到 6.6.0

首先感谢您对本套组件的关注,本目前本套组件已经拥有超过 120 个组件,本组件是基于 Bootstrap 风格的 Blazor 企业级组件库,提供如布局、导航、表单、数据、通知、图标、语音等几大类通用组件,每一个组件都经过静心设计,具有模块化、响应式和优秀的性能。从更多实际场景出发,满足多种场景的需求,极大的减少开发者时间成本,大大缩短开发周期,大幅提高开发效率,并提供了一套 通用权限管理系统 示例工程。Bootstrap Blazor 产品是由一支专业的全职技术团队进行维护,高效的响应速度,多元化的解决方案,长期提供支持,并提供企业级支持。目前已在多家知名国企内部使用,项目最高在线 1200 人稳定运行。右侧为国内人数最多的中文 Blazor QQ 社区二维码,欢迎扫描加群。

组件更新到 6.6.0 更新日志 [传送门] 如果组件给您带来了方便,请您帮忙给项目点亮 Star github gitee

QQGroup
QQ 795206915