Toolbelt.Blazor.I18nText 12.0.0-preview.1.10

.NET 5.0 .NET Standard 2.0
This is a prerelease version of Toolbelt.Blazor.I18nText.
Install-Package Toolbelt.Blazor.I18nText -Version 12.0.0-preview.1.10
dotnet add package Toolbelt.Blazor.I18nText --version 12.0.0-preview.1.10
<PackageReference Include="Toolbelt.Blazor.I18nText" Version="12.0.0-preview.1.10" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Toolbelt.Blazor.I18nText --version 12.0.0-preview.1.10
The NuGet Team does not provide support for this client. Please contact its maintainers for support.
#r "nuget: Toolbelt.Blazor.I18nText, 12.0.0-preview.1.10"
#r directive can be used in F# Interactive, C# scripting and .NET Interactive. Copy this into the interactive tool or source code of the script to reference the package.
// Install Toolbelt.Blazor.I18nText as a Cake Addin
#addin nuget:?package=Toolbelt.Blazor.I18nText&version=12.0.0-preview.1.10&prerelease

// Install Toolbelt.Blazor.I18nText as a Cake Tool
#tool nuget:?package=Toolbelt.Blazor.I18nText&version=12.0.0-preview.1.10&prerelease
The NuGet Team does not provide support for this client. Please contact its maintainers for support.

Blazor Internationalization(I18n) Text NuGet Package

📝 Summary

This package is another way to localize text in your Blazor Web App!

movie.1

