Skip to content

Internationalization and Localization of App Metadata

As an app developer, you can easily internationalize your app, in order to localize it to multiple languages and locales based on your target audience. This topic introduces the app metadata (folder structure, file name and structure, content and syntax) for the internationalized files in the Mobile Development Kit project.

Definition

Internationalization (i18n) is the design and development of a product, application or document content that enables easy localization for target audiences that vary in culture, region, or language (based on w3.org definition).

Localization refers to the adaptation of a product, application or document content to meet the language, cultural and other requirements of a specific target market (a locale) (based on w3.org definition).

Folder Layout in Metadata Definition

  • ProjectName/ : (Directory)
    • i18n/ : (Directory)
    • i18n.properties : (ResourceFile, Required)
    • i18n_de.properties : (ResourceFile, Optional)
    • i18n_en.properties : (ResourceFile, Optional)
    • i18n_en_GB.properties : (ResourceFile, Optional)
    • i18n_en_US.properties : (ResourceFile, Optional)
    • i18n_es.properties : (ResourceFile, Optional)
    • i18n_zh_Hans.properties : (ResourceFile, Optional)
    • i18n_zh_Hant.properties : (ResourceFile, Optional)
    • i18n_zh_Hant_HK.properties : (ResourceFile, Optional) ( and other supported languages.)

i18n directory (in lower case) consists of all files or resources related to Internalization and Localization, currently consists language resource files.

Application Configuration

There are a few application configurations defined in both Application.app in metadata definition and BrandedSettings.json.

In Application.app

Set the value for "Localization" property to the location of your default i18n properties file. The filename defined here will be used as the base name to search for other translated properties files.

"Localization": "localization reference (.properties)"

e.g.

"Localization": "/ProjectName/i18n/myi18n.properties"

myi18n will be the base name of the file

In BrandedSettings.json

"DefaultAppLanguage" : "default application language, i.e. en"

e.g.

"DefaultAppLanguage" : "en"

Note

If not specified in BrandedSettings.json, "en" will be used as the default value. For iOS, when the app fall backs to use DefaultAppLanguage, the app need to be restarted to fully take effect, it's advisable for app to inform user to restart app after changing the language.

Properties File

Properties files are where language and locale-specific strings stored. The filename should share the base name as defined in the "Localization" property in Application.app.

The application will only load the selected language as app language if the language properties file is provided, e.g., user selected Norwegian as the device language, but the i18n_no.properties file is not provided in metadata, in this case, the app would fall back to use DefaultAppLanguage as the app language.

The filename format (excluding the base_filename) should follow IETF BCP 47 Language Tag and iOS language ID designators.

The filename structure can consist of up to 4 parts: <base_filename>_<language_code>_<script_specifier>_<region_specifier>.properties

  • base_filename is mandatory base filename that should match the filename defined in the "Localization" property in Application.app
  • language_code should be set to the short form language code that its content has been translated to. The format should follow ISO 639-1 standard with two-letter language code in lowercase.
  • script_specifier is optional and can be set if its content is adapted to the specified script. The format should follow ISO 15924 standard with four letters (first letter uppercase and the last three lowercase). Do note that if the script_specifier is set, the app would only use the properties file if the device language script matches the script specifier.
  • region_specifier is optional and can be set if its content is adapted to the specified country. The format should follow ISO 3166-1 standard with two-letter capitalized region code. Do note that if the region_specifier is set, the app would only use the properties file if the device region matches the region code.

e.g.

  • myi18n.properties = default properties file
  • myi18n_en.properties = properties file for English language without country specifier
  • myi18n_en_GB.properties = properties file for British English language
  • myi18n_zh_Hans.properties = properties file for Chinese language with Simplified script specifier
  • myi18n_zh_Hant_HK.properties = properties file for Chinese language with Traditional script specifier and Hong Kong region specifier

Properties File Content

Each properties file contains a list of localization strings that come in key and value pair.

Syntax

<Localization_Key>=<Localized_Value>

Parameters

Parameter Name Type Required? Description
Localization_Key String Literal Mandatory Key to identify this localization string. Must NOT contain space
Localized_Value String Literal Mandatory Translated value for the localization string. You can add parameters for formatting. See [Text Formatting in Localized String] for details

Text Formatting in Localized String

You can add formatting parameters in the <Value>:

Use: {n} e.g. {1}, {2} ... {n} as placeholder for parameters value

e.g. {1} has sent item {2} to you

You can replace {1} and {2} with real value at runtime.

Misc

Comment lines in properties files are denoted by the hash sign (#) as the first non blank character, in which all remaining text on that line is ignored.

Properties File Example

HOMEPAGE_TITLE=Home Page
FULL_NAME=Full Name

# Localized string with parameters {n}. This is also a comment and will be ignored
WRONG_AMOUNT={1} is less than the minimum required amount: {2}
WRONG_PASSCODE=Wrong Passcode. {1} attempts remaining
PUSH_RECEIVED_ITEM={1} has sent item {2} to you
PUSH_NEW_ORDER=New order {1} has been placed

Consuming Localized Strings and Localized Data Formatting

Localization properties file can be consumed directly in metadata definition and also in rules:

Setting Application Language in Mobile Development Kit

A Mobile Development Kit application has 4 layers of setting to detect and decide application language and set the layout accordingly. They are , in order of decreasing priority :

  1. App Defined Language Setting
  2. Device Language Setting
  3. Default setting
  4. Hard-coded Language Setting

To enable support for any language inside an Mobile Development Kit application, user need to provide translations for strings in a properties file in i18n_<language _code>.properties format along with the metadata. The application will generate of a list of supported languages from the available i18n_<language_code>.properties files in metadata.

  1. App Defined Language Setting: This is the language set using Client APIs (SetLanguage Action or ClientAPI) by the app. If a supported language is set using the Client APIs, it will be stored and will take precedence over the device language. Otherwise it will fall back to use device language.

  2. Device Language Setting: This is the language setting defined in the device's setting. If the device language is supported by the app, it will be used, otherwise it will fall back to use the default language.

  3. Default Language Setting: This is the default language setting provided to the application in BrandedSettings.json. If not supported or provided, it will fall back to hard-coded language.

  4. Hard-coded Language Setting: If all the settings above fail, then it falls back to hard-coded language set in the app. Usually it remains set to “English”.


Last update: November 22, 2021