
National Language Support (NLS)
===============================

This directory contains files required for NLS.

The ASCII coded file 'nls.txt' contains all strings that can be localized in the
native language of the program (english).


How to localize the program for a new language
==============================================

Copy the file 'nls.txt' to the 'L10n' subdirectory and rename it to the target
locale preserving the extension. The resulting filename must look like this:
-------------------------------
xx_YY.txt

   xx: Language (lower case)
   YY: Country (upper case)
-------------------------------
To create e.g. a german localization for austria, the name must be 'de_AT.txt'.

Now the strings in this file can be translated. All lines starting with "$ " are
comments for the translator and not intended to become translated themselves.
The translations must be placed behind the original strings with a space as
separator. Examples:
-------------------------------
"original" "translation"
"foo " "bar "
"replace with empty string" ""
"should stay as it is"
-------------------------------
The second example shows strings with spaces at the end (this is allowed).
The third example generate an empty string. The fourth example leave the
original string in place (e.g. if there is no translation that makes sense in
the target language).

Attention:
The NLS string processing of the source code has problems with parenthesis,
therefore /hexadecimal-escape-sequence/ is used to represent them. For the
translated strings this is not allowed and the corresponding characters must
be used literally. Example:
-------------------------------
"\x28\x43RL\x29" "(CRL)"
-------------------------------
In the translated strings only the /simple-escape-sequence/ "\n" and "\r"
should be used in a similar way as in the original strings (for line breaks).

Note:
If some strings are present multiple times, the first occurrence and the
corresponding translation is used. All other occurrences of the same string are
ignored. They should nevertheless become assigned the same translation string
(because some strings may be removed in future versions)!

Finally the file content must be stored in Unicode format using UTF8 encoding
and normalization form C (NFC aka "precomposed").

To find all lines with missing translations you can use the following command:
grep '^"[^"]*"$'


How to install the new localization
===================================

The new localization is detected and installed automatically by the build
system. From the toplevel directory:

Type 'make clean' first and then 'make install' to reinstall anything.


How to use the new localization
===============================

Set the locale of your system to something that starts with the desired language
and country code 'xx_YY' as described above.
Example for germany:

Try 'LC_MESSAGES=de_DE ; export LC_MESSAGES'.

If it doesn't work:
Type 'locale -a' to list all available locales of your system.
Some old systems use locales of the form 'xx'. They are supported and internally
handled as 'xx_XX'.
Some other systems require that you specify an encoding like 'de_DE.ISO8859-1'.
The encoding is ignored for 'LC_MESSAGES' and it doesn't matter which one you
choose. Unicode is always used for NLS by this program.

If your window manager is not able to display Unicode text in the window title
bars, set 'LC_CTYPE' to a locale with ISO 8859-1 encoding. The strings for the
window manager are converted to ISO 8859-1 in this case.
No other encodings than UTF-8, ISO 8859-1 and US-ASCII are supported for
'LC_CTYPE'.

Attention:
POSIX defines undefined behaviour if the encoding configuration is not the same
for all locale categories. Therefore you should avoid such configurations.


And now?
========

If you have created a useful localization, report it so that it can be
integrated into the source tree and shipped with later versions.


EOF
