Multilingual Programming

Herbert zur Nedden explains how the ResFind/ResConf package can be used to adapt applications for multiple languages

This article is also available in German.

By using ResFind, programmers can easily create applications whose user interfaces support several languages; and by using ResConf, the end user can change the language selection order, should they wish to do so. This article is intended to show how this works.

Introduction

For many years, RISC OS has made the translation of applications possible, without access to the source code, thanks to the concept of Messages and Templates. Most programmers use this technique, the consequence of which is that quite a few applications offer support for different languages. Often, all the translations come with the application, giving the user the choice of which language to use; this is true especially of freeware programs. Unfortunately, in some cases the end-user has to configure the language to be used by copying files.

Acorn took its time in coming up with a concept for multilingual applications: it finally arrived with the release of the Toolbox, but was only suitable for applications that were themselves based on the Toolbox. By contrast, ResFind, with its concept for multilingual versions of any application, has been available since 1992. Many programmers never started to use Acorn's Toolbox, either because Acorn's development environment was too expensive, the work of converting applications to use the Toolbox involved too much effort, or the learning curve for getting to grips with the Toolbox was too steep.

On the other hand, the Toolbox technique isn't really flexible for multilingual applications from the end-user's point of view, as he can't control the language selected. By using ResConf, however, the user can change the language settings easily.

The end-user: ResConf

If an end-user gets an application that uses ResFind, he can use the application like any other one (he doesn't have to know that it uses ResFind). He might be surprised that the application uses a language he understands, though. But...

Using ResConf, the user can configure several defaults: for example, to determine which language he prefers, the language the system is configured to, and what language is preferable to English. With ResConf, it is even possible to set the language a specific application should use.

Let's take as an example a chap from the French part of Switzerland. His computer is configured to the country 'Switzerland' but he prefers French applications, and German ones are better for him than English ones. These wishes can be set easily using ResConf, and applications using ResFind take these wishes into account automatically.

Here, the language preferences are set with ResConf. French is to be used in preference to the language for the configured country, Switzerland, whilst German is preferred to the default language, English

If I use a program which supports my own language but the translation is not the way I like it, I can use ResConf to set a different language for this application (if the language I want is supported by the application and if it uses ResFind).

Here, ResConf is being used to configure an application (in this case, the CD-mastering software, CD-Burn) to use a specific language. This application obviously supports the languages German and English (UK)

The programmer: ResFind

An application supporting ResFind needs a directory called Resources inside the application directory, and appropriate language directories within it. The names of the language directories have to be the same as the country name used to configure the country (*Configure Country). For Germany, the directory is therefore called Germany and for English (or the United Kingdom, to be more precise) it is UK. All language-dependent files go inside the language directories. Aside from the aforementioned Messages and Templates files, other such language-dependent files will be the help file and perhaps the other documentation. Resources which are not language-dependent, such as the sprites, don't have to go into the language directories but can remain in the application directory as usual; this avoids the need for multiple copies.

This image shows the layout of an application using ResFind. Please note the language directories within Resources. (This application doesn't have the Templates file in the language directories because the text is read into the templates from the Messages file, meaning that the Templates file itself doesn't have to be translated.)

ResFind sets a path variable which tells the program where it can find the resources it should use. For this, ResFind looks for the correct language directory in the application. By default it is the one for the country the computer is configured to, since this reflects the preference of the user (or should reflect it). If the user made language selection settings with ResConf, they are certainly honoured here. If no matching language can be found, UK is taken as the 'last resort' language. Thus the application has to offer the language "UK" as a minimum.

In the !Run file of the application (let us call it !Appl) ResFind is called to find the language resources:

Set Appl$Dir <Obey$Dir>

IconSprites <Appl$Dir>.!Sprites

<Appl$Dir>.Resources.ResFind Appl

/<Appl$Dir>.!RunImage

ResFind sets the system variable ApplRes$Path such that it points to the language directory and to the application directory. Loading the templates is then not done in the previous way:

SYS "Wimp_OpenTemplate",,"<Appl$Dir>.Templates"

but rather by using the resources path variable ApplRes$Path:

SYS "Wimp_OpenTemplate",,"ApplRes:Templates"

The resources path should also be used for loading the other resources. This works in C, likewise. Some C libraries use an internal prefix to load the resources; as for DeskLib, calling

strcpy(resource_pathname, "ApplRes:");

prior to loading the resources does the trick (this is at least true for older versions of DeskLib).

As for the help, the same technique of storing the help files in the language directories should be used, and making the application's !Help file an Obey file as follows:

Set Appl$Dir <Obey$Dir>

<Appl$Dir>.Resources.ResFind Appl

Filer_Run ApplRes:Help

Please bear in mind an important point: the text for the application's menu entries mustn't be hard-coded in the program, but should also be read from the Messages file so that they can be translated as well.

Home page

Even if ResFind is unfamiliar to some readers, it has been available since 1992, and is not only freeware but may even be used in commercial applications.

The current versions of the programs (provided on this CD) are: ResFind 2.01b, ResError 1.01 and ResConf 0.30.

The ResFind home page can be found at http://www.gag.de/software/ResFind/.

"GAG" is the abbreviation for "German Archimedes Group", a German-speaking Club for RISC OS users; we also publish GAG-News, the only German-language RISC OS magazine. More information can be found at http://www.gag.de/ and in the Club Database entry on this CD.