Localization
From Xojo Documentation
Localization is the process of making your app display appropriately for a specific country or region. For example, this may involve:
- Displaying text in a different language
- Formatting numbers using alternative thousands and decimal separators
- Formatting dates using an alternative date pattern
- Formatting currency using a specific currency symbol
Contents
Text Localization with Localizable Strings
You localize text for your apps using localizable strings created with the UserGuide:Constant Editor. These are a special form of a constant that is added to a project item such as a module, window, web page or class. Only constants of type String or Text can be marked as localizable. When the constant is localizable, it can have different values to use for localization.
To identify a constant as localizable, create a String or Text constant and then enable the Localizable switch in the Inspector. A recommended approach is to create a separate module for these localizable strings, but you can put them anywhere that is publicly accessible.
You can enter different localized values for the string based on platform and language. Do this using the UserGuide:Constant Editor.
Use the “+” and “-” buttons to add or remove a specific localization. You can choose the Platform and the Language for which to specify a value.
When the user runs an app, the language specified on their system is used to look up the localized value of the string to use.
Localized Strings created in this manner can then be used as the Text or Caption of controls so that the control displays the appropriate localized value. To use a localized string as the Text or Caption, you prefix it with the “#” character when entering it in the appropriate property. If you have a module called LocalizedStrings and have a protected localized string called kWelcomeMessage, then you add it to a Label as the Text property like this:
You can also refer to the localized string in your code just as you would a constant, but since this is a special type of constant, you can also specify which localization you want to use. You do this by supplying the language code (usually two-character) and optionally the region code as a parameter to the localized string name. For example, if you had a localized string called kHello that had localizations for both French (“Bonjour”) and English (“Hello”), you could force the French version to be displayed by doing this:
s = kHello("fr") // s = "Bonjour"
s = kHello("en") // s = "Hello"
s = kHello("en_UK") // s = "Welcome"
And you could grab the default value like this, although you're better off getting the specific language value you want:
Building the Localized App
On the Shared Build Settings, there is a Language property in the Build section of the Inspector. This property determines the language that is used by any localized strings that have “Default” as the language.
It is important that you select a specific language in this build setting. If you also leave this setting at “Default”, you will run into confusion if the project file is shared with people that do not have the same system language as you.
For example, if you leave both the localized string language and build language as “Default” then “Default” becomes “English” for users that build with an English system and becomes “French” for users that build with a French system.
To prevent this confusion, always at least choose a specific language in the Build setting. Alternatively, don’t use “Default” for your localized strings and instead always choose the exact language for them.
Lingua
If you have a lot of text to localize, it can get tedious to enter all the values using the Constant Editor. The Lingua app is used to simplify the localization process. With Lingua you can localize your app strings outside of the project by using the localized strings you have already created.
Refer to the Lingua topic to learn more.
Date and Number Localization
You can localize how dates and numbers are displayed by using the Xojo.Core.Locale class. The shared Current method returns the locale that is specified in the system or device settings. You can then use this with the ToText method on Xojo.Core.Date, Double and Integer to display values formatted properly for the locale.
This code (in a Label's Open event handler), displays the current date:
Xojo.Core.Date.FormatStyles.Long, _
Xojo.Core.Date.FormatStyles.None)
On an US English system, this displays: January 9, 2017
On a French system, this displays: 9 janvier 2017
This code (also in a Label's Open event handler), displays a formatted number:
On an US English system, the number displays like this: 1,234.56
On a French system, it displays like this: 1 234,56
Localizing Web Apps
Web apps can also localize their text using dynamic constants, but the language that is displayed is determined by the language setting in the browser being used to access the web app. More specifically, it is using the constant value that is most appropriate for the HTTP header language setting of the current session.
There are also several properties of the WebSession that are helpful for localization:
- LanguageCode
- LanguageRightToLeft
In addition, you can also localize these dynamic constants on WebSession that are used for system messages:
- ErrorDialogCancel
- ErrorDialogMessage
- ErrorDialogQuestion
- ErrorDialogSubmit
- ErrorThankYou
- ErrorThankYouMessage
- NoJavascriptMessage
- NoJavascriptInstructions
Finally, WebApplication has these properties that you can provide values for using your own dynamic constants:
- LaunchMessage
- DisconnectMessage
- HTMLHeader
Dates and Numbers
In desktop apps, you can use Xojo.Core.Locale to get the user's locale for formatting dates and numbers. However, in a web app this value returns the locale used by the web server rather than the locale of the current user session.
To display dates formatted in the locale of the user session, you need to get the LanguageCode from WebSession and use that to create a locale that you can then use to display the date. This code (in a WebLabel Shown event handler) gets the language code for the user session and then uses it to display the current date:
Dim locale As New Xojo.Core.Locale(langCode)
Me.Text = Xojo.Core.Date.Now.ToText(locale, _
Xojo.Core.Date.FormatStyles.Long, _
Xojo.Core.Date.FormatStyles.None)
When the browser is set to English, this displays: January 9, 2017
When it is set to French, this displays: 9 janvier 2017
Use the same technique with number formatting. This code (in a WebLabel Shown event handler) gets the language code for the user session and then uses it to display a formatted number:
Dim locale As New Xojo.Core.Locale(langCode)
Dim num As Double = 1234.56
Me.Text = num.ToText(locale, "#,###.##")
When the browser is set to English, the number displays like this: 1,234.56
When it is set to French, it displays like this: 1 234,56
To get locale information that is more specific than just the language, you should check the value of the "Accept-Language" HTTP header:
Which returns both the language and region code in a format like this: en-US.
Note that there may be more than one value returned in this header so you may need to parse it to ensure you get the value you actually want.
Changing the Language
Windows
To use a different language on Windows, you need to change the Language setting on the Format tab of the Region control panel. Changing the Language on the Keyboard and Languages tab will not affect your applications.
For Windows 10:
- Open Settings
- Click Time & Language
- In "Related Settings", click "Additional date, time & regional settings"
- In the Region section, click "Change location"
- Click the Formats tab to display the drop-down where you can change the language
Mac
To change the language on Mac, open System Preferences and select "Languages & Region" (top row). In the list of Preferred languages on the left, you can drag the language you want to be the primary language to the top.
Linux
The specific way to change the language and region varies by Linux distribution. On Linux Mint 18, you can make the changes by going to Preferences ↠ Languages and making the appropriate changes.
iOS
To change the language on iOS, open the Settings app and select General, followed by "Language & Region". On this screen you can change the preferred language order and region formats.
Web Browsers
To see a web app in a different language, you'll need to change the settings for the browser that is connecting to the web app. This varies by browser.
| Browser | Language Setting |
|---|---|
| Edge | Uses the system settings in Settings / Control Panel. |
| Internet Explorer | Go to Internet Options. In the General tab click the Languages button to display the screen to set the language. |
| Safari | Uses the system settings in System Preferences. |
| Chrome | Go to Settings and then click Advanced settings. Look for the Languages section. |
| Firefox | Go to Preferences, select Content and look for the Languages section. |