Home / News / How To Localise Your Xamarin.Forms Apps

How To Localise Your Xamarin.Forms Apps

Learn to update your Xamarin.Forms apps to support multiple languages.

Introduction

When building our Xamarin.Forms apps, there usually comes a point where we need to support multiple languages. If you're lucky, you've been localising as you've been building your application!

But chances are, like me, you've been in a rush to ship the app and multiple language support was put on the back-burner... And now you've got a few dozen XAML and C# files to localise!

The process of manually replacing each string value is a little daunting, not to mention cumbersome and time-consuming! However, with a little bit of work, enabling multi-language support in your app is very achievable.

So, let's roll up our sleeves and get localising.

Localisation Infrastructure Setup

The very first thing we need to do is to create the infrastructure to power localisation for our XAML files. We'll be using the best practices outlined in Xamarin's excellent localisation tutorial

Firstly, we need to detect the current language settings of the user's phone. We do this by creating an interface in our PCL named ILocalize. We'll use this to provide the platform's current language settings into our shared code:

ILocalize.cs
using System;
using System.Globalization;

namespace MyApp.il8n
{
  public interface ILocalize
  {
    CultureInfo GetCurrentCultureInfo();

    void SetLocale();
  }
}

Next we create an iOS and an Android implementation of this interface:

We'll need somewhere to store the localised versions for our strings; in Xamarin.Forms we can use RESX files for this. In our PCL, create a new file named Resources.resx inside a directory named Resources.

Lastly, we create a custom markup extension named TranslateExtension in our PCL that takes a resource key, inspects the current language setting using ILocalize and then grabs the localisation value from our apps RESX resources:

Setting up all this infrastructure is a little tedious.... Instead of doing it by hand we can use MFractors Generate Localisation Infrastructure code action to do it for us. Simply right-click on any XAML string literal and the select Generate localisation infrastructure:

Generating XAML localisation infrastructure


All done!

Now let's move those pesky inline strings into resource files.

Localising XAML

Let's start by localising our apps LoginPage.xaml:

LoginPage.xaml
<?xml version="1.0" encoding="utf-8"?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
xmlns:local="clr-namespace:MyApp"
x:Class="MyApp.LoginPage">
  <StackLayout>
    <Image Source="icon.png"/>
    <Label Text="Email:"/>
    <Entry Text="{Binding Email}" Placeholder="Enter your email"/>
    <Label Text="Password:"/>
    <Entry Text="{Binding Password}" Placeholder="Enter your password"/>
    <Button Text="Login" Command="{Binding LoginCommand}"/>
  </StackLayout>
</ContentPage>


Our login page has five inline strings that need to be moved into a RESX file and then be replaced by a localisation lookup.

Let's start by localising the Email: string.

Firstly we need to create a new RESX entry for our string along with a key. Open up the Resources.resx file and at the end of the file, enter the following text:

<data name="EmailLabel" xml:space="preserve">
  <value>Email:</value>
</data>


This creates a new string resource for our Email: string that our TranslateExtension can retrieve when provided the key EmailLabel.

The next step is to replace the original Email: string in our XAML with a localisation lookup.

To do this, we add an XML namespace declaration to import our TranslateExtension:

xmlns:il8n="clr-namespace:MyApp.il8n"

And then we replace the Email: string with a resource lookup using the TranslateExtension; note that we can omit the Extension part of the name and just use il8n:Translate:

<Label Text="{i18n:Translate Email}"/>

Viola! We now have a localised email label.

The Localisation Wizard

Now that we've localised one string by hand, let's learn how we can use MFractor to speed up localising our XAML.

MFractor includes a localisation wizard that can move strings in a C# or XAML file into a RESX file and replace the original string value with a resource lookup.

For the localisation wizard to activate in XAML, we need to have a TranslateExtension that resolves to the symbol MyApp.il8n.TranslateExtension and at least one RESX file in our project.

Open the localisation wizard by right-clicking on any string literal and selecting Replace with a localised value lookup.

Once opened, you can choose the .resx file to place that string into, enter a key for the new resource and then selecting replace. Alternatively, you can apply the localisation action by press the Return key.

If the string value already exists in the .resx file that you have chosen, MFractor warns you that it's a duplicate with a yellow exclamation icon. If you'd like to use the existing key for the string value, you can press Shift+Return.

After you've localised a string, the localisation wizard will automatically move onto the next string that can be localised.

It's very quick to convert the remaining strings of our LoginPage.xaml into localisation lookups with the localisation wizard:

Localising XAML using MFractors localisation wizard.

Localising C#

If you have an MFractor Professional license, then you can also use localisation wizard in C# to move string literals into RESX files.

When you have at least one .resx file, access the localisation wizard by pressing Option+Return on a string literal.

Under the context menu that opens, choose "Replace with resx lookup".



Much like when localising XAML, the localisation wizard will let you walk over the document, highlighting localisable strings and let you move the string into a RESX file.

Summary

Even though we didn't plan to support multiple languages, it's not difficult to update your app to support multiple languages at a later date.

By using Xamarins best practices and MFractor's localisation wizard, we can quickly and easily retrofit our app with multi-language support.

Interested in localising your app quickly and easily? Using MFractor Lite, you can localise up to two XAML files per day!

Install MFractor today by visiting the Extension Gallery in Visual Studio Mac.

0 comments

Leave a comment