Introducing SayWhat.Forms: A Simple Localization Framework for Xamarin.Forms

SayWhat.Forms on GitHub and NuGet

After writing my guide on how to do dynamic localization, I realized how clunky it feels. There are other frameworks out there that you can use and bulkier patterns that could accomplish the same thing as I am doing here, but I felt there was a much simpler approach to solving a dynamic localization pattern. Wrapper classes + messaging subscribers + IDisposible is a recipe that allows users to develop per usual but use the wrapper class instead of the out of the box classes that manage the updates for you. In a way I feel a little bad saying that this is my first open source framework that I have contributed since I started professionally developing back in 2013. I guess it’s never too late!

Supported Controls

• The framework supports titles on all pages
  • LocalizedCarouselPage
  • LocalizedContentPage
  • LocalizedFlyoutPage
  • LocalizedNavigationPage
  • LocalizeTemplated
• As well as text and placeholders (if the control supports it) for:
  • LocalizedButton
  • LocalizedEntry
  • LocalizedLabel

Usage

Click here For a full example and demo.

Initialization

var resourceManager = new ResourceManager(“SayWhat.Forms.Demo.Resources.AppResources”, Assembly.GetAssembly(typeof(Main Page))); Utilities.SayWhat.Settings.Initialize(resourceManager, CurrentCulture);

It is recommended to initialize in the app.xaml.cs or app.cs file as it is done here.

Xaml

File on GitHub

In Xaml, create a variable from the namespace. Here I have assigned it to ‘sw’ for SayWhat”. However, it can be anything such as: il8n, localization, translations, etc.

Now you can use controls and set the resource name of the string you want translated to the resourcename property on each control.

<?xml version="1.0" encoding="utf-8" ?>
<sw:LocalizedContentPage
    xmlns="http://xamarin.com/schemas/2014/forms"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    xmlns:sw="clr-namespace:SayWhat.Forms.Controls;assembly=SayWhat.Forms"
    x:Class="SayWhat.Forms.Demo.MainPage"
    TitleResourceName="TranslatedTitle">
    <StackLayout 
        HorizontalOptions="Center"
        VerticalOptions="Center">
        <sw:LocalizedLabel 
            TextResourceName="HelloWorld" 
            FontSize="18"/>
        <sw:LocalizedEntry
            PlaceHolderResourceName="PlaceholderText" />
        <sw:LocalizedButton 
            TextResourceName="UpdateLanguage" 
            Clicked="Button_Clicked" />
    </StackLayout>
</sw:LocalizedContentPage>

C#

Translation of the above example in C#.

Using SayWhat.Forms
public MainPage : LocalizedContentPage
{
   public MainPage()
   {
       TitleResourceName = "TranslatedTitle"
       Content = new StackLayout
       {
           Children = 
           {
              new LocalizedLabel { TextResourceName="HelloWorld", FontSize="18"},
              new LocalizedEntry { PlaceHolderResourceName="PlaceholderText" },
              new LocalizedButton { TextResourceName="UpdateLanguage",   Clicked="Button_Clicked"}
           } 
       }
   }
}

Code Behind

The idea is a fairly simple one. Basically wrap the original control or page, take items that are translatable and when the culture is updated notify the control to retrieve the updated value. And of course, allow the garbage collector to clean up when no longer in use.

using SayWhat.Forms.Messages;
using SayWhat.Forms.Utilities;
using System;
using Xamarin.Forms;

namespace SayWhat.Forms.Controls
{
    public class LocalizedLabel : Label, IDisposable
    {
        public static readonly BindableProperty TextResourceNameProperty =
            BindableProperty.Create(
                  nameof(TextResourceName),
                  typeof(string),
                  typeof(LocalizedLabel),
                  null,
                  BindingMode.Default,
                  propertyChanged: TextResourceNameChanged);

        public LocalizedLabel()
        {
            MessagingCenter.Subscribe<object>(new object(), CultureChangedMessage.Message, (o) => UpdateText(this));
        }

        public string TextResourceName
        {
            get => GetValue(TextResourceNameProperty) as string;
            set => SetValue(TextResourceNameProperty, value);
        }

        public static void TextResourceNameChanged(BindableObject bindable, object oldValue, object newValue)
        {
            LocalizedLabel label = (LocalizedLabel)bindable;
            label.TextResourceName = (string) newValue;
            SetText(label);
        }

        public static void SetText(LocalizedLabel label)
        {
            label.Text = DynamicLocalizer.GetText(label.TextResourceName);
        }

        public void UpdateText(LocalizedLabel label)
        {
            label.Text = DynamicLocalizer.GetText(label.TextResourceName);
        }

        public void Dispose()
        {
            MessagingCenter.Unsubscribe<object>(new object(), CultureChangedMessage.Message);
        }
    }
}

Future Updates

In the future, I hope to support more localized items such as images, but if you want to jump in the game, feel free to fork the repository too! Hopefully, this framework will make someone’s life a little easier if the requirement of dynamic localization ever comes their way.

When Maui is fully released, I look forward to updating the framework to accommodate it, if applicable.

Have a different solution?

I’m always interested in learning better ways to manage code. If you have a different or better solution to the same problem, comment and let me know. I’d love to hear from you.