Android SDK Building A Localized Phrasebook

All Topics Find tutorials, courses, and more...
Code Categories Learning Guides
ANDROID SDK
Android SDK: Building a

Localized Phrasebook
by Shane Conder & Lauren Darcey 25 May 2010
11 Comments
In this tutorial, you will learn how to create and use alternative resource files with an
Android application called One Minute Phrasebook. This application displays certain
text and graphics based upon the Android system language/locale setting.
open in browser PRO version Are you a developer? Try out the HTML to PDF API pdfcrowd.com
Before You Begin
The authors are assuming the reader has some basic knowledge of Android and
has all of the necessary tools, such as Eclipse and the Android SDK, installed and
working. The examples given here are engineered to show how Android project
resources can be localized. Specifically, this tutorial will show you how to include
resources for different languages and locales.
Note: The code for the OneMinutePhrasebook application is also available on

Google Code.
Step 1: Create the OneMinutePhrasebook

Application
Begin by creating a new Android project.
To do this within Eclipse, choose File->New Android Project to launch the Android
project wizard.
Name the project: e.g. Phrasebook
Choose an appropriate Build Target, such as Android 2.1.
Name the application: e.g. One Minute Phrasebook
Name the package: e.g. com.mamlambo.article.phrasebook
Create a launch Activity: e.g. PhrasebookActivity
Step 2: Configure the Application for Debugging
You will be debugging this application, so you need to set the Debuggable attribute
in the Android Manifest file to true.
Step 3: Create a Debug Configuration
You will want to be able to easily launch the application in the Android emulator and
on the device from Eclipse, so you need to create a Debug Configuration.
To do this within Eclipse, choose Run->Debug Configurations....
Double click on the Android Project option.
Name your new configuration: Phrasebook Test
Select the project: Phrasebook
Step 4: Create Default String Resources
The One Minute Phrasebook displays the locale as well as several strings (Hello,
Goodbye, Please, Thank You and Help!) on the screen. Therefore, you need
to add a bunch of string resources to the /res/values/strings.xml file. Specifically,
add one string for each phrase, as well as a label for each phrase. Also, add strings
for the Flag (label), Map (label), and CIA World Factbook link (more on this in a
moment).
For default strings, we use one of the most common languages understood around
the worldEnglish. (Certainly, you could choose another language for your default, if
you like.)
The resulting strings.xml file should look something like this:
01 <?xml version="1.0" encoding="utf-8"?>

02 <resources>
03 <string name="app_name">The One Minute Phrasebook </
string>
04
05 <string name="locale_label">Locale: </string>
06 <string name="locale">"World-Wide" </string>
07
08 <string name="hello_label">Greet Someone: </
string>
09 <string name="hello">Hello!</string>
10
11 <string name="goodbye_label">Say Farewell: </string>
12 <string name="goodbye">Goodbye!</string>
13
14 <string name="please_label">Say Please: </string>
15 <string name="please">Please </string>
16
16
17 <string name="thankyou_label">Thank Someone: </
string>
18 <string name="thankyou">Thank You! </string>
19
20 <string name="help_label">Call for Aid: </string>
21 <string name="help">Help! </string>
22
23 <string name="flag_label">Flag: </string>
24 <string name="map_label">Map: </string>
25
26 <string name="cia_factbook_label"
>CIA World Factbook URL: </
string
27 <string name="cia_factbook_url"
>"https://www.cia.gov/library/publications/the-wo
28 </resources>
These are the default string resources that are used by this application. Many
applications use only default resources.
Step 5: Create Other Resources

The One Minute Phrasebook application also requires several other types of
resources. Specifically:
Some color resources for TextView text colors (/res/values/colors.xml)

