Toolbelt.Blazor.I18nText

Create an i18ntext folder in your project root. Inside, add localized text source files for each language using either JSON or CSV formats.

Requirements:

• Files must be encoded in UTF-8.
• JSON format: Must be a simple key-value object.
• CSV format: Must be a 2-column file without a header row.

Naming Convention: The filename must follow the pattern: <Text Table Name>.<Language Code>.{json|csv}.

Example: For a Text Table named MyText in English, use MyText.en.json or MyText.en.csv.

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

Key1,Localized text 1
Key2,Localized text 2

Add the Toolbelt.Blazor.I18nText NuGet package to your Blazor app project to enable localized text support using JSON or CSV files.

dotnet add package Toolbelt.Blazor.I18nText

To use localized text in a .razor component:

1. Inject the Toolbelt.Blazor.I18nText.I18nText service.
2. Declare a field for your generated Text Table class (e.g., MyText). Note that the namespace is <your_project_namespace>.I18nText.
3. In OnInitializedAsync, call GetTextTableAsync<T>(this) to populate the table.
4. Access text via properties (for IntelliSense) or the indexer (for dynamic keys).

@inject Toolbelt.Blazor.I18nText.I18nText I18nText

<h1>@MyText.HelloWorld</h1>
<p>@MyText["DynamicKey"]</p>

@code {
    private I18nText.MyText MyText = new();

    protected override async Task OnInitializedAsync()
    {
        MyText = await I18nText.GetTextTableAsync<I18nText.MyText>(this);
    }
}

The library uses a C# source generator to create a "Typed Text Table class" based on your source files.

• Visual Studio IDE: The source generator works automatically in the background; you usually do not need to build explicitly.
• dotnet CLI: Use dotnet watch to automatically recompile the source generator whenever you update your .json or .csv files.

dotnet watch

You can customize the namespace used for the generated Text Table classes by defining the <I18nTextNamespace> MSBuild property in your project file (.csproj).

<PropertyGroup>
  <I18nTextNamespace>MyCustomNamespace</I18nTextNamespace>
</PropertyGroup>

The fallback language is determined at compile time. By default, the fallback language is set to en. To use a different language as the fallback, add the <I18nTextFallBackLanguage> MSBuild property to your project file (.csproj) and set it to your desired language code.

<PropertyGroup>
  <I18nTextFallBackLanguage>fr</I18nTextFallBackLanguage>
</PropertyGroup>

The I18nText service (namespace Toolbelt.Blazor.I18nText) is the primary interface for managing the application's current language.

• GetCurrentLanguageAsync(): Returns the current language code (e.g., detected from browser settings or previously set via SetCurrentLanguageAsync).
• SetCurrentLanguageAsync(string langCode): Changes the current language code. By default, this value is stored in the browser's session storage so it can be restored when the app is reloaded.
• ChangeLanguage: An event (EventHandler<I18nTextChangeLanguageEventArgs>) that is invoked after the language has changed, but before the component state has updated.

// Example: Changing language in a component
await i18nText.SetCurrentLanguageAsync("fr-FR");

// Example: Getting current language
string currentLang = await i18nText.GetCurrentLanguageAsync();

To use the internationalization features in your Blazor application, you must register the I18nText service into the .NET Core Dependency Injection (DI) system using the AddI18nText() extension method. You can optionally provide an Action<I18nTextOptions> to customize the service behavior during registration.

// Register with default configuration
services.AddI18nText();

// Register with custom configuration
services.AddI18nText(options => {
    // Customize options here
});

To access your localized strings, use the GetTextTableAsync<T>(ComponentBase component) method.

• Type Parameter T: This must be the class auto-generated from your localized text source files during the build process.
• Automatic Refresh: When you call SetCurrentLanguageAsync(...), the I18nText service automatically calls StateHasChanged() on the component passed as the first argument. This ensures the UI refreshes immediately with the new language's text.

Fields within the returned T object are populated from the JSON resource file corresponding to the current language code.

// Inside a Blazor component
protected override async Task OnInitializedAsync() 
{
    // T is your auto-generated class
    textTable = await I18nText.GetTextTableAsync<MyTextTable>(this);
}

// In the markup
<p>@textTable.WelcomeMessage</p>