Avalonia UI Framework localization

So you want to localize your application developed using the Avalonia UI Framework? Let’s see how it can be done.

Some informations are taken from this bug report.

To localize an application we must be able to

  • Localize strings directly in the XAML
  • Get access to the localization strings in the code

To translate strings in the XAML we can use a custom MarkupExtension and bindings

    public class LocalizeExtension : MarkupExtension
        public LocalizeExtension(string key)
            this.Key = key;

        public string Key { get; set; }

        public string Context { get; set; }

        public override object ProvideValue(IServiceProvider serviceProvider)
            var keyToUse = Key;
            if (!string.IsNullOrWhiteSpace(Context))
                keyToUse = $"{Context}/{Key}";

            var binding = new ReflectionBindingExtension($"[{keyToUse}]")
                Mode = BindingMode.OneWay,
                Source = Localizer.Instance,

            return binding.ProvideValue(serviceProvider);

Note that in addition to the string key there’s also a context, used to have different translations for the same string in different contexts.

This extension can be used in XAML:

<Window xmlns="https://github.com/avaloniaui"
        mc:Ignorable="d" d:DesignWidth="800" d:DesignHeight="450"
        Width="500" Height="350"

  <StackPanel Orientation="Vertical" Margin="15">
    <Label Content="{i18n:Localize Language}" />
    <ComboBox SelectedIndex="0" SelectionChanged="OnLanguageChanged">

    <TextBlock FontSize="21" Text="{i18n:Localize HelloWorld}"/>
    <TextBlock FontSize="21" Text="{i18n:Localize HelloWorld, Context=Second}"/>
    <TextBlock FontSize="21" Text="{i18n:Localize MissingTranslation}"/>

We need to define the namespace first


then we can bind strings using our MarkupExtension

<TextBlock FontSize="21" Text="{i18n:Localize HelloWorld}"/>

Now we need a way to translate the strings to the desired language. An easy way is to use JSON files containing the context/key with the corresponding translated text. We can embed the JSON files using assets

Missing strings are displayed as the language code followed by a semicolon and the string key.

public class Localizer : INotifyPropertyChanged
        private const string IndexerName = "Item";
        private const string IndexerArrayName = "Item[]";
        private Dictionary<string, string> m_Strings = null;

        public Localizer()


        public bool LoadLanguage(string language)
            Language = language;
            var assets = AvaloniaLocator.Current.GetService<IAssetLoader>();

            Uri uri = new Uri($"avares://AvaloniaLocalizationExample/Assets/i18n/{language}.json");
            if (assets.Exists(uri)) {
                using (StreamReader sr = new StreamReader(assets.Open(uri), Encoding.UTF8)) {
                    m_Strings = JsonConvert.DeserializeObject<Dictionary<string, string>>(sr.ReadToEnd());

                return true;
            return false;
        } // LoadLanguage

        public string Language { get; private set; }

        public string this[string key]
                string res;
                if (m_Strings != null && m_Strings.TryGetValue(key, out res))
                    return res.Replace("\\n", "\n");

                return $"{Language}:{key}";

        public static Localizer Instance { get; set; } = new Localizer();
        public event PropertyChangedEventHandler PropertyChanged;

        public void Invalidate()
            PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(IndexerName));
            PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(IndexerArrayName));

Since we are using bindings and INotifyPropertyChanged the translated text is applied as soon as we load a new language.

To access to the translated strings in the code use the static Localizer using the string key


You can download the source code here