Some dimension resources for TextView text size (/res/values/dimens.xml)
Two graphics files: one for the map and one for the flag
(/res/drawable/flag.png and /res/drawable/map.png)
You can either add these resources now or as you build the layout. The flag and
map images used in this tutorial were acquired from public domain images available
on the CIA World Factbook website.
For the default cause, we will say the locale is World-wide, and display a graphic
with a bunch of world maps, and a map of the planet.
Step 6: Design the One Minute Phrasebook User
Interface
Next, turn your attention to designing the user interface of the application. The One
Minute Phrasebook is a very simple application with just one screen. The screen
displays some useful phrases, a flag and a map for the country, and a link to the
CIA World Factbook website for the appropriate country.
Note: For this application, we use an Android Virtual Device (AVD) profile to closely
match that of the Nexus One, with its 800x480 screen. Feel free to create an AVD
to match whichever Android device you have on hand to test with.
Step 7: Implementing the User Interface

This application has just one screen, defined within the /res/layout/main.xml file.
This is the file you need to edit.
In this case, we want nice, formatted columns, so consider using the TableLayout
control to format the TextView and ImageView controls containing the phrase, flag,
map and link to the CIA World Factbook.
The resulting main.xml layout file should look something like this:
002 <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android
003 android:orientation="vertical" android:layout_width ="fill_parent"
004 android:layout_height="fill_parent">
005 <ScrollView android:id="@+id/ScrollView01"
006 android:layout_width ="wrap_content" android:layout_height="wrap_content"
007 android:layout_gravity ="center">
008 <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android
009 android:orientation ="vertical" android:layout_width="fill_parent"
010 android:layout_height ="fill_parent">
011 <TableLayout android:id="@+id/TableLayout01"
012 android:layout_margin="@dimen/phrase_margin"android:layout_height
013 android:layout_width="fill_parent" android:stretchColumns
014 <TableRow android:id="@+id/TableRow01"
015 android:layout_height ="wrap_content" android:layout_width
016 <TextView android:id="@+id/TextView_LocaleLabel"
017 android:layout_width ="wrap_content" android:layout_height
018 android:text="@string/locale_label"android:textSize
019 android:textColor="@color/locale_color" ></TextView
020 <TextView android:id="@+id/TextView_Locale"
021 android:layout_height ="wrap_content" android:text
022 android:textSize="@dimen/phrase_size"android:textColor
023 android:layout_width ="wrap_content" android:layout_gravity
024 </TableRow>
027 <TextView android:id="@+id/TextView_HelloLabel"
029 android:text="@string/hello_label"android:textSize
030 android:textColor="@color/label_color" ></TextView
031 <TextView android:id="@+id/TextView_Hello"
032 android:layout_height ="wrap_content" android:text
032 android:layout_height="wrap_content" android:text
033 android:textSize="@dimen/phrase_size"android:layout_width
034 android:textColor="@color/phrase_color"android:layout_grav
035 </TableRow>
037 android:layout_width="wrap_content" android:layout_height
038 <TextView android:id="@+id/TextView_GoodbyeLabel"
040 android:text="@string/goodbye_label"android:textSize
041 android:textColor="@color/label_color"></TextView
042 <TextView android:id="@+id/TextView_Goodbye"
044 android:text="@string/goodbye" android:textSize
046 </TableRow>
049 <TextView android:id="@+id/TextView_PleaseLabel"
051 android:text="@string/please_label"android:textSize
053 <TextView android:id="@+id/TextView_Please"
055 android:text="@string/please" android:textSize
057 </TableRow>
060 <TextView android:id="@+id/TextView_ThankyouLabel"
062 android:text="@string/thankyou_label"android:textSize
064 <TextView android:id="@+id/TextView_Thankyou"
064 <TextView android:id="@+id/TextView_Thankyou"
066 android:text="@string/thankyou" android:textSize
068 </TableRow>
071 <TextView android:id="@+id/TextView_HelpLabel"
073 android:text="@string/help_label"android:textSize
075 <TextView android:id="@+id/TextView_help"
077 android:text="@string/help" android:textSize
079 </TableRow>
080 </TableLayout>
081 <TableLayout android:id="@+id/TableLayout02"
082 android:layout_margin="@dimen/phrase_margin"android:layout_height
083 android:layout_width="fill_parent">
086 <TextView android:id="@+id/TextView_FlagLabel"
088 android:text="@string/flag_label"android:textSize
090 </TableRow>
093 <ImageView android:id="@+id/ImageView01"
095 android:src="@drawable/flag" android:adjustViewBounds
096 android:saveEnabled="true"></ImageView>
096 android:saveEnabled="true"></ImageView>
097 </TableRow>
100 <TextView android:id="@+id/TextView_MapLabel"
102 android:text="@string/map_label"android:textSize
104 </TableRow>
107 <ImageView android:id="@+id/ImageViewMap"
109 android:src="@drawable/map"></ImageView>
110 </TableRow>
113 <TextView android:id="@+id/TextView_CIAFactbookLabel"
116 android:text="@string/cia_factbook_label"></
117 </TableRow>
120 <TextView android:id="@+id/TextView_help"
123 android:layout_gravity="right" android:text
124 android:autoLink="web"></TextView>
125 </TableRow>
126 </TableLayout>
127 </LinearLayout>
128 </ScrollView>
128 </ScrollView>
129 </LinearLayout>
Step 8: Running the Application

