Mocale.SourceGenerators 1.0.107-pre

Mocale

Localization framework for .NET Maui

Installation

The following packages are available via NuGet

<img src="assets/mocale_icon_light_rounded.png" width="100"> <img src="assets/mocale_icon_dark_rounded.png" width="100">

Package	NuGet
Mocale
Mocale.Cache.SQLite
Mocale.Providers.Azure.Blob
Mocale.Providers.GitHub.Raw
Mocale.SourceGenerators

Setup

Mocale is setup and configured in your MauiProgram.cs:

var builder = MauiApp.CreateBuilder();
builder
    .UseMauiApp<App>()
    .UseMocale(mocale =>
    {
      ...
    }

There are multiple configuration points to use with Mocale:

• Global
• Internal Provider
• External Provider
• Caching Provider

You must call WithConfiguration :

var builder = MauiApp.CreateBuilder();
builder
    .UseMauiApp<App>()
    .UseMocale(mocale =>
    {
        mocale.WithConfiguration(config =>
            {
                ...
            })

This method will provide the basic configuration of the library, the following configuration points are available:

If this method has not been called, an initialization exception will occur.

Internal Provider

Mocale ships with 2 internal providers, one for Resx and one for Json. Currently both providers are supported but if using external providers it is recommended to use Json because i haven't fully implemented Resx with external providers or the source generators yet.

Internal providers provide the solid foundation for your localizations. These use files that are bundled with the app and can be load immediately

Embedded Resource Provider

This will use Json to load localizations that have been registered as an EmbeddedResource:

<ItemGroup>
  <EmbeddedResource Include="Resources\Locales\*.json" />
</ItemGroup>

var builder = MauiApp.CreateBuilder();
builder
    .UseMauiApp<App>()
    .UseMocale(mocale =>
    {
        mocale.WithConfiguration(config =>
            {
                ...
            })
            .UseEmbeddedResources(config =>
            {
                config.ResourcesPath = "Locales";
                config.ResourcesAssembly = typeof(App).Assembly;
            });
    })

The following config is available:

The format of these files should be a keyvalue pair of strings in json format:

{
  "CurrentLocaleName": "English",
  "LocalizationCurrentProviderIs": "The current localization provider is:",
  "LocalizationProviderName": "Json",
  "MocaleDescription": "Localization framework for .NET Maui",
  "MocaleTitle": "Mocale"
}

App Resources Provider

This will use local app resources (resx) to provide the internal localizations.

var builder = MauiApp.CreateBuilder();
builder
    .UseMauiApp<App>()
    .UseMocale(mocale =>
    {
        mocale.WithConfiguration(config =>
            {
                ...
            })
            .UseAppResources(config =>
            {
               config.AppResourcesType = typeof(AppResources);
            });
    })

The following config is available:

External Provider

External providers allow you to update localizations without recompiling your app. This is really powerful for multiple reasons:

• Fix mistakes made in QA for spelling
• Update text and resources based on business requirements

Currently only a single external provider can be used but it is a roadmap item to be able to use multiple providers where the need arises.

By design external providers are considered risky and they will only be considered a source of truth if they return values. The caching layer of the library will persist any data pulled from these providers and whilst the app is within the window of cache only the local data will be used.

There is currently only 1 implemented external provider and its implementation is not extremely robust (missing features such as auth) but I plan to develop these over time. It is also intended for you to create your own external providers based on your specific requirements. If the provider is generic enough I would implore you to contribute it back to this library, equally if it is business specific then you can manage it internally.

Azure Blob Storage Provider

This provider will search for resource in Blob Storage.

var builder = MauiApp.CreateBuilder();
builder
    .UseMauiApp<App>()
    .UseMocale(mocale =>
    {
        mocale.WithConfiguration(config =>
            {
                ...
            })
            .UseBlobStorage(config =>
            {
                config.BlobContainerUri = new Uri("https://azurestorage/mocale/");
                config.RequiresAuthentication = false;
                config.CheckForFile = true;
            });
    })

Currently this provider only works for public facing blob files, I intend to allow authentication for privately hosted files.

The following configuration is available:

Caching Provider

There is currently one caching provider Mocale.Cache.SQLite, this provides a cache layer for Mocale using a SQLite database.

Install Mocale.Cache.SQLite package into your project and in the MocaleBuilder register the provider:

var builder = MauiApp.CreateBuilder();
builder
    .UseMauiApp<App>()
    .UseMocale(mocale =>
    {
        mocale.WithConfiguration(config =>
            {
                ...
            })
            .UseSqliteCache(config =>
            {
                config.UpdateInterval = TimeSpan.FromDays(7);
            })
    })

The following config is available:

The database name and location is not configurable, it will create its own database named Mocale.db under the FileSystem.AppDataDirectory path.

Currently there is no in memory package and if you run Mocale without referencing this package it will not function because not all of the required classes for normal lib function have been implemented in the main assembly.

This is a roadmap item to not have consumers depend on the SQLite package.

Usage

Once registered using the host builder, the library will automatically initialise using the given config.

Xaml

Reference mocale as an xml namespace:

xmlns:mocale="http://axemasta.com/schemas/2022/mocale"
xmlns:keys="clr-namespace:Mocale.Translations"

Note keys will be generated in the namespace Mocale.Translations, but they will be included within your apps assembly, therefore an assembly reference is not required.

Use the provided markup extension:

<Label Text="{mocale:Localize MocaleDescription}" />
<Label Text="{mocale:Localize Key={x:Static keys:TranslationKeys.MocaleDescription}}" />

Provide an IValueConverter:

<Label Text="{mocale:Localize Key=CurrentLocaleName, Converter={StaticResource LanguageEmojiConverter}}" />
<Label Text="{mocale:Localize Key={x:Static keys:TranslationKeys.CurrentLocaleName}, Converter={StaticResource LanguageEmojiConverter}}" />

Codebehind / ViewModel

Translations

I will be updating this to provide a more testable way to retrieve translations in the viewmodel layer

In your class add ITranslatorManager:

private readonly ITranslatorManager translatorManager;

public MyViewModel(ITranslatorManager translatorManager)
{
	this.translatorManager = translatorManager;
}

Use the methods provided to translate:

private void DoSomething()
{
	var appTitle = translatorManager.Translate("AppTitle");
}

Change Culture

In your class add ILocalizationManager:

private readonly ILocalizationManager localizationManager;

public MyViewModel(ILocalizationManager localizationManager)
{
	this.localizationManager = localizationManager;
}

Call SetCultureAsync to attempt to change culture:

private async Task ChangeCultureToFrench()
{
	var french = new CultureInfo("fr-FR");
	
	var changed = await localizationManager.SetCultureAsync(french);
	
	Console.WriteLine($"Changed to french: {changed}");
}

Source Generators

The Mocale.SourceGenerators package provides some extra useful features for develepment.

When installed this package will automatically generate a translations key constants file for you, this is essentially the same as the Resx designer file. This allows you to have strong typings for your translation keys which will be valuable for cases such as removing a resource key, normally this key would be orphaned in your code and wouldn't be an issue until runtime, now if you have a reference through code, removing it will cause your compile to fail.

Source generators are only compatible with Json localizations, Resx already have designer files you can reference.

To get this source generator to work:

• Reference all your Locale Json files as C# Analyzer Additional Files:

  <ItemGroup>
    <AdditionalFiles Include="Resources\Locales\*.json" />
  </ItemGroup>
  

• Build solution (to run the generator)

• A new class named TranslationKeys will be generated under the namespace of the assembly referencing the generator.

The generated class will look similar to:

// <auto-generated/>
namespace Mocale.Translations;

public static class TranslationKeys
{
	/// <summary>
	/// Looks up a localized string using key KeyOne.
	/// </summary>
	public const string KeyOne = "KeyOne";


	/// <summary>
	/// Looks up a localized string using key KeyTwo.
	/// </summary>
	public const string KeyTwo = "KeyTwo";
}

The generated properties will be Pascal cased and have illegal c# characters sanitized. The values will be unaltered and will be able to use as keys for the localizations.

The namespace for the constants is equal to the assembly name referencing the generator:

• Acme.MauiApp references Mocale.SourceGenerators
• The following class will be created: Acme.MauiApp.TranslationKeys

You can use these classes in Xaml or C# to perform translations:

Xaml:

<Label Text="{mocale:Localize Key={x:Static keys:TranslationKeys.LabelTitle}}"/>

C#:

var labelTitle = translationManager.Translate(TranslationKeys.LabelTitle);

Feature Goals

These are features not yet currently in Mocale which I intend to add in the near future, mainly because I will be needing them. Feel free to raise a PR if I haven't got around to implementing them 😄

• String formatting
  • Stretch: Definable format criteria aka not just "Replace {0} and {1}" but for complicated strings like "Replace {value} and {name}"
• Support for different types of locale file (aka resx, json), currently json is assumed
• Support for multiple external providers
• Add a more MVVM friendly mechanism to resolve translations (such as a ITranslationProvider where you request a number of keys & get localizations back)
• Resolve translation keys within the mocale XmlnsDefinition, I did try this but couldn't get it working.