The challenges of localizing an Android application (with special considerations for Arabic)

I don't usually blog about work-related problems I encounter, but I figured this could be useful for some people.

Below is a checklist of potential issues than can crop up when trying to introduce localization to an application that initially supported a single language.

Backend error messages

Instead of returning error messages, it would be more suitable to return error codes, and have the Android application display their interpretation in the user's language of choice. For example, instead of returning a string that says "This username is already in use", return something like "duplicate_username".

One caveat of this approach is how the context that comes with errors should be handled. In the previous example, when a username is already in use, it's customary to return similar usernames that are available. The backend and the frontend should agree on a way to pass this contextual data through the response.

Alternatively, you can propagate the localization all the way to the backend, then have the backend return error messages in the requested language. You can pass the chosen language to the backend in a variety of ways: through the Accept-Language header, via a URL parameter, or even persist it in a database when the user selects it.

Push notifications

The same principles apply here. You can either send notification labels that the Android Firebase service handler translates into readable messages, or you send readable messages in the language that the user chose.

Finding hardcoded strings

Android Studio warns about hardcoded strings that should be put in strings.xml. However, it doesn't warn about this if there's a level or more of indirection.

Translation warning

The translation warning is gone

Here's a useful tip to find the hardcoded strings that are littered throughout your project : https://stackoverflow.com/a/33165433/3729391

For good measure, after handling the cases where Android Studio displays a warning, search for edge cases with a regex like \.text = (?!getString) (or the Java equivalent with setText) and make sure there are no surprises there.

Text size differences

Sometimes, text takes more space when it's displayed in another language. This can result in visual bugs that weren't there prior to the introduction of new languages.

Text in images

If your application displays images that contain text, make sure to also have images that contain the translated text. This goes for static images as well as external ones.

Text displayed in WebViews

If your application displays content from websites, try to see if it's possible to load it in the user's chosen language. Sometimes websites have a URL parameter for this in the query string or in the path.

Special considerations for Arabic

Going with classical Arabic or a dialect

This one is a product-related decision more than it is technical, but it's worth noting. Using a dialect makes the app look more hip, but going with classical arabic reduces the confusion that can be introduced by the regional dialect differences.

Right-to-left alignment

Android can mirror your application if the user chooses a right-to-left locale as long as you use "start" and "end" instead of "left" and "right" in your code (for example, marginStart instead of marginLeft). You still need to go over it to make sure there are no surprises there.

Text alignment issues in strings.xml

This one can cause a major headache when trying to embed right-to-left words between <string> tags, especially if the translated sentence contains both right-to-left and left-to-right characters. I recommend using the translations editor instead of changing strings.xml directly, it makes it more tolerable.

It's highly recommended that you go through the app, screen by screen, to make sure everything is taken care of.