Android Localization: Getting Started

Right-To-Left Languages

Supporting multiple languages can sometimes require extra consideration. Some languages, for instance Arabic or Hebrew, read from right-to-left, RTL, rather than left-to-right, LTR, like the English languages this tutorial has covered so far.

Mirroring UI

To support RTL languages in your app, you should test your layouts to ensure your UI functions as intended when mirrored.

For simple layouts, following Android best practices when creating your layouts should go a long way. You should always build according to best practices to minimize the effort required to make changes down the line. Key things to keep in mind are:

The left hand side of the screen remains on the left even when mirrored. So the layout doesn’t change when mirrored when you use this attribute to position a view.

It’s most common to set either android:layout_width or android:layout_height to wrap_content to allow it to wrap to the size it needs. If your layout really does need fixed sizes, you should look at utilizing Autosizing TextViews.

• Always use xml attributes referring to the start and end of views instead of left and right, unless your layout strictly requires this for all locales. If the device is set to RTL, the right hand side of the screen is considered the start instead of the left. So, these attributes help display your layout as expected when mirrored.
• Don’t restrict both android:layout_width and android:layout_height of a TextView to fixed values. Words and phrases may differ in length when translated into different languages. The text may be cut off if you have fixed your view to a size which is too small.
• Consider using ConstraintLayout to build your layout. Features such as Barriers are particularly useful for allowing the UI to adapt to strings of different lengths when lining up other views. Refer to this tutorial if you want to learn more about ConstraintLayout.

Creating Custom Layouts for Locales

In most cases, following the above tips should enable you to use the same layout file to support both LTR and RTL. But for complex layouts or particularly custom UIs, you may wish to create separate layout files to optimize layouts for different layout directions.

Store the RTL optimized layouts in a resource directory named layout-ldrtl, keeping the layout file name the same as the one you wish to replace for RTL configurations. You can create this directory in Android Studio the same way you created a new directory for different String locales earlier.

This time, select layout as the resource type and use Layout Direction as the qualifier. Pick RTL as the layout direction for this directory.

Testing for RTL Locales

The sample project currently doesn’t contain any RTL language files. But you can still test to see if the app is ready to support them.

First, confirm the app has enabled RTL support by checking in AndroidManifest.xml that application contains android:supportsRtl=”true”.

While developing your layout in Android Studio, you can use the layout preview pane to quickly see how it would look in RTL mode.

Earlier, you learned how to view the localized strings in the layout preview. You might have noticed the Right to Left preview in the same menu. Toggling Preview Right to Left in this menu mirrors the layout in the preview.

Once you’re happy with your layout, you should also test on an Android emulator. Luckily, the developer options on the device have some useful tools for testing different types of languages. So, you can test your layout in RTL mode without learning to read Arabic first!

Developer Options

If you haven’t already, enable developer options on your emulator. To do this, open the Settings app and find the Build number.

This number’s location can vary for different devices, but you’ll likely find it at System ▸ About emulated device. Tap the row containing the build number seven times.

Congratulations, you’re now a developer! :]

With your shiny new developer status, you now have access to Developer Options, a new menu in the System area of Settings.

Click the Developer options menu and ensure it’s turned on.

Pseudolocales

Next, enable pseudolocales for your debug builds. In the sample project you need to add a new configuration to your app build.gradle. Add the following code inside the buildTypes section to add a new debug build type and enable pseudolocales.

debug {
  pseudoLocalesEnabled true
}

Your build.gradle should look like this:

Since you edited build.gradle, you’ll need to sync. Press the Sync Now button in the banner at the top of the file. Then build and run the app. You’re ready to test on the emulator.

With the latest debug version of the app loaded on the device, all that’s left to do to test for RTL locales is to change the device language to a pseudolocale. There are two available pseudolocales:

• English([XA]): This is a LTR locale which reads like English, but adds accents to characters and expands text to aide with exposing layout issues.
• Arabic([XB]): This is an RTL locale. It triggers the device to go into mirrored UI mode to better support the RTL text direction. It also reverses the characters of English strings to help mimic an RTL locale. This helps expose layouts that aren’t mirrored properly and strings that can’t be translated or have other punctuation or number character ordering issues.

You can find the pseudolocales in the Languages section of Settings.

Select cibarA([XB]) from the languages list and move it to the top of your language preferences. The device will automatically switch to RTL mode. You’ll also see that the system string character ordering is reversed to emulate a RTL directional locale.

Open the app and you’ll see how it looks in a RTL locale.

The app looks good mirrored and is ready to support RTL languages!

Drawables

You’ve already covered a lot in this tutorial, but there’s still one thing left to address. The app still shows the US flag to users of all locales!

By now, you’ve probably got the hang of adding resource files for different configurations, but here are the steps one more time.

Create a new resource directory where you’ll add a new image to display to British users. As before, right click on the res package and select New ▸ Android resource directory. You need to create a new drawable folder for the en-GB locale. Select drawable as the resource type, locale as the qualifier, en:English as the language and GB:United Kingdom as the region.

When you add a new image to this directory, you’ll need to make sure to save it with the same name as the default image. That way, when the device switches locale it can use the same filename referenced in the code to get the image.

For the sample app, you should save the new image with the filename img_flag.png. You can either save this image directly into the folder using a File Explorer on your machine, or drag and drop the image file into the folder in Android Studio.

Feel free to find your own image to use here. But here’s a cute little Union Jack in the same style as the existing US flag you can use. Right click and save it into your new GB resource directory.

You’ve now added a localized drawable. Build and run the app again. Change your emulator or device’s primary language to English (United Kingdom) and open the app again to see the new image displayed on the screen.