Internationalization/Localization Language Properties
Internationalization/Localization Language Properties
Starting with Wrapper version 3.5.0, the code base has been
internationalized and is able to run localized.
To run your application in another language (given that your OS supports the language),
please read through this page.
Changes to the value of these properties will not have any affect on the Wrapper
if the configuration is reloaded.
The Wrapper must be restarted for changes to take effect.
This property specifies the output language of the Wrapper.
On Windows, the value must be one of the installed languages.
Please refer to the list of supported language on Microsoft website.
The short notation (language tag) is preferred and can be written with a '_' instead of a '-' for cross-compatibility with Unix systems.
The value 'en_UK' was added as an alias of 'en_GB' (or 'en-GB') to be compatible with Unix.
On UNIX based systems, the value has to be the valid part 'language[_territory]' of an installed locale.
In order to get the installed and available locales on UNIX systems, please run "locale -a".
If no locale for the desired language appears in the list, you would need to install
one prior to using the localization feature of the Wrapper.
On Linux, this can be done with the 'locale-gen' command.
SYSTEM for the system language (commonly referred to as 'Language for non-unicode programs').
On Windows, the default value is DESKTOP. Prior to version 3.5.28, the language was resolved using the language identifier of the Region Format settings.
On UNIX based operating systems, both 'DESKTOP' and 'SYSTEM' are both considered as default values and resolved as the language of the current session.
DESKTOP and SYSTEM can only be used when wrapper.lang.windows.encoding is set to 'ANSI' (default), 'OEM' or 'UTF-8'.
For more information, please read the wrapper.lang.windows.encoding description.
Since version 3.5.31, the Wrapper will try using a different letter case (for example 'JA_JP' instead of 'ja_JP')
if no exact match could be found when searching among the languages installed on the system.
This is done to improve portability as lowercase or uppercase characters may be used for a same language depending on the platform.
When running on a single server, it is however recommended to set the value exactly as returned by the 'locale' command.
It is also possible to specify a modifier (e.g., @euro) after the language. If wrapper.lang.encoding
is also set, the modifier will be automatically added after the encoding when setting the locale.
Usually it should not be needed to add the modifier because the Wrapper also searches among locales ignoring the modifiers
if no exact match could be found.
This property (and its platform specific equivalents 'wrapper.lang.windows.encoding' and 'wrapper.lang.unix.encoding'),
specifies the encoding of the Wrapper process which is used to write any log output.
It is also used to read the JVM output. The selected encoding has to be installed on the OS in order to make use of it.
When the Wrapper can't set the encoding, it falls back using the encoding of the environment on which it was launched.
Since version 3.5.35, the wrapper.jvm.encoding property can be used to set the default encoding
of the JVM to a different value than the encoding used by the Wrapper. Three configurations are possible:
- if wrapper.lang.*.encoding is not specified, the Wrapper will use the environment encoding, or if it exists the encoding specified in the JVM arguments, to read the JVM outputs.
- if wrapper.lang.*.encoding is specified to a value different than the environment, the Wrapper will use it to read the JVM outputs, and will set the default encoding of the JVM to the same value.
- if both wrapper.lang.*.encoding and wrapper.jvm.encoding are specified, the Wrapper will use the value of the first property to read the JVM output, and set the JVM default encoding to the value of wrapper.jvm.encoding. This requires recent JVMs which can receive system properties to set the encoding of the standard outputs to a different value than default encoding (see the description of wrapper.jvm.encoding).
This property was added in version 3.5.35 to bring support of encodings on Windows.
The default value is 'ANSI' which refers to the default OS ANSI code page.
This is the same value that the JVM uses by default. Setting this property to another value will have two effects:
- First, the Wrapper will pass the encoding to the JVM by adding the file.encoding system property to the
list of JVM arguments. This ensures that the JVM and Wrapper respectively write and read using the same encoding.
- Secondly, the locale of the Wrapper process will be updated so that all Wrapper outputs can be written to the log file
using the same encoding.
The value of this property can be set to one of the Windows Code Pages Identifiers. Note however that the Wrapper will restrict some values when the code page can't be used to write to the console
(see the warning at the bottom of this section), or when the code page is known to be incompatible with the configured language.
As of 3.5.35, the compatibility is only checked for the languages provided with the Wrapper
(i.e. English, German and Japanese):
- English is compatible with all code pages because it contains only ANSI characters.
- German supports the following code pages: 437, 850, 1141, 1250, 1252, 20106, 20273, 28591, 28592, 65000, and 65001 (UTF-8)
- Japanese supports the following code pages: 932, 10001, 20290, 20932, 21027, 50220, 50221, 50222, 50930, 50931, 50939, 51932, 65000 and 65001 (UTF-8)
Unlike Unix systems, Windows doesn't check compatibility between a code page and language when setting a locale. This means that a language
(other than the above listed ones) associated with a wrong code page may result in garbled outputs, without means for the Wrapper to know about it.
By default, the Wrapper localization is resolved using the language of the user interface which may vary depending on the machine.
To ensure a correct encoding through the different platforms, wrapper.lang.windows.encoding must be set to 'ANSI' (or left to default),
'OEM' or 'UTF-8' if wrapper.lang is set to 'DESKTOP' or 'SYSTEM'.
Note that some encodings like UTF-8 contain characters coded in more than 2 bytes.
The locale of the Wrapper process can't be set with a DBCS code page, but the Wrapper operates internaly in Unicode and will apply a conversion
to write the log output in the correct encoding.
The Wrapper can use two different modes when logging its output to the console. These modes can be controlled with the
When set to TRUE, which is the default, the console operates in Unicode and any conversion from the value of
wrapper.lang.windows.encoding will be supported. However, you should make sure that the font of the console supports
the characters of the language. The font can be changed from the 'Properties' windows of the console.
When wrapper.console.direct is set to FALSE, the Wrapper will make use of stdout and stderr, which requires all outpouts to
be written in the console code page so that they can be decoded and displayed correctly at the opposite side of the streams.
In this mode, any value of wrapper.lang.windows.encoding that is not compatible with the console code page will be rejected.
In addition to set the encoding of the Wrapper output, wrapper.lang.windows.encoding is also used when reading the JVM output.
If it is left to its default value (ANSI), the 'file.encoding', 'sun.stdout.encoding' and 'sun.stderr.encoding'
system properties can be used to specify a different encoding that the Wrapper will use to read the JVM output.
However, if wrapper.lang.windows.encoding specifies an encoding other than 'ANSI', the system properties will not be
accepted in the wrapper.java.additional.* properties, because the Wrapper would also need to use them.
In such a situation the Wrapper will consider the configuration as invalid and will stop. You will be asked to choose between
the Wrapper properties and the system properties.
This property was introduced in 3.5.35 to replace the deprecated wrapper.lang.encoding property.
Like wrapper.lang.encoding, the default value is the encoding of the locale set for the session that launched the Wrapper.
Before using the encoding, the Wrapper will always make sure that the combination of the configured language
and encoding exists as an installed locale on the system, and that any conversion from and to the configured encoding are supported.
If the configuration is correct, the locale (language and encoding) of the Wrapper process will be updated, otherwise the Wrapper will
attempt to combine the configured language with the encoding of the session that launched the Wrapper, or failing that, will not update the locale.
If you use the command 'locale -a' to list all installed locales of the system, you may notice that some of them
have no encoding specified in their descriptive name. In fact, such locales have a default encoding which can be
displayed by using the following command:
Example: (display the default encoding)
$ LANG=de_DE@euro locale charmap
In order to make the Wrapper use a locale with a default encoding, it is necessary to set wrapper.lang.encoding
to the value of the default encoding.
Example: (define a locale with its default encoding)
On some platforms you would need to change the locale before executing 'locale charmap'.
On Mac OSX, 'locale charmap' will return an empty string when querying the default encoding of a locale.
In this case, the encoding is assumed to be UTF-8.
When setting a locale, some platforms (Linux, AIX) will ignore canonical dashes, punctuation, and case in the encoding notation.
For example UTF-8 is equivalent to utf8. Other platforms will require the encodings to strictly match (Solaris, FreeBSD, HP-UX).
Finally some platforms will require the dashes and punctuation to match but not necessarily the case (Mac OSX, ZOS).
In order to properly display log outputs, the configured encoding must match with the terminal's encoding.
There is no way for the Wrapper to know about the terminal encoding, as it is usually specified by an option
of the terminal emulator and not by a locale variable.
For example, the encoding of the Gnome terminal can be changed from the menu by selecting: Terminal -> Set Character Encoding.
Unlike Windows, the compatibility between a language and the encoding is automatically verified by the fact that it is only
possible to set a locale to one of those installed on the system, an installed locale being a set where the encoding is
appropriate for the language and region settings it represents.
Another difference with Windows is that the Wrapper usually doesn't need to pass the encoding to the JVM (through file.encoding),
because the JVM automatically uses the locale encoding of the Wrapper process.
However, since version 3.5.35 the JVM output encoding and default encoding can be set
to different values by using wrapper.jvm.encoding, in which case the Wrapper will need
to add both encodings to the arguments used when launching the JVM. For this reason it is not allowed to use wrapper.jvm.encoding together with 'file.encoding',
'sun.stdout.encoding' or 'sun.stderr.encoding' in the wrapper.java.additional.* properties (see wrapper.jvm.encoding for details).
Unix systems often use the same syntax for encodings. Sometimes the case or punctuation may differ (e.g. 'UTF-8' vs 'utf8'), but the Wrapper will resolve
such cases automatically if no exact match could be found. However, some OS use platform-specific names and it can be useful to target these encodings with
dedicated properties. This is possible using the wrapper.lang.<platform>.encoding properties.
If the property for a platform isn't specified, the default value will be the value of wrapper.lang.unix.encoding.
The supported values for <platform> are:
Example: set the encoding to eucJP ('IBM-eucJP' on AIX)