- Objective
- Contents
- Hands-on practice
- Summary
- References and further reading
Objective
In this section, you will learn how you can seamlessly internationalize your Titanium apps. We'll look specifically at how you can use external language files to display text in the user's preferred language.
Contents
Titanium provides a number of JavaScript functions in the Titanium.Locale
namespace for use in localization. It also provides String
formatting functions to handle dates, times, currencies, and more. You can even internationalize the name of your app itself. We'll look at those features, as well as how to test your language settings in this section.
Language strings
Rather than hard-coding strings into your project, you can use localized strings. Localized strings are replaced at runtime with values appropriate to the user's language. Titanium relies on resources files and string placeholders to accomplish this task.
In your Alloy project create a directory called i18n
. Inside the i18n
folder, create folders for each language your application will support. Name the folder according to the ISO 639-1 standard. For example, use en
for English, es
for Spanish, fr
for French, etc.
You can also add a suffix to the language directories for variants of languages. However, if you don't plan on adding multiple suffix-ed directories omit the suffix completely. Suffix the folder name with a dash followed by the country's ISO 3166-1 Alpha-2 code. For example, use en-US
for American English, en-CA
for Canadian English, en-GB
for British English, etc. Note that the OS may not support all regional languages.
Resource file structure
The string resource file closely mirrors the format of Android localization files, which have an XML-based format. The name
attribute represents the key for the string, and the text inside the XML node represents the value. A typical strings.xml
file would look like the following:
Resource files are processed and included with your application at build time by our Titanium build scripts. This means that these strings won't be processed if you use Xcode or Eclipse to build your project natively.
String resource names (the "keys") must begin with a letter and can contain digits, English characters, and the underscore. The contents (values) of each string resource must be UTF-8 compatible strings. While a given platform may not crash or throw an exception if you don't follow these rules, there's a good chance you will encounter some unexpected behavior.
Getting a localized string
Titanium provides two functions for obtaining a localized string from your resource files. Both take the key of the string requested as their first parameter. The L()
macro is a short form for Ti.Locale.getString():
To handle situations where no key exists in the strings.xml
file, the L() macro accepts a second argument to provide default hint
text:
Additionally, you can use the titleid
property of Titanium UI objects, such as labels or buttons, to directly reference a string resource without using the L()
macro. For example:
Replacing values in a localized string
You probably noticed the %1 and %2 placeholders in the sample strings.xml
file above. The String
object in Titanium contains a format
function which formats strings according to the IEEE printf specification. If your localization string contains replacement keys, as format_test
does in our example file above, you can replace values into your localized string like so:
Using the other replacement values from the printf spec, you can also do ordered values:
iOS-specific localizations
On iOS applications, you can localize the names of system buttons, such as "Save" and "Cancel", and the values of pList keys. You also need to modify the plist section of the tiapp.xml
file in order to submit your application to international App Stores.
Localize system buttons and submit to international App Stores
To localize system buttons or submit your application to international iTunes App Stores, add the CFBundleLocalizations
key to the iOS plist section of the project's tiapp.xml
file. Assign the CFBundleLocalizations
key an array of strings. Each string is the ISO 639-1 standard name of the language you want the application to support. For example, to support English, Spanish and French, add the following to the application's tiapp.xml
file:
Localize property list keys
To localize property list key values (Info.plist keys), add string
elements to the app.xml
file with the name attribute set to the property list key and the node text to the localized string to display. For example, the following file provides French versions of several dialog messages displayed to the user when asking for permission to use their location, contacts or calendar.
Set default language
The following key allows you to set the default language and region of your app which is very useful for the management of localization:
For more information about CFBundleDevelopmentRegion, please review iOS Developer Library - Core Foundation Keys and iOS Developer Library - Language IDs.
Internationalizing the app's name
One thing that has been a little tricky for some developers, is changing the application name based on locale.
For example, say you had an application named "Cat", but you wanted it to be "Gato" in Spanish locales, "猫" in Japanese, and so on. Let 's see how you would prepare your application to display its name appropriately for both iOS and Android distributions.
Changing locale for testing
Before learning to configure your apps to use localized strings for application names, let's first see how we can change locales manually for testing. Below you can find short videos for both iOS and Android that show you exactly how to do that.
Change Locale on iPhone from Appcelerator Video Channel on Vimeo.
App name localization
For iOS applications and if you are using Titanium SDK 3.2.0 and greater to build your Android applications, it's pretty simple. Use the standard method for creating localization paths, which means creating and using the i18n
directory like this:
In each of your language directories under i18n
, you'll include an app.xml
file that includes the necessary XML structure for defining the localized name of your app. That structure will look like this for each file:
And that's it. The next time you build your application, these localized strings will be used for your application name. If everything was configured correctly, you'll see the app name has changed based on the selected locale.
Android app name localization with Titanium SDK 3.1.x and older
If you are using Titanium SDK 3.1.x and older to build your Android apps, the name localization is a little more involved. First, we need to create language-specific resource folders explicitly for Android. To do so, we will create the platform/android/res/values-(language code)
directory structure, like this:
You'll notice in this case we are creating the Android native strings.xml
files, rather than the app.xml
files used by iOS. While the file names are different, the contents will be identical to those in the iOS files seen above.
Aside from the strings.xml
files, there's one more thing we need to add. To make your app use these localized strings, you need to modify the existing AndroidManifest.xml
. In order to do that, we need to add that custom manifest file, seen in the picture above at platform/android/AndroidManifest.xml
. The AndroidManifest.xml
file placed here should be a copy of the generated AndroidManifest.xml
file found in your project's build/android
directory. For more details on custom AndroidManifest.xml
files, check out this wiki entry on the topic.
Now open up platform/android/AndroidManifest.xml
and change the android:label
attributes of the <application>
and <activity>
elements from the defined value of your app name to the value @string/app_name
. Yeah, that was a lot of instructions all in one sentence, so here's an example to show you what I mean:
With these changes in place, you can now rebuild your app (probably best to give it a clean first) and you'll have a successfully localized application name.
Reference
This is how your home screens might look on Android and iOS when Japanese is the selected language.
And just in case my description was clear as mud, check out a Titanium project with these localizations set up first hand. Just go to the AppNameLocalization project repository on Github. It contains the very basic project discussed here. With all this, you should be well-equipped to distribute your apps in as many languages as you wish to support.
Links
- AppNameLocalization project on Github
- Appcelerator Wiki: Maintaining a Custom AndroidManifest.xml
Internationalizing image and file resources
Titanium does not provide built-in functions for internationalizing image and file resources. But you can easily accomplish this yourself. There are a couple of techniques you can employ:
Put the path and file name of each resource in the
strings.xml
file, then use that string in theimage
property, like this:Put your images into a set of folders that match the 2-letter ISO codes, and include that directory in the path with
Ti.Locale.currentCountry
, like this:
Date and time formatting
Titanium provides string formatting functions that you can use to create formatted dates and times. These include String.formatDate()
and String.formatTime()
. You can use these methods to format a JavaScript Date object to locale-specific strings.
At the time of this writing, natively, Android does not format dates in accordance with the official DateFormat documentation. Consequently, this will affect the corresponding short
, medium
and long
formats of Titanium String Formatting. Furthermore, when the device settings are set to certain languages, the translations can be wrong or fields in the incorrect order. For example, the following code is run on a device to demonstrate the issue:
This results in the following when the device is set to display in Polish:
Here, maja
is output for the month of May, whereas the Polish for May is actually Maj.
Similarly, when the device is set to English (United Kingdom), the month fields are incorrectly displayed before the dates:
This issue may well be fixed by the time you read this but, nevertheless, it gives us an opportunity to employ some of Titanium's tools to provide a workaround that gives you full control over the date format and translations.
We can use JavaScipt's Date object to return the date, which provides methods such as getDate()
and getFullYear()
to individually retrieve some of the information that we need. Although it does not specifically provide a method for returning the name of the month, we can derive it, in English, from the space-separated string output from Date.
To do so, we'll use the JavaScipt String.split() function. This will give us a key to lookup in the string.xml
files.
Using string substitution placeholders, dynamic values can be passed to the headingDate
string. This enables each locale to display the fields in a different order. In the following string.xml
files, Polish and English translations will return the date in the default order, whereas Spanish will result in a modified order.
Using this code, the date in Polish is translated correctly:
In addition, the recognized date format for the UK is produced:
Lastly, the date in Spanish has been reordered:
Other formatting and locale functions
Titanium also provides string formatting functions that you can use to create formatted currency and decimal numbers. These functions are String.formatCurrency()
and String.formatDecimal()
, respectively. The Ti.Locale module provides the Ti.Locale.formatTelephoneNumber()
method for getting a locale-formatted phone number. That module also includes functions for retrieving the correct currency symbol and currency code for the user's locale.
Testing languages
When building internationalized apps, you'll need to test each of the supported languages. You can do so either on-device or in the simulator/emulator. In each case, you configure the device's language settings to change locales.
To set the language on iOS:,
- Open Settings.
- Tap General, then Language & Region.
- Under iPhone Language, select the language to use, then tap Done.
- iOS will ask you to confirm your changes. Tap Change to....
Optionally, in Settings, tap General, Language & Region, Region Format to specify your locale format for dates and times.
To set the language on Android:
- Open Settings.
- Tap Language & input.
- Tap Language and select the language to use.
Hands-on practice
Goal
In this activity, you will create an internationalized app that outputs language-specific strings and test that in the simulator/emulator.
Steps
- Create a new Titanium Mobile project named "Language Test" with an app ID of your choice.
- Using your computer's file management tools, create an
i18n
directory at the/app
directory of your project. In that directory, create two directories:en
andes
. - Using Studio, within the
en
directory, create astrings.xml
file following the format shown above. Add three key/value pairs:- language = Language
- test = Test
- tab = Tab
- In the
es
directory, create a matching copy ofstrings.xml
except that the values should be as follows:- language = Lengua
- test = Prueba
- tab = Lengüeta
- In the
es
directory, create anapp.xml
file following the format shown above. Add the necessary key and value to specify "Lengua Prueba" as the translated version of the app's name. (This won't have any effect if you're building for Android.) - In app.js, on tab 1, add the necessary code to output the internationalized "Language Test" string as the text of
label1
. - On tab 2, change the text of
label2
to output today's date using theString.formatDate()
method. - For both tab 1 and tab 2, update the text to use the internationalized "tab" key plus the tab's number.
- Build the app for the simulator/emulator. The label and tab text should output in English (unless your emulator is already set to output text in Spanish). Close the app.
- Change the simulator/emulator's settings to display text in Spanish. Open the app. Label and tab text should now be in Spanish. On iOS, the app's icon should be labeled in Spanish as well.
Summary
In this chapter, you learned how to internationalize your app, including using language strings, internationalizing the app name, and formatting strings, dates, and currency values.
1 Comment
Ricardo
Pretty good, however It would be better if you start how to do it with the Titanium SDK 3.1.x and older because the docs in the official website does not include it http://docs.appcelerator.com/titanium/3.0/#!/guide/Localization it's a waste of time for any who visit that link.