Localization Guide

Overview

To reach out to the users in the global market, it is essential to provide your apps and services in many different languages. There are a few things to keep in mind when you localize your apps or services for webOS Open Source Edition (OSE).

  • Write code using the internationalization (i18n) library provided by webOS OSE.
    • This page provides the links to external pages with detailed information on libraries and coding rules for each programming language.
  • Prepare multi-language string resources in the guided format.
    • You can prepare string resources yourself, or use the localization tool to make string resources generated at build time.
Locale identification in webOS OSE

Locales in webOS OSE follow the BCP 47 standard. A locale is represented as a language tag, typically in language-[script]-[region] format, where the language code is a required field. For example,

  • ko: Korean
  • fr-FR: French - France
  • fr-CA: French - Canada
  • zh-Hant-HK: Chinese - Chinese Traditional - Hong Kong

For more information about BCP 47 and the language tag, refer to the following:

Applying localization to your project

In order to apply localization to your project, you need to follow the steps below:

  1. Write codes using the internationalization(i18n) library
  2. Prepare XLIFF files
  3. Prepare the localization tool
  4. Update Recipes to apply webOS build

Here's a detailed explanation.

(1) Write codes using the internationalization(i18n) library

In order to get localized strings on your project, Strings need to be wrapped with a function appropriate to the file type. Please refer to the following guide: Writing Localizable Code.

Note
If you want to create resources manually without using a localization tool, Please skip the next steps and go to the Resource Formats section.

(2) Prepare XLIFF files

(2-1) What is XLIFF?

XLIFF (XML Localization Interchange File Format) is an XML format file that contains the actual translation data. XLIFF must exist for each locale. The following shows an example of XLIFF, which represents the translation data for ‘en-US’ locale of ‘javascript’ application named ‘sample'. The localization tool of webOS OSE is based on XLIFF version 2.0.

en-US.xliff (web)
<?xml version="1.0"?>
<xliff xmlns="urn:oasis:names:tc:xliff:document:2.0" version="2.0" srcLang="en-KR" trgLang="en-US">
 <file id="sample_f1" original="sample">
  <group id="sample_g1" name="javascript">
   <unit id="sample_1">
    <segment>
     <source>String 1</source>
     <target>Translation 1</target>
    </segment>
   </unit>
   <unit id="sample_2">
    <segment>
     <source>String 2</source>
     <target>Translation 2</target>
    </segment>
   </unit>
  </group>
 </file>
</xliff>

The following table describes the key elements and attributes of XLIFF.

Element/AttributeDescription
<xliff> - srcLangSource language - the code of the language, in which the text to be translated is expressed
<xliff> - trgLangTarget language - the code of the language, in which the translated text is expressed
<group> - nameProgramming language type - “javascript”, “c”, “cpp”, “x-qml” (for Qt/QML)
<source>Source string - the text to be translated
<target>Target string - the translated text
Note
  • The source language is defined as en-KR.
  • basename : The short name for the application. The right-most word of the dot-connected string of the application name becomes the basename.
    • If an application name is com.webos.app.home, the basename is home.
    • If an application name is sample, the basename is sample.

(2-2) How to write XLIFF files?

When writing an XLIFF file, the value of original attribute must match the basename. In addition, the value of name attribute in group must match the type of programming language used for developing the apps or services, as follows:

en-US.xliff
<?xml version="1.0"?>
<xliff xmlns="urn:oasis:names:tc:xliff:document:2.0" version="2.0" srcLang="en-KR" trgLang="en-US">
 <file id="sampleJS_f1" original="sampleJS">
  <group id="sampleJS_g1" name="javascript">
...
en-US.xliff (c)
<?xml version="1.0"?>
<xliff xmlns="urn:oasis:names:tc:xliff:document:2.0" version="2.0" srcLang="en-KR" trgLang="en-US">
 <file id="samplec_f1" original="samplec">
  <group id="samplec_g1" name="c">
...

For Qt/QML apps, the group name is “x-qml”.

en-US.xliff (qml)
<?xml version="1.0"?>
<xliff xmlns="urn:oasis:names:tc:xliff:document:2.0" version="2.0" srcLang="en-KR" trgLang="en-US">
 <file id="sampleqml_f1" original="sampleqml">
  <group id="sampleqml_g1" name="x-qml">
