Localization

The Localization single instance plugin handles all localization and translation related functionality. All locale settings are app-wide.

Right-to-left Support

Most Astro plugins currently offer right-to-left support. On Android, setting the locale to a right-to-left language such as Arabic will immediately cause those plugins to swap their layout. On iOS, setting the locale in an Astro application does not trigger a right-to-left swap. Instead, the system locale is what determines the orientation of the application. So on iOS, if the app is set to use Arabic, Arabic strings will be used if they can be found in the dictionaries, however, the UI will only swap orientation if the user has their device also set to Arabic.

Localized Plugins

Any native class (for example a custom plugin) that must be aware of locale changes should implement the LocaleChangedListener protocol/interface. On initialization of the class it should add itself to the list of subscribers by calling the addLocaleChangedListener method on the Localization/LocalizationUtilities object on the native side.

Sample swift code:

public class MyCustomSwiftClass: LocaleChangedListener {
    init() {
        Localization.addLocaleChangedListener(self)
    }

    public func localeDidChange(newLocale: Locale) {
        // Retrieve localization state from the Localization class
        print('Locale changed!')
    }
}

For any Astro plugin methods that accept string parameters that will be displayed in the UI, translation keys should be used instead of hard-coded strings. Astro will look up the supplied translation key in the supplied dictionaries and replace the text with the localized string if it is found. If Astro cannot find the key in the current locale's dictionary, it will fallback to English. If the key does not exist in the English dictionary either, the key itself will be inserted in the UI.

Sample code:

myHeaderBarPlugin.setLeftTitle('header_left_title_key')

Dictionaries

All strings must be added to dictionaries in both the iOS and Android project. String resource files can be found in Localizable.strings on iOS and strings.xml on Android.

To support the above example, the following would be needed in the project:

//// Localizable.strings (iOS)
"header_left_title_key" = "My left title"

<!-- strings.xml (Android) -->
<string name="header_left_title_key">My left title</string>

A version of each of these files must exist for each language the app supports.

Methods

getLanguage #

Returns the ISO 639 alpha-2 language code representing application language. If no language has been set on previous app launches or this is the first app launch, the fall-back is the OS language. The returned language code is always lowercased as per the standard.

setLanguage #

Sets the langauge to the supplied ISO 639 alpha-2 language code. This method is case insensitive but langauge is lower case canonicalized when set.

getCountry #

Returns the ISO 3166 alpha-2 country code representing the application country. If no country has been set on previous app launches or this is the first app launch, the fall-back is the OS coutnry. The returned country code is always uppercased as per the standard.

setCountry #

Sets the country to the supplied ISO 3166 alpha-2 country code. This method is case insensitive but country is upper case canonicalized when set.

getLocale #

Gets an object containing the ISO 3166 alpha-2 country code and ISO 639 alpha-2 language code of the app. Langauge code is always lower case, country code is always upper case.

{
    langauge: "en",
    country: "CA"
}

setLocale #

Sets the application locale to the supplied ISO 3166 alpha-2 country code and ISO 639 alpha-2 language code supplied. This method is case insensitive but supplied values will be canonicalized. This method requires both country and language to be supplied. Setting only one of these values should be done through setCountry or setLanguage accordingly.

 Localization.setLocale({
    langauge: "ar",
    country: "SA"
})

translate #

Given a translation key, returns the translated version of the string in the language that the application is currently set to (as returned by getLanguage()). If the key is not found in the current lanuage's dictionary, or the current langauge does not have a dictionary supplied, the key returns the corresponding string from the base language dictionary (English). If the key is not found in the base language dictionary, the key itself is returned.

const translatedString = await Localization.translate('my_test_key')
console.log('Translation for "my_test_key" = ' + translatedString)