🎁 Features

  • Both Blazor Server and WebAssembly are supported.
  • In Blazor Wasm, it works even on a static web host. (The ASP.NET Core host isn't required)
  • Only needs plain text editor - no need for .resx
  • Static Typing - IntelliSense, Code Hint...
  • It supports Blazor components libraries. You can create NuGet packages of your libraries that are localized with "Blazor I18nText".

📢 Notice

Blazor WebAssembly has started localization support officially since v.3.2 preview 4. It is based on .NET Standard IStringLocalizer and satellite assemblies with .resx.

However, I will continue to develop and maintain this package, because this package still has some advantages over .NET standard implementation.

pros/cons

Supported versions

.NET Ver. Blazor I18n Text Ver.
v.6.0, 7.0 v.12 (Recommended), v.11
v.5.0 v.12 (Recommended), v.11, v.10, v.9
v.3.x v.12 (Recommended), v.11, v.10, v.9

🚀 Quick Start

Step.1 - Add Package

Add Toolbelt.Blazor.I18nText NuGet package to your Blazor app project, like this.

$ dotnet add package Toolbelt.Blazor.I18nText

Step.2 - Create localized text source files as JSON or CSV

Add localized text source files for each language in an i18ntext folder under the project folder.

The localized text source files must be simple key-value only JSON file, like in the example below:

{
  "Key1": "Localized text 1",
  "Key2": "Localized text 2",
  ...
}

or, 2 columns only CSV file without header row like a bellow example.

Key1,Localized text 1
Key2,Localized text 2

⚠️NOTICE - The encoding of the CSV and JSON file must be in UTF-8.

And, the naming rule of localized text source files must be the following:

<Text Table Name>.<Language Code>.{json|csv}

fig.1

Step.3 - Build the project whenever localized text source files are created or updated.

Basically, after creating or updating those localized text source files, you have to build your Blazor app project.(*-1)

After that, "Typed Text Table class" C# source code will be generated by the C# "source generator" feature.

And also, "Localized Text Resource JSON" files will be generated in the output folder.

fig.2

(*-1) Note 1 - for Visual Studio IDE users:
On Visual Studio IDE, the source generator will work automatically in a background process.

Therefore, Visual Studio IDE users are usually not needed to build the project explicitly.

Localized text source files (.json or .csv) are recompiled into "Typed Text Table class" and "Localized Text Resource JSON" files automatically whenever users change and save them.

(*-1) Note 2 - for dotnet CLI users:
When you are developing on dotnet CLI and want to recompile localized text source files automatically whenever those localized text source files (.json or .csv) are changed, you can use the dotnet watch command.

$ dotnet watch

After entering that dotnet CLI command, the command window will stay in execution mode and watch localized text source files changing.

When that dotnet CLI detects localized text source files changing, the dotnet CLI will recompile localized text source files into "Typed Text Table class" and "Localized Text Resource JSON" files.

fig.2-2

⚠️NOTICE - The source generator for Blazor I18n Text is enabled on .NET 6 or later and Blazor I18n Text ver.12 or later only.
For more details on previous versions and platforms, please see the following link.

Step.4 - Configure your app to use I18nText service

Edit the "Program.cs" file to register "I18nText" service, like this.

// in your Program.cs
using Toolbelt.Blazor.Extensions.DependencyInjection; // 👈 Add this, and...
...
var builder = WebAssemblyHostBuilder.CreateDefault(args);
...
builder.Services.AddI18nText();  // 👈 Add this.
...

Step.5 - Get the "Text Table" object in your Blazor component

Open your Blazor component file (.razor) inside any editor, and do the following:

  1. Inject Toolbelt.Blazor.I18nText.I18nText service into the component.
@inject Toolbelt.Blazor.I18nText.I18nText I18nText
  1. Add a field of the Text Table class generated from localized text source files, and assign the default instance.
@code {
  I18nText.MyText MyText = new I18nText.MyText();

Note: The namespace of the Text Table class is <default namespace of your Blazor project> + "I18nText".

  1. Override OnInitiallizedAsync() method of the Blazor component, and assign a Text Table object that's a return value of GetTextTableAsync<T>() method of I18nText service instance to the Text Table field.
protected override async Task OnInitializedAsync()
{
  MyText = await I18nText.GetTextTableAsync<I18nText.MyText>(this);

fig.4

Step.6 - Use the Text Table

After doing these steps, you can reference a field of the Text Table object to get localized text.

If you are using Visual Studio in Windows OS and Blazor extensions are installed in that Visual Studio, you can get "IntelliSense" and "Document comment" support.

movie.2

Note: Text Table object allows you to get localized text by key string dynamically, with indexer syntax, like this.

<h1>@MyText["HelloWorld"]</h1>

If you make some mistakes that typo of key string, it will just return the key string as is without any runtime exceptions.

Step.7 - Run it!

Build and run your Blazor app.

The I18nText service detects the language settings of the Web browser, and reads the localized text resource JSON which is most suitable for the language detected.

fig.5

More information for Blazor server app

I recommend enabling "Request Localization" middleware inside Blazor server app, like this:

// in the Startup class
...
public void ConfigureServices(IServiceCollection services)
{
  services.Configure<RequestLocalizationOptions>(options => {
    var supportedCultures = new[] { "en", "ja" };
    options.DefaultRequestCulture = new RequestCulture("en");
    options.AddSupportedCultures(supportedCultures);
    options.AddSupportedUICultures(supportedCultures);
  });
  ...

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
  app.UseRequestLocalization();
  ...

This code makes the result of server-side pre-rendering to be suitable for "Accept-Language" header value in a request from clients.

📌 Limitations

The following features are not supported in this version of I18Text library.

  • Integration with ASP.NET Core localization (IStringLocalizer<T> support)
  • Localize validation message
  • Plural form support
  • Text formatting by placeholder.
  • Integration with System.Globalization.Culture.CurrentUICulture.

The following features will not be supported forever, because these features are not the scope of this library, I think.

  • Formatting of date, time, currency. (These features will be provided by System.Globalization.Culture.)

⚙️ Configuration

🛠️ API Reference

Please see also "API Reference" on GitHub.

🎉 Release Notes

Release notes are here.

📢 Licence & Third Party Notice

Product Versions
.NET net5.0 net5.0-windows net6.0 net6.0-android net6.0-ios net6.0-maccatalyst net6.0-macos net6.0-tvos net6.0-windows
.NET Core netcoreapp2.0 netcoreapp2.1 netcoreapp2.2 netcoreapp3.0 netcoreapp3.1
.NET Standard netstandard2.0 netstandard2.1
.NET Framework net461 net462 net463 net47 net471 net472 net48
MonoAndroid monoandroid
MonoMac monomac
MonoTouch monotouch
Tizen tizen40 tizen60
Xamarin.iOS xamarinios
Xamarin.Mac xamarinmac
Xamarin.TVOS xamarintvos
Xamarin.WatchOS xamarinwatchos
Compatible target framework(s)
Additional computed target framework(s)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (2)

Showing the top 2 NuGet packages that depend on Toolbelt.Blazor.I18nText:

Package Downloads
Densen.Extensions.BootstrapBlazor

Densen Blazor组件库以及BootstrapBlazor服务扩展包

Toolbelt.Blazor.I18nText.StringLocalizerSupport

This NuGet package allows you to localize your Blazor app even validation messages based on .NET Core localization infrastructure such as "IStringLocalizer".

GitHub repositories (1)

Showing the top 1 popular GitHub repositories that depend on Toolbelt.Blazor.I18nText:

Repository Stars
csharpfritz/csharp_with_csharpfritz
Show notes, slides, and samples from the CSharp with CSharpFritz show
Version Downloads Last updated
12.0.0-preview.1.10 591 3/27/2022
11.1.4 1,389 3/23/2022
11.1.3 1,095 2/5/2022
11.1.2 202 1/30/2022
11.1.1 90 1/27/2022
11.1.0 87 1/26/2022
11.0.0 2,182 11/11/2021
11.0.0-preview.2 429 10/9/2021
11.0.0-preview.1 287 8/21/2021
10.0.0-preview.1 407 8/16/2021
9.4.1 2,709 8/14/2021
9.4.1-preview.1.3 317 5/16/2021
9.4.0 7,719 1/15/2021
9.3.1 1,178 11/29/2020
9.3.0 4,147 9/14/2020
9.2.0 12,757 8/5/2020
9.1.1 3,683 6/18/2020
9.1.0 506 6/11/2020
9.0.1.1 3,331 4/26/2020
9.0.1 6,362 4/6/2020
9.0.0.3 2,389 3/14/2020
8.0.0.2-beta 751 2/14/2020
7.1.0 6,855 1/9/2020
7.0.1.1 4,033 10/9/2019
7.0.0.17 738 10/3/2019
6.0.0 1,262 9/5/2019
5.0.0.19 552 8/18/2019
4.0.0 964 7/27/2019
3.0.0.7 700 6/17/2019
2.0.0 469 5/1/2019
1.0.0.49 436 3/21/2019

v.12.0.0
- Improve: introduce the custom C# source generator instead of the legacy MSBuild custom task for compiling localized source texts into typed files and resource json files.