...

(2-3) Where to put the XLIFF files?

XLIFF files for each locale must be placed in the directory with the same name as the base name, as shown below:

XLIFF Directory Structure
com.webos.app.sample
├── sample
     ├── af-ZA.xliff
     │── ar-SA.xliff
...
     │── en-GB.xliff
     │── en-US.xliff
...
     └── zh-Hans-CN.xliff

(3) Prepare the localization tool

The localization tool parses source codes along with XLIFF files, and generates string resources in formats required by each programming language.

Therefore, you must provide translation data in XLIFF format to use the localization tool. In order to run the localization tool on your machine, you need to check out the localization tool repository and then install the plugins.

(3-1) Install the localization tool

webOS OSE's localization tool is named loctool.

In order to install the loctool, make sure you have Node.js installed on your machine and in your path, as this is used to run the code (Use 7.0 or later). Once Node.js is installed, you can install the loctool.

By checking out the ilib-loctool-webos-dist repository, you can download all related plugins including loctool.

Installation
 git clone https://github.com/iLib-js/ilib-loctool-webos-dist
 cd ilib-loctool-webos-dist
 npm install
 // or to install it globally: npm install -g

(3-2) Prepare a configuration file

To run the tool, create a project.json configuration file for each project and place it in the root of that project.

The loctool recursively search the given directory (current dir by default) for project.json files to find the roots of the projects. The root of each project will be recursively searched for localizable files.

For more information about loctool configuration, please visit the loctool project site.

Here's an example for a webOS application.

project.json (Web)
{
    "name": "com.webos.app.home",
    "id": "home",
    "projectType": "webos-web",
    "sourceLocale": "en-KR",
    "pseudoLocale": ["zxx-XX", "zxx-Cyrl-XX", "zxx-Hans-XX", "zxx-Hebr-XX"],
    "resourceDirs": {
         "json":"resources"
     },
     "resourceFileTypes": {
         "json":"ilib-loctool-webos-json-resource"
     },
    "plugins": [
         "ilib-loctool-webos-javascript",
         "ilib-loctool-webos-appinfo-json"
     ],
     "excludes": [
         "*"
     ],
     "includes": [
         "src"
     ]
}
project.json (QML)
{
    "name": "ime-manager",
    "id": "imemanager",
    "projectType": "webos-qml",
    "sourceLocale": "en-KR",
    "pseudoLocale": ["zxx-XX", "zxx-Cyrl-XX", "zxx-Hans-XX", "zxx-Hebr-XX"],
    "resourceDirs": {
         "ts":"resources"
     },
     "resourceFileTypes": {
         "ts":"ilib-loctool-webos-ts-resource"
     },
    "plugins": [
         "ilib-loctool-webos-qml",
         "ilib-loctool-webos-appinfo-json"
     ],
     "excludes": [
         "*"
     ],
     "includes": [
         "src"
     ]
}
Note
id property's value in project.json have to be the same as xliff's directory name.
plugins

The loctool is driven by plugins that know how to parse various types of files and writes out the appropriate localized output. Here are matchs for various languages.

typepluginsprojectType
javascriptilib-loctool-webos-javascript, ilib-loctool-webos-json-resourcewebos-web
cilib-loctool-webos-c, ilib-loctool-webos-json-resourcewebos-c
cppilib-loctool-webos-cpp, ilib-loctool-webos-json-resourcewebos-cpp
qmlilib-loctool-webos-qml, ilib-loctool-webos-ts-resourcewebos-qml
appinfo.jsonilib-loctool-webos-appinfo-json-

(3-3) Run the localization tool on local

Running the Loctool
 node <path-to-the-loctool-dir>/loctool.js

 // To see the usage
 node <path-to-the-loctool-dir>/loctool.js -h

 // Example) options on webOS
 node <path-to-the-loctool-dir>/loctool.js -2 -x xliffPath --pseudo --localizeOnly -l localelist

(4) Update Recipes to apply webOS build

In order to enable the localization task during build, recipes need to be updated properly.

