install4j Help

Localization

On the "General Settings->Languages" step, you configure the languages that are supported by your project. The following languages are available:

  • Arabic [ar]
  • Chinese (Simplified) [zh_CN]
  • Chinese (Traditional) [zh_TW]
  • Croatian [hr]
  • Czech [cs]
  • Danish [da]
  • Dutch [nl]
  • English [en]
  • Finnish [fi]
  • French [fr]
  • German [de]
  • Greek [el]
  • Hebrew [he]
  • Hungarian [hu]
  • Italian [it]
  • Japanese [ja]
  • Korean [ko]
  • Norwegian [no]
  • Polish [pl]
  • Portuguese [pt]
  • Portuguese (Brazilian) [pt_BR]
  • Romanian [ro]
  • Russian [ru]
  • Spanish [es]
  • Swedish [sv]
  • Turkish [tr]

By default, only one language is shipped with the installer. This is called the principal language. By adding additional languages, you can build multi-language installers. If none of the configured languages match the locale at runtime, the principal language is used.

For multi-language installers, a language selection dialog is shown when the installer is started. By selecting the Skip language selection dialog check box you can choose to show the language selection only if the installer cannot find a match between a supported language and the auto-detected locale.

The principal language setting can be overridden for each media file on the "Customize project defaults->Principal language" step of the media wizard. In this way, you can build multiple fixed-language installers, each with a different principal language.

Localization mechanism

In projects, localized messages are obtained in one of two ways;

  • with i18n messages

    The i18n variable system gives access to all messages with the syntax 

    ${i18n:messageKey}

    To select a message, use the  variable selector button next to text fields and properties. For messages with one or more parameters of the form {0} to {n}, the variable selector will insert placeholder values like in 

    ${i18n:DiskSpaceWarning("arg 0", "arg 1")}

  • with the API

    In scripts and in your custom code you can call 

    context.getMessage("messageKey")

    For messages with arguments, you pass the arguments with the vararg syntax: 

    context.getMessage("DiskSpaceWarning", 10000, 100)

    The "Insert variable" tool bar button in script editors allows you to insert these calls with the correct syntax for selected message keys.

Custom localization

In addition to the standard messages that are displayed in the generated installer and uninstaller, you will have your own messages that need to be localized in the same way. To configure these messages, create a custom localization file for the principal language. A custom localization file is a text file with key-message pairs in the format of

  • a Java properties file

    A Java properties file has a .properties file extension and must use ISO 8859-1 encoding. All other characters must be represented as Unicode escape sequences, like \u0823.

  • a properties file with UTF-8 encoding

    A properties file with UTF-8 encoding has an .utf8 file extension and has the advantage that you do not have to use escape sequences. However, it might not be supported by some localization tools.

You can create and edit custom localization files externally or directly in the install4j IDE with the built-in editor:

For each additional language, add a corresponding custom localization file that contains the same keys. If a message is missing for an additional language, the message for the principal language is used. The variable selection dialog for i18n messages will show all keys in the custom localization file for the principal language.

If any standard message in the installer is not appropriate for your purpose, you can override it by looking up the corresponding keys in the appropriate message file with the path 

<install4j installation directory>/resource/messages/messages_*.utf8

and defining the same key in your custom localization file. The built-in editor has an "Override message" tool bar button that helps you to find the message of interest and inserts the key-value pair in the editor.

Parameters in i18n messages

If required, you can use parameters for your messages by using the usual {n} syntax in the value and listing the parameters with a function-like syntax after the key name. For example, if your key name is myKey and your message value is 

Create {0} entries of type {1}

you can use a variable 

${i18n:myKey("5", "foo")}

in order to fill the parameters, so that the actual message becomes 

Create 5 entries of type foo

However, in the context of localizing an installer this is rarely necessary. Should you need to include a literal variable expression {n} in the message, you have to quote it like '{'n'}'.

Another way of adding parameters to i18n messages is to use compiler or installer variables. Compiler variables are replaced at build time and installer variables are replaced at runtime. For example: 

messageWithCompilerVariable=Title for ${compiler:sys.fullName}
messageWithInstallerVariable=Installing to ${installer:sys.installationDir}