UserGuide

Difference between revisions of "Localization"

From Xojo Documentation

(Windows: Added images and table.)
(Lingua)
Line 39: Line 39:
  
 
== Lingua ==
 
== 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 application strings outside of the project by using the dynamic constants you have already created.
+
If you have a lot of text to localize, it can get tedious to enter all the values using the Constant Editor. The [[UserGuide:Lingua|Lingua]] app is used to simplify the localization process. With Lingua you can localize your application strings outside of the project by using the dynamic constants you have already created.
  
When all of the strings in your project have been defined as dynamic constants, choose File ↠ Export Localizable Values. A dialog box appears, asking you to select the language you want to localize to. Select the language you are localizing to and click Export. (Also make sure that the Language in the Build Settings is set to either Default or any other language that you want to use as the originating language in the export.)
+
Refer to the [[UserGuide:Lingua|Lingua]] page to learn how to use it.
 
 
When you click Export, a file is created that can be opened by Lingua.
 
 
 
Launch Lingua and then open the file you exported. The main Lingua window opens, showing a list of all the dynamic strings in your application. The values are grayed out when there is no localized text yet. If there are any different values specific to Windows, Linux, or macOS, there will be an icon to the far right of the string in the list. Like the strings, the icons are grayed out if the value hasn't been localized yet.
 
 
 
To localize a string, select it in the list. The original value is displayed in its entirety in the upper right pane, and in you can type the translated text in the lower right panel.
 
 
 
To add a value specific to a platform, expand the string in the list, and select the individual platform to edit it.
 
 
 
To test the strings, choose File ↠ Export to Application. Lingua presents an open-file dialog box. Select the target application and click Open. When the import is complete, switch back to Xojo and debug the application normally.
 
 
 
When finished localizing, you can save the file from within Lingua and then import the strings file back into your project by dragging it into a project or choosing File ↠ Import.
 
  
 
== Date and Number Localization ==
 
== Date and Number Localization ==

Revision as of 19:29, 26 September 2018

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

Text Localization with Dynamic Constants

You localize text for your applications using dynamic constants, which is 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 dynamic. When it is dynamic, it allows it to be more easily used for localization.

To identify a constant as dynamic, create a Text constant and then check the dynamic check box. A recommended approach is to create a separate module for your localizable constants, but you can put these constants anywhere that is publicly accessible.

You can enter different localized values for the dynamic constant based on platform and language. Do this using the 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 constant to use.

Constants 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 dynamic constant 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 constant called kWelcomeMessage, then you add it to a Label as the Text property like this:

#LocalizedStrings.kWelcomeMessage

You can also refer to the dynamic constant in your code just as you would any other constant, but with a dynamic 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 constant. For example, if you had a constant called kHello that had localizations for both French (“Bonjour”) and English (“Hello”), you could force the French version to be displayed by doing this:

Dim s As String
s = kHello("fr") ' s = "Bonjour"
s = kHello("en") ' s = "Hello"
s = kHello("en_UK") ' s = "Welcome"

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 constants 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 constant 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 constants and instead always choose the exact language for each constant.

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 application strings outside of the project by using the dynamic constants you have already created.

Refer to the Lingua page to learn how to use it.

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:

Me.Text = Xojo.Core.Date.Now.ToText(Xojo.Core.Locale.Current, _
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:

Dim num As Double = 1234.56
Me.Text = num.ToText(Xojo.Core.Locale.Current, "#,###.##")

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 langCode As Text = Session.LanguageCode.DefineEncoding(Encodings.UTF8).ToText
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 langCode As Text = Session.LanguageCode.DefineEncoding(Encodings.UTF8).ToText
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:

Dim langHeader As String = Session.Header("Accept-Language")

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

Windows 10 Language Setting

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

Mac Language Settings

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

Linux Mint 18 Language Settings

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

iOS Language Settings

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.