To use the localization tool for generating string resources at build time, add the following line to the recipe to inherit the webos_localizable bbclass.

sample.bb
inherit webos_localizable

C/C++

Regarding C/C++ cases, the i18n library (libwebosi18n) needs to be built first. In order to do that, add a dependency for the library to the recipe.

samplecpp.bb
...
DEPENDS="libwebosi18n"
...
inherit webos_localizable
QML

For QML app, the recipe must inherit webos_qt_localization instead of webos_localizable. webos_qt_localization bbclass includes an additional process to convert a .ts file into a .qm file.

sample.bb for QML
inherit webos_qt_localization
Tips

If necessary, you can change the location of XLIFF directory by redefining the values below:

Default WEBOS_LOCALIZATION_DATA_PATH
WEBOS_LOCALIZATION_DATA_PATH ?= "${S}"
Example of modified recipe
WEBOS_LOCALIZATION_DATA_PATH = "${STAGING_DATADIR}/localization"

Resource Formats

This section explains the resource format of each supported programming language.

Web

Web Application relys on the iLib library and it requires string resources in JSON format. If you are not using the localization tool, create a file named strings.json and write strings for translation in key-value format.

Example of strings.json
{
  "String 1": "Translation 1",
  "String 2": "Translation 2"
}

Make sure that you prepare strings.json files for each locale under the resources directory. The directory structure is as below.

Locale Resource Structure
com.webos.app.sample
├── resources
│   └── <language>
│       ├── <script>
│       │   ├── <region>
│       │   │   └── strings.json
│       │   └── strings.json
│       └── strings.json
├── src
│

For example, the strings for French-language speakers in France need to be stored in resources/fr/FR/strings.json, while the strings for French-speaking residents of Canada stored in resources/fr/CA/strings.json.

C/C++

You can also specify the name of the JSON file. However, it is recommended that you use cppstrings.json for C++ and cstrings.json for C.

QML

Basically, you can follow the localization guidelines of Qt. For details, refer to the Qt documentation.

If you use the localization tool, .qm files for each locale are generated in the following file name format.

  • Format: sampleqml_[lang]_[script]_[region].qm
  • Examples: sampleqml_en_GB.qm, sampleqml_zh_Hans_CN.qm

Preventing the Use of Duplicate Data

If you consider preventing the use of duplicate data, configure the structure of string resources as follows. Let's take an example of English where there may be other translation terms by region.

Termen-US (English - USA)en-GB (English - United Kingdom)
AllAllAll
HelloHiHi
ColorColorColour
SubwaySubwayUnderground

To avoid duplicates, configure directories and files as follows:

  • All: If the original term and translated strings are the same, there is no need to write translations in the resource file.
  • Hello: If the strings for en-US and en-GB are the same, write them in en/strings.json.
  • Color, Subway: If the translations for US and UK English are different, write them in en/US/strings.json and en/GB/strings.json respectively.
com.webos.app.sample
└── resources
    └── en
        ├── GB
        │   └── strings.json              : Colour, Underground
        ├── US
        │   └── strings.json              : Color, Subway
        └── strings.json                  : Hi

To prepare string resources without using the localization tool and XLIFF, write them in JSON format just like in JavaScript. The format and directory structure are basically the same as what's described above.

You can also specify the name of the JSON file, but it is recommended that you use cppstrings.json for C++ and cstrings.json for C.

Pseudo-Localization

Pseudolocalization (or pseudo-localization) is a software testing method used for testing internationalization aspects of software. Instead of translating the text of the software into a foreign language, as in the process of localization, the textual elements of an application are replaced with an altered version of the original language.

When you use the localization tool, it generates the string resources for pseudo locale by default. (You do not need to add an XLIFF file for this locale.)

A pseudo string is generated by processing the source string. For hard-coded strings, however, a pseudo string is not generated.

The pseudo locales defined in webOS OSE are as follows. The character set differs per locale. Therefore, you can check the localization issue even before the actual translation data is updated.

Pseudo LocaleDescription
zxx-XXIncludes accented Latin characters
zxx-Cyrl-XXIncludes Cyrillic characters
zxx-Hans-XXIncludes Chinese characters
zxx-Hebr-XXIncludes Hebrew characters

Contents