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)