{"id":35050,"date":"2018-02-08T15:10:34","date_gmt":"2018-02-08T23:10:34","guid":{"rendered":"https:\/\/blog.xamarin.com\/?p=35050"},"modified":"2019-04-04T08:47:33","modified_gmt":"2019-04-04T15:47:33","slug":"add-languages-to-your-apps-with-xamarin-and-multilingual-app-toolkit","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/xamarin\/add-languages-to-your-apps-with-xamarin-and-multilingual-app-toolkit\/","title":{"rendered":"Add Languages to Your Xamarin Apps with Multilingual App Toolkit"},"content":{"rendered":"

With Xamarin, you can extend your cross-platform apps with support for native speakers, reaching markets that might otherwise be overlooked. However, managing multiple languages and keeping everything current can be challenging, especially if you\u2019re not fluent in\u00a0those languages.<\/p>\n

\"\"This is where the Multilingual App Toolkit (MAT)<\/a> can help by automating\u00a0the management of your language support, so you can focus on what you do best: build great cross-platform apps!<\/p>\n

Before getting started, it’s important to note that most project templates are not<\/em> localization enabled. Fortunately, adding localization support is straightforward. Once you do the initial setup, your app will be ready to travel the world.<\/p>\n

Getting Started with Multilingual App Toolkit<\/h2>\n

Let\u2019s look quickly at this process using a Xamarin.Forms sample. The LocalizationSample<\/a> project has all the plumbing and is available on GitHub.<\/p>\n

Wiring up localization can be done quickly using a NuGet called Multilingual (Localization) Plugin for Xamarin and Windows<\/em><\/a>. The documentation is straightforward, with the core being the addition of the TranslationExtension<\/code> class to provide XAML binding for your app\u2019s resources. Here’s the code-snippet Plugin.Multilingual<\/code> used to wire up access to the resources:<\/p>\n

[ContentProperty(\"Text\")]\r\npublic class TranslateExtension : IMarkupExtension\r\n{\r\n    const string ResourceId = \"LocalizationSample.Resources.AppResources\";\r\n\r\n    static readonly Lazy resmgr = \r\n        new Lazy(() => \r\n            new ResourceManager(ResourceId, typeof(TranslateExtension)\r\n                    .GetTypeInfo().Assembly));\r\n\r\n    public string Text { get; set; }\r\n\r\n    public object ProvideValue(IServiceProvider serviceProvider)\r\n    {\r\n        if (Text == null)\r\n            return \"\";\r\n\r\n        var ci = CrossMultilingual.Current.CurrentCultureInfo;\r\n        var translation = resmgr.Value.GetString(Text, ci);\r\n\r\n        if (translation == null)\r\n        {\r\n            translation = Text; \/\/ returns the key, which GETS DISPLAYED TO THE USER\r\n        }\r\n        return translation;\r\n    }\r\n}<\/pre>\n
Of course, you’ll need a place to store the localizable text. Using the familiar RESX file with Xamarin.Forms makes this a snap. Simply add a folder named \u201cResources\u201d to the SampleLocalization project. In this folder, add AppResources.resx<\/code> and \u201cHelloWorld\u201d with the value \u201cHello from App Resource\u201d to the new RESX file:<\/p>\n
\"\"\"\"<\/p>\n
The final step before all the wiring is complete is to replace the hard-coded text in the XAML code with bindings that will retrieve the text from the resource file. All that remains is adding a reference to the TranslateExtension<\/code> and applying the binding, like so:<\/p>\n
<?xml version=\"1.0\" encoding=\"utf-8\" ?>\r\n<ContentPage xmlns=\"http:\/\/xamarin.com\/schemas\/2014\/forms\"\r\n             xmlns:x=\"http:\/\/schemas.microsoft.com\/winfx\/2009\/xaml\"\r\n             xmlns:i18n=\"clr-namespace:LocalizationSample.Helpers;assembly=LocalizationSample\" \r\n             xmlns:local=\"clr-namespace:LocalizationSample\"\r\n             x:Class=\"LocalizationSample.MainPage\"\r\n             Title=\"Let's Translate!\">\r\n \r\n    <StackLayout Padding=\"20\">\r\n\t    <Label Text=\"{i18n:Translate HelloWorld}\" \r\n               LineBreakMode=\"WordWrap\"\/>\r\n \r\n\t    <Label \r\n                Margin=\"0,60,0,0\"\r\n                Text=\"Translate this automatically\"\r\n                LineBreakMode=\"WordWrap\"\r\n               x:Name=\"LabelTranslate\"\/>\r\n \r\n\t    <Picker ItemsSource=\"{Binding Languages}\"\r\n                ItemDisplayBinding=\"{Binding DisplayName}\"\r\n                x:Name=\"PickerLanguages\"\/>\r\n \r\n    <\/StackLayout>\r\n \r\n<\/ContentPage><\/pre>\n
Running the app should now display the English string \u201cHello from App Resource\u201d as well as the still hard-coded text values:<\/p>\n
\"\"<\/p>\n
Traditionally, after ensuring the localization is wired up and displaying correctly, you would finish adding all the app\u2019s resource data before considering adding additional languages to avoid managing the changes to the resource or the related translation during the ongoing development process. This can be a challenge with only one or two additional languages, but becomes daunting very quickly as more languages are added.<\/p>\n
It’s best to validate that your app\u2019s language support is working correctly throughout the development process to avoid bugs that may delay your app\u2019s release, or worse, cause you to reduce market support by cutting additional language support.<\/p>\n
This is where the Multilingual App Toolkit (MAT)<\/a> comes in. It manages your target REXS files by applying on-demand Machine Translations throughout the development process. Once development nears completion, you can have the translations proofed and adjusted by family, friends, co-workers, or translation vendors.<\/p>\n
Install and Enable<\/h2>\n
To Install the Multilingual App Toolkit(MAT), just use Visual Studio\u2019s Tools -> Extensions and Updates<\/em> menu:<\/p>\n
\"\"<\/p>\n
After the installation is completed, you will need to ensure your app has defined the default app language. This is the language displayed if the app does not<\/em> support the language of the device. It’s also the language MAT uses to know how to translate into other languages.<\/p>\n
To check the Neutral Language<\/strong>, right-click the LocalizationSample<\/code> project and select Properties<\/strong>. On the package tab, the Assembly Neutral Language<\/em> value determines the app’s default language. This should be set to the language you use in your AppResources.resx<\/code> file. In this example, it will be English (en-US):<\/p>\n
\"\"<\/p>\n
MAT needs to be enabled for any project that has localizable text. This is done by selecting the project in the Solution Explorer<\/strong>, then the Tools -> Multilingual App Toolkit -> Enabled selection<\/em>:<\/p>\n
\"\"<\/p>\n
Adding target languages is as simple as right-clicking on the project and selecting Multilingual App Toolkit -> Add translation languages<\/em>. Remember to set up the Azure Cognitive Service configuration<\/a> for MAT\u2019s Microsoft Translator provider first.<\/p>\n
\"\"\"\"<\/p>\n
After selecting the desired language and clicking “OK” and MAT will add two files for every language selection, an .XLF file<\/strong> and the corresponding .RESX file<\/strong>. The .XLF file is an XLIFF 1.2 industry standard file that is designed to support translation data. The related RESX files are managed by MAT and used by Visual Studio to add the desired language support to your app.<\/p>\n
\"\"<\/p>\n
Selecting one or more .XLF file enables the menus that allow for Machine Translation or even exporting for external localization. Select Generate machine translations<\/strong> to apply machine-generated translations to your project:<\/p>\n
\"\"\"\"<\/p>\n
Note: Before building, ensure the Package Action is set to XliffResource<\/code>. This setting is used by the build task to update related RESX with the translation in the .XLF file. Without this setting, your app will not contain the translation:<\/p>\n
\"\"<\/p>\n
Now it’s time to build and run your app! Language picking in the sample is configured dynamically; you can switch the text for easy testing. For more application, let the device\u2019s language pick the app\u2019s language automatically.<\/p>\n
\"\"<\/p>\n
See It In Action<\/h2>\n
This week I joined James Montemagno<\/a> on The Xamarin Show<\/a> to show off the Multilingual App Toolkit in action:<\/p>\n