{"id":47570,"date":"2020-07-21T10:32:51","date_gmt":"2020-07-21T17:32:51","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/xamarin\/?p=47570"},"modified":"2020-09-15T11:16:18","modified_gmt":"2020-09-15T18:16:18","slug":"mastering-multilingual-in-xamarin-forms","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/xamarin\/mastering-multilingual-in-xamarin-forms\/","title":{"rendered":"Mastering Multilingual in Xamarin.Forms"},"content":{"rendered":"

This is a guest blog post by Charlin Agramonte. Charlin is a Microsoft MVP. She writes Xamarin articles in her blog xamgirl.com<\/a> and you can find her on Twitter at @Chard003<\/a>.<\/strong><\/p>\n

Multilingual support is one of the most common requirements for mobile apps. One of the great parts of building mobile apps with Xamarin is that handling multiple languages is super simple. It may seem like a difficult task, but it is relatively easy if you leverage built in .NET capabilities to add multilingual support to your apps. A while back I wrote an article<\/a> on how to do add multilingual support with my plugin<\/a>. In this article, I will talk about some typical problems that you might face when adding multilingual support and how to solve them. Let\u2019s start!<\/p>\n

Setting App Culture<\/h2>\n

When multiple languages are handled in our application, a typical use case is to support that the user can change the language within the application. The problem can come up because we often bind our XAML strings to the AppResources<\/code> class directly. This means we don\u2019t have a mechanism to observe when the language changes and we would need to restart the application to get those strings updated.<\/p>\n

The code to set the Culture<\/code> is usually set in the App startup code:<\/p>\n

Thread.CurrentThread.CurrentUICulture = language;\nAppResources.Culture = language;\nApp.Current.MainPage = new NavigationPage(new MainPage());\n<\/code><\/pre>\n
\"Mastering<\/p>\n
While this works, restarting our entire application could be painful and isn\u2019t a good user experience.<\/p>\n
Improving Runtime Changes<\/h2>\n
As I mentioned, the main problem with this is approach is that we bind to the AppResources class;s strings directly in the XAML. Or the app is using code behind and a translate class that returns a string with the text changed.<\/p>\n
When I was looking for a solution I found this great idea on StackOverflow<\/a> with a localization manager.<\/p>\n
I created a LocalizationResourceManager class that handles language changes and also will have a property with the translation. When the language changes it will invalidate that string so it will force the property to change.<\/p>\n
\n public class LocalizationResourceManager : INotifyPropertyChanged\n    {\n        public static LocalizationResourceManager Instance { get; } = new LocalizationResourceManager();\n\n        public string this[string text]\n        {\n            get\n            {\n                return AppResources.ResourceManager.GetString(text, AppResources.Culture);\n            }\n        }\n\n        public void SetCulture(CultureInfo language)\n        {\n            Thread.CurrentThread.CurrentUICulture = language;\n            AppResources.Culture = language;\n\n            Invalidate();\n        }\n\n        public event PropertyChangedEventHandler PropertyChanged;\n\n        public void Invalidate()\n        {\n            PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(null));\n        }\n    }\n<\/code><\/pre>\n
Instead of binding our strings directly to the AppResources class, a Translate Extension that returns a BindingProperty is used and binds to our new LocalizationResourceManager.<\/p>\n
\n[ContentProperty(\"Text\")]\npublic class TranslateExtension : IMarkupExtension<bindingbase>\n{\n    public string Text { get; set; }\n    object IMarkupExtension.ProvideValue(IServiceProvider serviceProvider)\n    {\n        return ProvideValue(serviceProvider);\n    }\n\n    public BindingBase ProvideValue(IServiceProvider serviceProvider)\n    {\n        var binding = new Binding\n        {\n            Mode = BindingMode.OneWay,\n            Path = $\"[{Text}]\",\n            Source = ResourceManagerHelper.Instance,\n        };\n        return binding;\n    }\n}\n<\/bindingbase><\/code><\/pre>\n
Finally, in our XAML we just have to use that translate extension.<\/p>\n
<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<ContentPage xmlns=\"http:\/\/xamarin.com\/schemas\/2014\/forms\"\n             xmlns:x=\"http:\/\/schemas.microsoft.com\/winfx\/2009\/xaml\"\n             x:Class=\"MultilingualXFSample.Views.ChangeLanguagePage\"\n             xmlns:helpers=\"clr-namespace:MultilingualXFSample.Helpers\">\n\n         <Label  Text=\"{helpers:Translate SelectLanguage}\" \/>\n<\/ContentPage>\n<\/code><\/pre>\n
\"Video<\/p>\n
Platform Control Localization<\/h2>\n
Since native platforms don\u2019t give us enough flexibility to change the control\u2019s locale in runtime we have to do a bit of custom work. After checking all the Xamarin.Forms controls, I only found 3 that we need to localize (Picker<\/code>, DatePicker<\/code>, and TimePicker<\/code>). Let’s first start with the \u201cDone\u201d button text that is common on Pickers.<\/p>\n
\"iOS<\/p>\n
iOS<\/h3>\n
For iOS, I created an effect that can be applied to all of these controls. I added it as a general style so I don\u2019t have to add it each control when I use them in my UI.<\/p>\n
Effect<\/h4>\n
[assembly:ResolutionGroupName(\"MyCompany\")]\n[assembly:ExportEffect(typeof(iOSPickerDoneButtonEffect), nameof(PickerDoneButton))]\nnamespace MultilingualXFSample.iOS\n{\n   public class iOSPickerDoneButtonEffect : PlatformEffect\n   {\n    UIButton _doneBtn;\n    UIBarButtonItem _originalDoneBarButtonItem;\n\n\n    protected override void OnAttached()\n    {\n        var effect = (PickerDoneButton)Element.Effects.FirstOrDefault(e => e is PickerDoneButton);\n\n        if (effect != null && Control?.InputAccessoryView is UIToolbar toolbar && toolbar.Items?.Count() > 0)\n        {\n            _originalDoneBarButtonItem = toolbar.Items[1];\n\n            _doneBtn = new UIButton(UIButtonType.System);\n            _doneBtn.SetTitle(effect.ButtonTitle, UIControlState.Normal);\n            _doneBtn.Font = UIFont.BoldSystemFontOfSize(UIFont.SystemFontSize);\n            _doneBtn.TouchUpInside += HandleButtonClicked;\n\n            _originalDoneBarButtonItem.CustomView = _doneBtn;\n\n            if (Control.InputView is UIDatePicker picker)\n            {\n                picker.Locale = new Foundation.NSLocale(LocalizationResourceManager.Instance.CurrentCulture.TwoLetterISOLanguageName);\n            }\n        }\n    }\n\n\n    protected override void OnDetached()\n    {\n        if(_doneBtn !=null)\n        {\n            _doneBtn.TouchUpInside -= HandleButtonClicked;\n            _doneBtn = null;\n            _originalDoneBarButtonItem.CustomView = null;\n        }\n    }\n\n    void HandleButtonClicked(object sender, EventArgs e)\n    {\n        UIApplication.SharedApplication.SendAction(_originalDoneBarButtonItem.Action, _originalDoneBarButtonItem.Target, sender: null, forEvent: null);\n    }\n  }\n}\n<\/code><\/pre>\n
Style<\/h4>\n
<?xml version=\"1.0\" encoding=\"utf-8\"?>\n<Application xmlns=\"http:\/\/xamarin.com\/schemas\/2014\/forms\"\n             xmlns:x=\"http:\/\/schemas.microsoft.com\/winfx\/2009\/xaml\"\n             xmlns:d=\"http:\/\/xamarin.com\/schemas\/2014\/forms\/design\"\n             xmlns:mc=\"http:\/\/schemas.openxmlformats.org\/markup-compatibility\/2006\"\n             xmlns:helpers=\"clr-namespace:MultilingualXFSample.Helpers\"\n             xmlns:effects=\"clr-namespace:MultilingualXFSample.Effects\"\n             mc:Ignorable=\"d\"\n             x:Class=\"MultilingualXFSample.App\">\n    <Application.Resources>\n        <ResourceDictionary>\n            <Style TargetType=\"Picker\" ApplyToDerivedTypes=\"True\">\n                  <Style.Setters>\n                    <Setter Property=\"effects:PickerDoneButtonEffect.DoneButtonText\" Value=\"{helpers:Translate Done}\" \/>\n                  <\/Style.Setters>\n            <\/Style>\n\n             <Style TargetType=\"DatePicker\" ApplyToDerivedTypes=\"True\">\n                  <Style.Setters>\n                    <Setter Property=\"effects:PickerDoneButtonEffect.DoneButtonText\" Value=\"{helpers:Translate Done}\" \/>\n                  <\/Style.Setters>\n            <\/Style>\n\n             <Style TargetType=\"TimePicker\" ApplyToDerivedTypes=\"True\">\n                  <Style.Setters>\n                    <Setter Property=\"effects:PickerDoneButtonEffect.DoneButtonText\" Value=\"{helpers:Translate Done}\" \/>\n                  <\/Style.Setters>\n            <\/Style>\n        <\/ResourceDictionary>\n    <\/Application.Resources>\n<\/Application>\n<\/code><\/pre>\n
Android<\/h3>\n
On Android, I created an effect for the Picker and for DatePicker\/TimePicker I used a platform renderer. Since they have a Cancel\/Done button, there\u2019s not much flexibility to customize those buttons.<\/p>\n
You can check the full implementation for both platforms here<\/a>.<\/p>\n
\"Image<\/p>\n
Localized C# Text<\/h2>\n
Since the AppResources class is a static class, we can access it directly in C# code with just a few steps:<\/p>\n
Add the string to the Resource file.<\/h3>\n
<data name=\"WelcomeText\" xml:space=\"preserve\">\n    <value>Welcome to my App<\/value>\n<\/data>\n<\/code><\/pre>\n
Use it!<\/h3>\n
var text = AppResources.WelcomeText; \n<\/code><\/pre>\n
Remembering the Language<\/h2>\n
Thanks to Xamarin.Essentials this is pretty easy to achieve. We only have to persist the latest language code in the Preferences and load that persisted language code when opening the application.<\/p>\n
I added this logic to the actual LocalizationResourceManager.<\/p>\n
namespace MultilingualXFSample.Helpers\n{\n    public class LocalizationResourceManager : INotifyPropertyChanged\n    {\n        private const string LanguageKey = nameof(LanguageKey);\n\n        private LocalizationResourceManager()\n        {\n            SetCulture(new CultureInfo(Preferences.Get(LanguageKey, CurrentCulture.TwoLetterISOLanguageName)));\n        }\n        \/\/...\n        public void SetCulture(CultureInfo language)\n        {\n            \/\/...\n            Preferences.Set(LanguageKey, language.TwoLetterISOLanguageName);\n        }\n    }\n}\n<\/code><\/pre>\n
Handle small text modifications<\/h2>\n
There are some cases where we want to use translated text with a minor string modification. For example, we have the text \u201cSelect Language\u201d and \u201cSelect Language:\u201d. For these use cases we have a few options, we can add both texts in our AppResources file or add the text with the : in our viewmodel. The disadvantage of using the first one is that you will have repeatable texts in your AppResource file and using the second one you will be handling presentation logic in the ViewModel.<\/p>\n
A better approach is to use a FormattedText:<\/p>\n
  <Label>\n    <Label.FormattedText>\n        <FormattedString>\n            <Span Text=\"{helpers:Translate SelectLanguage}\" \/>\n            <Span Text=\":\" \/>\n        <\/FormattedString>\n    <\/Label.FormattedText>\n<\/Label>\n<\/code><\/pre>\n
This approach works very well when you are using a Label, since it supports FormattedText, but what happens when you have simple string? Since we bind to the AppResources class or use a TranslateExtension returning a simple text you can\u2019t use StringFormat.<\/p>\n
Workaround Modify our actual TranslateExtension file to support StringFormat.<\/p>\n
[ContentProperty(\"Text\")]\n    public class TranslateExtension : IMarkupExtension<BindingBase>\n    {\n        public string Text { get; set; }\n        public string StringFormat { get; set; }\n        object IMarkupExtension.ProvideValue(IServiceProvider serviceProvider)\n        {\n            return ProvideValue(serviceProvider);\n        }\n\n        public BindingBase ProvideValue(IServiceProvider serviceProvider)\n        {\n            var binding = new Binding\n            {\n                Mode = BindingMode.OneWay,\n                Path = $\"[{Text}]\",\n                Source = ResourceManagerHelper.Instance,\n                StringFormat= StringFormat\n\n            };\n            return binding;\n        }\n    }\n<\/code><\/pre>\n
And the XAML:<\/p>\n
 <Label  Text=\"{helpers:Translate SelectLanguage, StringFormat='{0}:'}\" \/>\n<\/code><\/pre>\n
Final thoughts<\/h2>\n
As you see, handling Multilingual in Xamarin.Forms is quite easy even in the most complex scenarios there are easy ways to get it working for your needs. As an extra recommendation, I encourage you to check these great tips in the Xamarin documentation<\/a> about Localization best practices that will help you to have more consistent code. Additionally, for simplicity is to use the Multilingual Toolkit<\/a> if you are using Visual Studio for Windows and MFractor<\/a> if you are using Visual Studio for Mac. Both are really useful tools when it comes to localization related tasks. That\u2019s all for now. You can check the full source code used here<\/a>.<\/p>\n
Happy coding!<\/p>\n","protected":false},"excerpt":{"rendered":"
This guest post by Charlin Agramonte elaborates on how multilingual support is one of the most common requirements for mobile apps and the simplicity of building mobile apps with Xamarin that handle multiple languages.<\/p>\n","protected":false},"author":579,"featured_media":47572,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[2,367],"tags":[7282,587,9003,9010,9019,9002,9018,27,16],"class_list":["post-47570","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-developers","category-xamarin-forms","tag-net","tag-accessibility","tag-localization","tag-mobile-applications","tag-mobile-apps","tag-multilingual","tag-multiple-languages","tag-xamarin","tag-xamarin-forms"],"acf":[],"blog_post_summary":"
This guest post by Charlin Agramonte elaborates on how multilingual support is one of the most common requirements for mobile apps and the simplicity of building mobile apps with Xamarin that handle multiple languages.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/posts\/47570","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/users\/579"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/comments?post=47570"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/posts\/47570\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/media\/47572"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/media?parent=47570"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/categories?post=47570"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/tags?post=47570"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}