Quick Apps

# Internationalization

You can distribute the same quick app in multiple languages, addressing different countries and cultures. The internationalization of quick apps enables the platform to manage and deliver the content depending on the system's configuration (locale) with the same rpk file.

You can configure the multilingual capability of your quick app just by creating specific localization resources and referencing their content. If you want to allow your users to change the locale and language of the quick app, please check the Select Localization Resources section.

# Localization Resources

The quick app platform uses localization resource files to store definitions of multiple languages. These files are JSON documents stored in the i18n directory within the main directory for the source code. Every localization document represents the resources for one language. Resources contain JSON objects with key-value pairs that have the unique identifier (the key) of a localizable term or expression and the representation in the concrete language (the value).

The filename of each localization document follows the Language-Tag (opens new window) notation as defined in and represents the specific configuration for that particular language. Suppose a language has different variants, depending on the region. In that case, you can specify them using the concrete details of the language/region. The file matching will be performed by priority.

Language Variants

You can define several variants of a language. For instance, English: en for generic English, en-GB for British English, and en-US for US English. If the user's locale is set as en-GB, the matching sequence to select the right resource is: en-GB -> en -> en-* -> lang by default. If there are multiple en-* files, they are sorted in ascending alphabetical order.

If your app is planned to support only one language, but you still need to use the formatting, singular-plural conversion, and localization of multi-language support, you can use this feature, declaring a defaults.json file.

Example of localization resource:

{ 
    "message": { 
        "appName":"Quick App Sample", 
        "pageA": { 
            "pageTitle": "Quick App feature display", 
            "text": "pure-text-content", 
            "format": { 
                "object": "type-{name}", 
                "array": "type-{0}" 
            }, 
            "array": [ 
                "item-type-string", 
                { 
                    "key": "item-type-object-attribute" 
                }, 
                ["item-type-array"] 
            ], 
            "plurals": { 
                "double": "car | cars", 
                "three": "no apples | one apple | {count} apples", 
                "format": { 
                    "object": "type-{mytype}", 
                    "array": "type-{0}" 
                } 
            } 
        } 
    } 
}

Any component may access the values of the localization resources through path expressions based on the key names separated by the dot (.) operator. For instance, message.pageA.text corresponds to pure-text-content.

# Access to Localization Resources

All component instances implement the function $t() and $tc() to access the multilingual features.

You can access these functions both from the template and from the script sections. For instance:

<template> 
    <div> 
        <text>{{ $t('message.pageA.text') }}</text> 
        <text>{{ $t('message.pageA.format.object', { mytype: 'string' }) }}</text> 
        <text>{{ $t('message.pageA.format.array', ['orange','lemon','strawberry']) }}</text> 
    </div> 
</template> 
<script> 
    export default { 
        onInit () { 
            // Simple formatting: 
            this.$t('message.pageA.text') 
            this.$t('message.pageA.format.object', { mytype: 'string' }) 
            this.$t('message.pageA.format.array', ['orange','lemon','strawberry']) 
        } 
    } 
</script>

# Simple Formatting

The function $t extracts the content value from a localization resource.

  • path: string (Mandatory). Path of the JSON key that identifies the content in the resource.
  • object: (optional) object with the arguments to include as parameters in the localized content.
  • array: (optional) array with a list of values to be selected as parameters in the localized content.

Examples:

// Sample 1: Formatting without additional parameters 
this.$t('message.pageA.text') 
// Output: "pure-text-content" 

// Sample 2: The additional parameter is an object, which is used to replace the binding in the referenced content. 
this.$t('message.pageA.format.object', { mytype: 'string' }) 
// Output: "type-string" 

// Sample 3: The additional parameter is an array, which is used to replace the binding in the referenced content.  
this.$t('message.pageA.format.array', ['arg-array'])
// Output: "type-arg-array"

# Pluralization

The function $tc extracts the content value from a localization resource either in singular or plural.

  • path: string (Mandatory). Path of the JSON key that identifies the content in the resource.
  • choice: (optional) integer . Which plural string to get. 1 returns the first one.

You need to define the locale messages that have a pipe (|) separator and define plurals in pipe separator, as described in the message.pageA.plurals.double in the example.

Examples:

// Sample 1: When the value of message contains two options, the passed value is not the singular form. 
this.$tc('message.pageA.plurals.double', 0) 
// Output: "cars" 

// Sample 2: When the value of message contains two options, the passed value is the singular form. 
this.$tc('message.pageA.plurals.double', 1) 
// Output: "car" 

// Sample 3: When the value of message contains two options, the passed value is not the singular form. 
this.$tc('message.pageA.plurals.double', 2) 
// Output: "cars" 

// Sample 4: When the value of message contains two options, the passed value is not the singular form. 
this.$tc('message.pageA.plurals.three', 0) 
// Output: "no apples" 

// Sample 5: When the value of message contains three or more options, the passed value is the singular form. 
this.$tc('message.pageA.plurals.three', 1) 
// Output: "one apple" 

// Sample 6: When the value of message contains three or more options, the passed value is not the singular form. 
this.$tc('message.pageA.plurals.three', 10)
// Output: "10 apples"

# Select Localization Resources

In some scenarios, you may need to modify the locale of the current system. You can change the language options of the app through the App Configuration API.

Getting the locale:

import configuration from '@system.configuration' 
// Get the locale. 
// You can set the locale to the data attribute in the VM and determine the locale in the template to change layouts. 
const localeObject = configuration.getLocale() 
// Convert the locale to the character string format, for example, en or en-US. 
const locale = [localeObject.language, localeObject.countryOrRegion] 
    .filter(n => !!n) 
    .join('-') 
console.info(`The current locale is: ${locale}`)

// function onConfigurationChanged is triggered after locale is set successfully. 
configuration.setLocale({ 
  language: 'es', 
  countryOrRegion: 'AR' 
})

The configurationChanged event is triggered when the system settings or configuration.setLocale is modified:

onConfigurationChanged(data) { 
    console.info(JSON.stringify(data)) 
    // Output {"type":"locale"} 
}

# Localization of Manifest Members

You can use the internationalization features on the name (app name) and titleBarText (page title) members in the manifest file.

Example:

{
  "package": "org.example.myquickapp",
  "name": "${message.appName}",
  "display": {
    "backgroundColor": "#ffffff",
    "titleBarText": "${message.pageA.pageTitle}"
  },
}

← Components Basics →