[Proposal]: Localization with Fluent C# and XAML Support

[stephenquan]

There have been several previous discussions, proposals, and pull requests exploring localization support within the CommunityToolkit ecosystem:

• Previous .NET MAUI CommunityToolkit issue: Localization classes migration #6
• Current .NET CommunityToolkit issue: [Proposal] LocalizationResourceManager dotnet#312
• Initial .NET MAUI CommunityToolkit implementation: Localization #7
• Updated implementation: PR LocalizationResourceManager #93 #441
• .NET MAUI Community Toolkit Monthly Standup (June 2022): https://www.youtube.com/watch?v=t3g_NrQfE8g

I'd like to revisit localization support for the .NET MAUI CommunityToolkit, this time focusing on .NET MAUI-specific capabilities such as Fluent C# extensions and XAML markup extensions that can make localized UI development simpler and more ergonomic.

Proposed API

// Observable wrapper to CurrentUICulture and CurrentCulture
public partial class LocalizationManager : INotifyPropertyChanged
{
    public static LocalizationManager Current { get; } = new();
    public CultureInfo CurrentUICulture { get; set; } // Observable wrapper for `CultureInfo.CurrentUICulture` (for localized text)
    public CultureInfo CurrentCulture { get; set; } // Observable wrapper for `CultureInfo.CurrentCulture` (for formatting numbers, dates and currency)
    public Func<string, CultureInfo, string?>? LocalizationProvider { get; set; } // Delegate for resolving localized values
    public string? GetString(CultureInfo? culture, string s, params object?[] args); // Retrieves localized values from configured `LocalizationProvider` with built-in string formatting support
}

// Translate Fluent C# extension methods
public static class TranslateExtensionMethods
{
    public static T Translate<T, TProvider>(
        this T bindable, // BindableObject that will get the Translate extension method
        BindableProperty targetProperty, // Property that will get the culture-aware binding
        string key, // String resource that will be translated with LocalizationManager.Current.LocalizationProvider
        params object?[] args // Will be used for string.Format only if TProvider == string
        ) where T : BindableObject;
    public static T Translate<T, TProvider>(
        this T bindable, // BindableObject that will get the Translate extension method
        BindableProperty targetProperty, // Property that will get the culture-aware binding
        Func<CultureInfo?, TProvider> localizationProvider, // Used for building the culture-aware binding
        params object?[] args // Will be used for string.Format only if TProvider == string
        ) where T : BindableObject;
}

// Translate XAML Markup extension
[ContentProperty(nameof(Key))]
public partial class TranslateExtension : BindableObject, IMarkupExtension<BindingBase>
{
    [BindableProperty] public partial string Key { get; set; } = string.Empty; // string resource, e.g. "BUTTON_CLICKED_N_TIMES"
    [BindableProperty] public partial object? X0 { get; set; } = null; // {0} formatting string resource. e.g. {0} in "Button clicked {0} times"
    [BindableProperty] public partial object? X1 { get; set; } = null; // {1} formatting string resource
}

// TranslateBindingBase.Create factory method for creating culture-aware bindings. Inspired by `BindingBase.Create`
public static class TranslateBindingBase
{
    public static BindingBase Create<TReturn>(
        string key, // String resource that will be translated with LocalizationManager.Current.LocalizationProvider
        params object?[] args); // Optional arguments (either scalar or bindings)
    public static BindingBase Create<TReturn>(
        Func<CultureInfo?, TReturn> localizerProvider, // Convert the delegate to a culture-aware binding
        params object?[] args); // Optional arguments (either scalar or bindings)
}

N.B. This is a minimal skeleton of the proposed API. The GitHub repository below has additional details, such as additonal overloads on the Translate Fluent C# markup extension and the corresponding overloads on TranslateBindingBase.Create.

Example: Fluent C# localization

The following example demonstrates the Translate extension method. Rather than supplying a static string, Translate accepts a delegate that is evaluated on demand, allowing localized values to be re-resolved whenever the UI culture changes

void OnCounterClicked(object? sender, EventArgs e)
{
    Count++;
    if (Count == 1)
        CounterBtn.Translate(Button.TextProperty, _ => AppStrings.BUTTON_CLICKED_1_TIME);
    else
        CounterBtn.Translate(Button.TextProperty, _ => AppStrings.BUTTON_CLICKED_N_TIMES, Count);
    SemanticScreenReader.Announce(CounterBtn.Text);
}

Example: XAML localization

The Translate markup extension provides a simple XAML syntax for localization through a configurable localization provider and automatically updates bound UI elements when the active UI culture changes.

