Setup

Install

The following packages are available on NuGet:

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

The following packages MUST be installed:

• Mocale
• Mocale.Cache.SQLite

Currently there is only 1 cache provider and there is no default in memory cache provider therefore the sqlite cache is mandatory.

It is recommended to install the Mocale.SourceGenerators package if you are using Json resources.

If you want to use the external provider functionality, install the corresponding package for your external storage solution.

Host Builder

Use the host builder extension in your MauiProgram.cs:

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

Configure MocaleBuilder

The host builder extension provides a MocaleBuilder which can be used to configure the library. There are a number of builder extensions which you can call, depending on the features you wish to use some setup calls are mandatory.

WithConfiguration

This is the general config for Mocale, the following properties are available:

DefaultCulture

The culture to treat as the default, this value will be used when your Maui app loads and will be displayed in the app until this locale is changed in code.

ShowMissingKeys

Whether translation keys should be displayed in the app when the corresponding value could not be found.

var translation = translationManager.Translate("ThisKeyDoesntExist");

// translation = "$ThisKeyDoesntExist";

Value	Returns
true	translation key, formatted with NotFoundSymbol
false	empty string

NotFoundSymbol

If ShowMissingKeys is true, this value will be used to format the missing key

// NotFoundSymbol = "££"

var translation = translationManager.Translate("ThisKeyDoesntExist");

// translation = "££ThisKeyDoesntExist££";

UseExternalProvider

Whether to use an external localization provider. This value defaults to true and Mocale expects you to install and configure an external provider. If you don't wish to use this functionality, set this value to false and only the local provider will be used.

SaveCultureChanged

When the localization culture changes, whether this change should be persisted.

Value	Returns
true	When locales change, this value is saved & subsequent sessions will use this culture
false	The default culture is always loaded at app startup

UseEmbeddedResources (Local Json Provider)

This method registers the local localization provider for Json files.

If you are using local json files, install the source generator so that translation keys are source generated.

The embedded resource provider scans for json files in your app assembly registered as EmbeddedResource. The recommended folder for these files is within the Maui Resources folder, by default the subfolder Locales is used, this can be configured.

It is recommended to add the following csproj ItemGroup:

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

Files in this directory should be named according to their language & regions ISO 639-1 language codes:

For example:

• en-GB.json
• en-US.json
• fr-FR.json

UseAppResources (Local Resx Provider)

This method registers the local localization provider for Resx files.

TODO