Its time to run the application for the first time. To do so from Eclipse, choose Run-
>Debug Configurations. Select the Phrasebook Test configuration and click the
Debug button.
Step 9: Changing the Device or Emulator Locale
Now its time to explore the language settings of your emulator or device. To view
and change the language/locale settings from the Home screen, click the Menu
button and choose Settings->Language and Keyboard->Select Locale.
Try changing the locale to a foreign language you are familiar with.
Warning: Keep in mind that if you change the language and leave the Settings, you
will need to be able to navigate back to the settings screen in that language.
Memorizing, or writing down, the keystrokes to do this can simplify doing so.
Note how all the menus change to that language. Run the One Minute Phrasebook
application in this locale. Note how the application does not appear any different
than before you changed the localeit still appears in English.
Now, change back to your favored locale. Mine is English (United States).
Note: The emulator has all locale options available in a given version of the Android
SDK. However, specific devices may have a limited set of locales to choose from.
Step 10: Understanding How Android Manages

Resources
Each time a screen is drawn within an Android application, the Android operating
system attempts to match the best possible project resource for the job. In many
cases, applications provide only one set of resourcesthe default resources.
When alternate resources are included with an application as part of their package,
the Android operating system always attempts to load the most specific resources
available.
Alternate resources can be created for many different criteria, including, but not
limited to, languages and regions, screen characteristics and device input methods.
Some common alternative resources are those for languages, locales and screen
orientation (layouts especially). Criteria are organized hierarchically and each type
of criteria can be used as a suffix on the appropriate project resource directory
name.
Alternate resources must use the same names as the default resources. Android
resource resolution is best shown by example. In this tutorial, we focus only on
creating alternate resources for specific languages and regions.
Step 11: Create Alternate String Resources for

the French-Speaking Countries
Now lets say you want to add support for French-speaking regions. You can easily
do this by adding alternate resource strings to the project. For example, you might
leave the phrase labels in English, but translate the actual phrases into the French
language.
You can add language resources to any project by creating specially named project
directories. Simply take the existing project directory name (such as /res/values)
and tack on a dash followed by the two letter language code, as defined in ISO 639-
2. So, for example, English is en, French is fr, Spanish is es, German is de, etc.
You can add a single set of French translated strings in the /res/values-fr/strings.xml
file. These strings will be loaded whenever a French-speaking locale setting is
enabled. Any other locale settings will continue to use the default strings.
Each of the alternate resource strings must have the same name as the default
resource used (stored in /res/values/strings.xml). The Android operating system will
choose the most specific resource available at runtime. You do not need to provide
translations for all strings, just the ones you want altered when a French-speaking
locale setting is chosen.
The resulting /res/values-fr/strings.xml file should look something like this:

