Localizing and translating your application

 

This tutorial focuses on adding localization and translations to your native Cascades app.  Many of you already know that Blackberry has a tremendous following outside of the English speaking world.  Places like the Middle-East, Indonesia and South America have a great BlackBerry userbase.  Even though you could be building an awesome app it's important to understand who your customers are and how you can cater to them.  If you're building a complicated app with lots of labels and text throughout you may want to consider localizing your application and providing translations for other languages. It's a feature that I like to incorporate into my applications so that users can understand what's going on while using my apps.

The project is attached at the end of this tutorial for your pleasure and to use as a starting point if you'd like.  But first I would like to highlight some of the main files we will be touching:

  • applicationui.cpp
  • applicationui.hpp
  • main.qml
  • ThemeSample.pro (or *Your app name*.pro)

 

Screenshots

 

 

 

 There are two parts to this tutorial.  If you start your project from scratch from within Momentics your project likely already has all the code setup, in which case you can skip part A and go directly to part B to learn how to choose what languages to translate to and input translations into your app.

 

Part A

applicationui.cpp

here is where we setup the translator and LocaleHandler.  Add the following code to your applicationui.cpp:

 
#include <bb/cascades/LocaleHandler>

 
 
m_pTranslator = new QTranslator(this); m_pLocaleHandler = new 
LocaleHandler(this); 


 
 
if(!QObject::connect(m_pLocaleHandler, 
 SIGNAL(systemLanguageChanged()), this, 
SLOT(onSystemLanguageChanged()))) { // This is an abnormal 
situation! Something went wrong! // Add own code to recover 
here qWarning() << "Recovering from a failed connect()"; 
} onSystemLanguageChanged(); 


 
 
void applicationui::onSystemLanguageChanged() { QCoreApplication::instance()-
>removeTranslator(m_pTranslator); // Initiate, load and install the 
application translation files. QString locale_string = QLocale().name(); 
QString file_name = QString("persistentobjects_%1").arg(locale_string); 
if (m_pTranslator->load(file_name, "app/native/qm")) { 
QCoreApplication::instance()->installTranslator(m_pTranslator); } } 


applicationui.hpp

here is where we delcare the translator and LocaleHandler.  Add the following code to your applicationui.hpp:


#include <bb/cascades/LocaleHandler>
 
 
namespace cascades { class LocaleHandler; class Application;


 
 
 
private slots: void onSystemLanguageChanged(); 



 
 
QTranslator* m_pTranslator; bb::cascades::LocaleHandler* 
m_pLocaleHandler; 


Part B

main.qml

For text to be translated you must add a bit of code to your text so that it automatically gets pulled and is told how and when to change that text as well as to what to change it to based on either language, locale or both. Add the following code around any text string to retranslate the text whenever the OS language is changed.

qsTr("your text") + Retranslate.onLanguageChanged

Conversely if you want to change the text based on Locale like what country the OS is targeting you can add the following code.

qsTr("your text") + Retranslate.onLocaleChanged

Depending on what type of application you are creating certain rules and regulations may apply to one country and not another, this would allow you to build one app and have certain things show or be hidden in the text based on the OS Locale

app.pro

To build .ts files for you to edit and change for your translations you'll need to target them in your .pro file. Add the following code to the bottom of your .pro file

TRANSLATIONS = \
    $${TARGET}_fr.ts \
    $${TARGET}_es.ts \
    $${TARGET}_en.ts \
    $${TARGET}.ts

This code tells what language .ts files will be built. For a comprehensive list of supported language codes in BlackBerry 10 please have a look here.

translation.ts

The .ts file is really where you actually do the translations for your app. The following is an example of a string of text that you marked in the QML being automatically pulled into the .ts file when you build your app

"<"ts version="2.0" language="es_ES"">"
"<"context">"
    "<"name">"main"<"/name>"
    "<"message">"
        "<"location filename=""../assets/main.qml"" "line="25"">"
        "<"source /">"Theme Selection:"
        "<"translation type=""unfinished"">"<"/translation">"
    "<"/location">"<"/message">"
"<"/context">"
"<"/ts">"

You may have noticed that it shows at the very top what language will pull this translation as well as what the text encoding is. Don't worry about the encoding right now. Just use the default encoding, you may have to adjust the encoding depending on if you use cyrillic or chinese languages. You will also notice that under the it shows what QML the following translations are from (main.qml) and each translation is found between a showing the location and line it is found on as well as what the original source text is. Underneath this is the translation portion. THe default will say translation type="unfinished" this means there is no translation. To add your own translation you can change this to with your actual translation between the translation brackets like so.

"<"ts version="2.0" language="es_ES"">"
"<"context">"
    "<"name">"main"<"/name>"
    "<"message">"
        "<"location filename=""../assets/main.qml"" "line="25"">"
        "<"source /">"Theme Selection:"
        "<"translation">"Selección de tema:"<"/translation">"
    "<"/location">"<"/message">"
"<"/context">"
"<"/ts">"

Conclusion

Translations are a very important part of app development especially since more than half the world speaks a different language. The top three languages in the world are Mandarin, Spanish and English. If you're going to focus on one language make sure to keep in mind which one will give you the best coverage based on your audience and who you're trying to aim your app for. It's also important to target at least one of the languages that BlackBerry recommends here if you want to get your app Built for BlackBerry approved.  For more information on Localizing your app you can also check the online documentation on the BlackBerry developer site here.  You can also download my sample below for a depper look.

 

Brandon Orr

Transportation Planner (University of Waterloo Graduate) & Blackberry 10 Developer (PinGuin App) part of the open source BB team.

Website: appworld.blackberry.com/webstore/vendor/65375/

Leave your comments

Post comment as a guest

0
  • No comments found
Subscribe to the official OSBB BBM Channel!

osbbchannelQR

C00013E89

Back to top