Using localized strings at runtime

Distributing compiled string files

The compiled string files (.42s) must be distributed with the program files in a directory specified in the DBPATH/FGLRESOURCEPATH environment variable.

Setting the correct locale

The locale (LANG/LC_ALL) corresponding to the encoding used in the .42s files must be set before starting the application. If the locale is wrong, the strings will not be loaded properly.

How does the runtime system load the strings?

The .42s compiled string resource files are loaded in following order of precedence:

The files defined in FGLPROFILE,
A file having the same name prefix as the current program,
A file with the name "default.42s".

For each string file, the runtime system looks in the following directories:

The current directory,
The path list defined in the DBPATH/FGLRESOURCEPATH environment variable,
The FGLDIR/lib directory.

What happens if a string is not defined in a resource file?

If a localized string is not defined in one of the compiled string files, the runtime system uses the string identifier as default text.

What happens if a string is defined more that once?

When a localized string is defined in several compiled string files, the runtime system uses the first string found.

For example, if the string "hello" is defined in program.42s as "hello from program", and in default.42s as "hello from default", the runtime system will use the text "hello from program".

Defining a list of string files in FGLPROFILE

Specify a list of compiled string files with entries in the FGLPROFILE configuration file with the fglrun.localization entries.

First define the total number of files with:

fglrun.localization.file.count = integer

And for each file, define the filename (with the .42s extension), including an index number (start index must be 1):

fglrun.localization.file.index.name = "filename.42s"

Warning switches can be specified in FGLPROFILE.

If the text of a string is not found at runtime, the runtime system can show a warning, for development purposes.

fglrun.localization.warnKeyNotFound = boolean

By default, this warning switch is disabled.

Organizing .42s resource files in distribution directories

A set of .42s files using the same language and codeset is typically copied in a distribution directory with a name identifying the locale.

For example:

/opt/app/resource/strings/en_US.iso8859-1  -- English strings in iso8859-1 code-set
/opt/app/resource/strings/fr_FR.iso8859-1  -- French strings in iso8859-1 code-set
/opt/app/resource/strings/jp_JP.utf8       -- Japanese strings in utf-8 code-set

At runtime, specify the string file search path in the DBPATH/FGLRESOURCEPATH environment variable by adding the name of current locale as sub-directory. For example, to find the correct string files in one of the locale-specific directories shown above, set the FGLRESOURCEPATH variable as follows (UNIX™ shell):

$ echo $LC_ALL
jp_JP.utf8
$ FGLRESOURCEPATH="$FGLRESOURCEPATH:/opt/app/resource/strings/$LC_ALL"
$ export FGLRESOURCEPATH
$ echo $FGLRESOURCEPATH
/opt/app/forms:/opt/app/resource/strings/jp_JP.utf8