2 <resources>
3 <string name="hello">Bon jour!</string>
4 <string name="goodbye">Au revoir!</string>
5 <string name="please">"S'il vous plat"</string>
6 <string name="thankyou">Merci!</string>
7 <string name="help">Au Secours!</string>
8 </resources>
Note that you may need to quote resource strings if they contain single quotes
themselves (such as S'il vous plat).
Step 12: Create Alternate String Resources for

Specific Countries
Now that youve determined the French string resources (the phrases) that can be
shared across all French-speaking locales and regions, you want to create some
alternate string resources for specific countries: Belguim, Canada, France and
Switzerland.
Each country will need:
A locale region string

A CIA World Factbook URL string
The Android platform supports language-specific alternative resources (such as

those created in the previous step). However, you cannot create region-specific
resources without the language. Instead, you must include the language and the
country code in the resource directory name.
To create resources specific to a region, you must use its language (in this case
fr), followed by a dash, followed by its region code in the form rXX where XX is
the region code for the country as defined by ISO 3166-1-alpha-2 code.
For example, the language and region codes for the French-speaking countries
supported in Android would be:
Belgium: fr-rBE
Canada: fr-rCA
France: fr-rFR
Switzerland: fr-rCH
So, for example, you can create a strings.xml file in the /res/values-fr-rBE project
directory for string values specifically for the French (Belgium) locale setting.
/res/values-fr-rBE/strings.xml might look like this:

2 <resources>
3 <string name="locale">Belgium</string>
4 <string name="cia_factbook_url">https://www.cia.gov/library/publications/the-wor
5 </resources>
Step 13: Create Alternate Drawable Resources

for Specific Countries
Alternate resources can be created for other types of data besides strings. You can
create alternate resources for any type of resource, including strings, dimensions,
colors, drawable resources and other types. You simply use the same project
resource directory hierarchy rules.
So to add flag and map drawable resources for each country (Belguim, Canada,
France, and Switzerland), you need to create four new directories under the project:
Store the Belgian flag.png and map.png graphics in the /res/drawable-fr-rBE/

directory.
Store the Canadian flag.png and map.png graphics in the /res/drawable-fr-rCA/
directory.
Store the Swiss flag.png and map.png graphics in the /res/drawable-fr-rCH/
directory.
Store the French flag.png and map.png graphics in the /res/drawable-fr-rFR/
directory.
Note that the drawable file names must match the default drawable file names
(those stored in /res/drawable) exactly.
Your project should now be organized like this:
Step 14: Re-running with a French-speaking
Locale
In your emulator or on your device, change the Locale to one of the French options
(Franais (France), Franais (Canada), Franais (Belguim), Franais (Switzerland).)
Note: For those not versed in French, you can return to the locale settings menu
from the Home screen by choosing: Menu->Paramtres->Langue et clavier-
>Langue et rgion.
Re-run the One Minute Phrasebook application and view the results. Note how the
appropriate French strings are loaded for all French languages. Also note how the
specific region dictates which country information is displayed within the application.
The figure shows what happens when you choose Franais (France).
Step 15: Where to Go From Here
Internationalization forces design choices on the development team. For example,
will you build one big project for all languages, or will you break the applications up
by region? For some projects with light internationalization, you may be able to get
away with one project with all internationalized resources. For deep
internationalization, you may need to reorganize projects so that no application
becomes too large or cumbersome for the user.
You may have noted that in all this internationalization work, we never once touched
the java source files of the project. This is important to note, because it means that
the work of internationalizing an application may fall not to a developer who knows
how to use Eclipse and the Android tools well, but to someone else who will need
some training on how Android internationalization works, how resources can be
layered, and the drawbacks of over-internationalizing (resulting in very large
package files with many graphics and such). On the plus side, this leaves
developers free to do what they do best: developing code.
Lastly, you likely noted that the Android internationalization structure isnt perfect
especially for countries with multiple official (and unofficial) languages. It makes little
sense to have to include the same graphics (flag and map) in both an en-rCA and
fr-rCA directories for English and French speaking Canadians. However, you can
work around these limitations by programmatically determining the locale and
loading the appropriate graphic files yourself. That, however, is for another tutorial.
You can find a more complete explanation of Android resource resolution in the
Android SDK documentation here.
Conclusion
In this tutorial, you learned how to create and use alternative resource files with an
Android application called One Minute Phrasebook. This application displays certain
strings and graphics based upon the Android system language/locale setting. You
learned about how the Android operating system resolves resources and chooses
the most appropriate resource available at runtime. You also learned how to
organize resources efficiently in order to provide your worldwide users with the best
possible application experience.
We hope you enjoyed this tutorial and look forward to your feedback!
Advertisement
About the Authors

Mobile developers Lauren Darcey and Shane Conder have coauthored several
books on Android development: an in-depth programming book entitled Android
Wireless Application Development and Sams TeachYourself Android Application
Development in 24 Hours. When not writing, they spend their time developing
mobile software at their company and providing consulting services. They can be
reached at via email to androidwirelessdev+mt@gmail.com, via their blog at
androidbook.blogspot.com, and on Twitter @androidwireless.
Need More Help Writing Android Apps? Check out our

Latest Books and Resources!
Advertisement
Difficulty: Suggested Tuts+ Course

Beginner
Length:
Short
Categories:
Android SDK Mobile Development
Translations Available:
Tuts+ tutorials are translated by our community

members. If you'd like to translate this post into
Multi-Platform Apps In C# With Start
another language, let us know! Xamarin
Download Attachment
Related Tutorials
How To Localize an Android

Application
Code
About Shane Conder & Lauren Darcey
Mobile developers Lauren Darcey and
Shane Conder have coauthored numerous
Use Text-to-Speech on Android to
books on Android development. Our latest Read Out Incoming Messages
books include Sams Teach Yourself Android Code
Application Development in 24 Hours (3rd Edition),
Introduction to Android Application Development:
Android Essentials (4th Edition), and Advanced
Google Play Game Services:
+ Expand Bio
Leaderboards
Code
Jobs
Web Developer / Site Management

at Zanes Law in Phoenix, AZ, USA
PHP Coder with Magento Knowledge

at Yoginet Web Solutions in New Delhi,
Delhi, India
Advertisement
Envato Market Item
11 Comments Mobiletuts+
Sort by Best
Join the discussion
duongdemui a year ago

Thanks. It's so great
Reply Share
Burt K. 2 years ago

Really Great! Thanks!
Reply Share
Horrorgoogle 3 years ago

Wow..its a great.
Reply Share
Matt 4 years ago

Thanks for putting this up. I've been running through a few of your tutorials and after a few hic ups they've
working out great.
One question I have is how would you implement a language that isn't roman alphabet based, ie Janpanes
(Both Mandarin and Cantonese), etc?
(Both Mandarin and Cantonese), etc?
Reply Share
Dliswa 4 years ago

Hi all
I am aware of Creating a new values directory for the language with the suffix of the language code. For g
values-de or french: values-fr then copy our string.xml into that and translate each entry. And this works b
Phone Localization settings
I wanted to know if we can bypass the phone setting and and make the user select his required language
app?
My requirement is, i want to give a language selection option inside my app, and make the user select the
he wants for the app.. how to dynamically switch between the string.xml (for different languages) ???
Problem is i wanna change language just inside in my application.
thanks in advance
Reply Share
dmitry 4 years ago

> It makes little sense to have to include the same graphics (flag and map) in both an en-rCA and fr-rCA d
for English and French speaking Canadians.
maybe it's possible not to place actual files in directories but links to em?
Reply Share
Andrey 5 years ago
open in browser PRO version Thank

Are you you very Try
a developer? much
out the for
HTMLthis wonderfully
to PDF API structured and easy to follow tutorial pdfcrowd.com
Thank you very much for this wonderfully structured and easy to follow tutorial
Reply Share
Aafrin 5 years ago

Awesome tutorial. suitable for beginners like me....
Reply Share
dragon noir 5 years ago

Nice tuto
Reply Share
ZERO-Mohammed Morsi 5 years ago

That&#039s awesome
it&#039s nice start :)

Reply Share
Austin Pickett 5 years ago

Great unique starting article for any android-enthusiast.
Reply Share
Subscribe d Add Disqus to your site Privacy
Facebook App
Events
Learn How People Engage
with Your App and Measure
Performance.
Advertisement
18,892 Tutorials 461 Video Courses

Teaching skills to millions worldwide.
Follow Us Email Newsletters
Get Tuts+ updates, news, surveys &

offers.
Email Address
Help and Support Email Address
FAQ
Subscribe
Terms of Use
Contact Support Privacy Policy
About Tuts+
Advertise
Teach at Tuts+
Custom digital services like logo design, WordPress installation, video

production and more.
Check out Envato Studio
Build anything from social networks to file upload systems. Build faster
with pre-coded PHP scripts.
Browse PHP on CodeCanyon
2014 Envato Pty Ltd. Trademarks and brands are the property of their respective
owners.

Android SDK Building A Localized Phrasebook

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Android SDK Building A Localized Phrasebook

Uploaded by

Copyright:

Available Formats

All Topics Find tutorials, courses, and more...

Code Categories Learning Guides

Android SDK: Building a

Note: The code for the OneMinutePhrasebook application is also available on

Step 1: Create the OneMinutePhrasebook

Name the project: e.g. Phrasebook

Name the application: e.g. One Minute Phrasebook

Name the package: e.g. com.mamlambo.article.phrasebook

Create a launch Activity: e.g. PhrasebookActivity

To do this within Eclipse, choose Run->Debug Configurations....

Double click on the Android Project option.

Name your new configuration: Phrasebook Test

Select the project: Phrasebook

The resulting strings.xml file should look something like this:

01 <?xml version="1.0" encoding="utf-8"?>

Step 5: Create Other Resources

Some color resources for TextView text colors (/res/values/colors.xml)

Step 7: Implementing the User Interface

Step 8: Running the Application

Step 10: Understanding How Android Manages

Step 11: Create Alternate String Resources for

The resulting /res/values-fr/strings.xml file should look something like this:

1 <?xml version="1.0" encoding="utf-8"?>

Step 12: Create Alternate String Resources for

Each country will need:

A locale region string

The Android platform supports language-specific alternative resources (such as

/res/values-fr-rBE/strings.xml might look like this:

1 <?xml version="1.0" encoding="utf-8"?>

Step 13: Create Alternate Drawable Resources

Store the Belgian flag.png and map.png graphics in the /res/drawable-fr-rBE/

Your project should now be organized like this:

About the Authors

Need More Help Writing Android Apps? Check out our

Difficulty: Suggested Tuts+ Course

Android SDK Mobile Development

Tuts+ tutorials are translated by our community

How To Localize an Android

Web Developer / Site Management

PHP Coder with Magento Knowledge

Envato Market Item

Join the discussion

duongdemui a year ago

Burt K. 2 years ago

Horrorgoogle 3 years ago

Matt 4 years ago

Dliswa 4 years ago

Problem is i wanna change language just inside in my application.

dmitry 4 years ago

Andrey 5 years ago

open in browser PRO version Thank

Aafrin 5 years ago

dragon noir 5 years ago

ZERO-Mohammed Morsi 5 years ago

it&#039s nice start :)

Austin Pickett 5 years ago

Subscribe d Add Disqus to your site Privacy

18,892 Tutorials 461 Video Courses

Follow Us Email Newsletters

Get Tuts+ updates, news, surveys &

Custom digital services like logo design, WordPress installation, video

You might also like