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 as the current program (myprog.42m loads myprog.42s),
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.

String resource file sharing

Like .42m program pcode files, the .42s string resource files are shared by all fglrun processes running on the computer: The string file is loaded into memory with the mmap operating system function.

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

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.

What happens if a 42s string file is not found?

If the 42s string file was defined with fglrun.localization.* FGLPROFILE entries, it is considered as mandatory, and the runtime system will raise error -8006 if the file is not found. If the progname.42s and default.42s string files are not found, no error is raised, because these are fallback string resource files.

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".

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

Localized string files on mobile devices

On mobile devices, the language is determined by the operating system regional settings.

On iOS devices (version 8.1), the language is determined by Settings >> General >> International >> Language
On Android™ devices (version 4.4), the language is determined by Settings >> Language & Input >> Language

The selected language is identified by a locale code following the ISO 639 standard. Below are some language code examples; see the mobile OS documentation for information about available languages and their corresponding ISO 639-x codes.

en - English (for all regions)
en_US - English in the United States
en_GB - English in the United Kingdom

On startup, the mobile app will by default search for localized string files (.42s) in appdir/locale-code, the application sub-directory having the same name as the locale identifier (with language and category/region codes) (for an English-US locale: appdir/en_US). If the 42s files are not found in this sub-directory, the runtime system tries to load the files from a sub-directory with the language identified only (for an English-US locale: appdir/en). Finally, if the string files are not found in locale-specific directories, the files are loaded directly from appdir.

In order to localize your application, you simply need to place your .42s localized string files in the appropriate language sub-directory.

Note: If the .42s file names do not match the main program name, define the list of localized strings files in app's fglprofile file.

If you want to distinguish language categories (Simplified/Tradition Chinese), or if you want to use different texts according to the territory for the same language (English in USA or Great Britain), create language sub-directories with the exact OS locale identifier:

For English in the USA, use "en_US"
For English in the United Kingdom, use "en_GB"
For English in Canada, use "en_CA"
etc...

appdir/en_US/mystrings.42s
appdir/en_GB/mystrings.42s
appdir/en_CA/mystrings.42s

If the language category or region can be ignored, create language sub-directories with names matching the language identifier only:

For English, use "en"
For French, use "fr"
For German, use "de"
etc...

appdir/en/mystrings.42s
appdir/fr/mystrings.42s
appdir/de/mystrings.42s

Consider providing a default set of string files (in English) directly under appdir, in case if the regional settings of the device do not match one of the locale directories you provide, otherwise the application will stop with error -8006:

appdir/mystrings.42s

For more details about the mobile app directory structures (appdir), see Directory structure for GMA apps and Directory structure for GMI apps.