<ContentPage xmlns:i18n="clr-namespace:..." Title="{i18n:Translate TITLE_HOME}">
    <ScrollView>
        <VerticalStackLayout>
           <Label Text="{i18n:Translate LABEL_HELLO_WORLD}" />
           <Label Text="{i18n:Translate LABEL_WELCOME}" />
           <Button x:Name="CounterBtn" Text="{i18n:Translate BUTTON_CLICK_ME}" />
        </VerticalStackLayout>
    </ScrollView>
</ContentPage>

While the LocalizationProvider can be implemented using any localization source, a RESX ResourceManager can be wired up as follows:

LocalizationManager.Current.LocalizationProvider = AppStrings.ResourceManager.GetString;

Example: Runtime culture switching

CurrentUICulture is exposed through an observable wrapper that raises property change notifications. As a result, updating the value automatically triggers localization updates throughout the application.

LocalizationManager.Current.CurrentUICulture = new CultureInfo("fr-FR");

Example: Bindable arguments

If a localized resource has arguments, e.g. "Button clicked {0} times", the arguments may be supplied as bindings to the Translate markup extension rather than scalar values. For example:

CounterBtn.Translate(
    Button.TextProperty,
    _ => AppStrings.BUTTON_CLICKED_N_TIMES,
    BindingBase.Create(static (MainPage p) => p.Count, BindingMode.OneWay));

Likewise, arguments can be provided through bindings as parameters to the Translate XAML markup extension using X0 or X1, e.g.

<Button Text="{i18n:Translate BUTTON_CLICKED_N_TIMES, X0={Binding Count}}" />

Example: TranslateBindingBase.Create

TranslateBindingBase.Create can also be used to create culture-aware bindings.

CounterBtn.SetBinding(
    Button.TextProperty,
    TranslateBindingBase.Create(
        _ => AppStrings.BUTTON_CLICKED_N_TIMES,
        BindingBase.Create(static (MainPage p) => p.Count, BindingMode.OneWay)));

While this approach is more verbose than the Fluent C# Translate extension, TranslateBindingBase.Create is provided to support MultiBinding scenarios that require a BindingBase instance and therefore cannot be implemented using the Fluent C# Translate extension.

Example: Localize non-string types

The localization APIs are not limited to strings. Any bindable property can react to culture changes, enabling scenarios such as automatically switching FlowDirection or mirroring directional images for right-to-left languages.

// Right-to-left aware
this.Translate(
   FlowDirectionProperty,
   uiCulture => uiCulture?.TextInfo.IsRightToLeft == true
      ? FlowDirection.RightToLeft
      : FlowDirection.LeftToRight);

// Horizontal mirror
DotNetBot.Translate(
	Image.ScaleXProperty,
	uiCulture => uiCulture?.TextInfo.IsRightToLeft == true ? 1 : -1);

Example: Localize collections

If a collection contains localization keys (for example, "CHOICE_YES", "CHOICE_NO", and "CHOICE_MAYBE"), the Translate markup extension can bind to each key and automatically resolve the corresponding localized value:

<CollectionView ItemsSource="{Binding Choices}">
    <CollectionView.ItemTemplate>
        <DataTemplate>
            <Button Text="{i18n:Translate Key={Binding .}}" />
        </DataTemplate>
    </CollectionView.ItemTemplate>
</CollectionView>

public List<string> Choices { get; } = [ "CHOICE_YES", "CHOICE_NO", "CHOICE_MAYBE" ];

Example: Complex LocalizationProvider

LocalizationManager.Current.LocalizationProvider abstracts ResourceManager string lookups, allowing applications to source translations from one or more RESX files, custom resource managers, or third-party localization engines.

LocalizationManager.Current.LocalizationProvider = (key, uiCulture) =>
{
    foreach (var localizer in new Func<string, CultureInfo, string?>[]
    {
        AppStrings.ResourceManager.GetString,
        MoreStrings.ResourceManager.GetString,
        (key, culture) => JsonDictionary.TryGetValue(key + "-" + culture.Name, out var value) ? value : null,
        (key, culture) => JsonDictionary.TryGetValue(key, out var value2) ? value2 : null,
    })
    {
        if (localizer(key, uiCulture) is { Length: > 0 } value)
        {
            return value;
        }
    }
    return null;
};

Sample Implementation

The following repository contains source code for a working proof of concept, including fully functional backend implementations and examples of both the Fluent C# and XAML localization experiences within the .NET MAUI starter template application.

https://github.com/stephenquan/MauiLocalize2026