Using resource files to create multi-lingual OPL applications

Author: Phil Spencer
Last revised: 18 September 2000
Revision: 1.00(030)
Status: Final Release

Summary: With Symbian OS and OPL, creating multi-lingual applications has never been easier. The process is founded on the basic principle that parts of your application which differ between languages should be kept separate from the actual application code. This includes text, graphics and keyboard shortcuts.

Contents

• 1. Introduction
• 2. Files Supplied with this Document
• 3. The Basics
• 4. Compiling resource files
• 5. The Output Files
• 6. Using the Resource File in your Application
• 7. Using Resource Files on the ROM
• 8. A Note About Long Integer Resources
• 9. Acknowledgements

1. Introduction

Differences between language variants (or locales as they are officially titled) of applications can be broadly classified into two areas:

• Things that the user can see (strings of text, bitmaps, etc.)
• Things the user can do (by pressing certain hotkeys for example)

The requirement of different bitmaps between locales can be easily dealt with in OPL by using the Symbian OS native multi-bitmap file format (MBM), where the underlying bitmaps can be changed without requiring a re-translation of the application. Language resource files provide a similar feature for text strings.

When writing an application that is to be translated into different languages, careful thought should be given to all parts which could differ between languages. These may include any or all of the following examples (and maybe other things too, depending on your application):

• The names of menu options
• Hotkeys for those options (for example, on UK machines the ‘Close’ action is always Ctrl+E. On French machines it is Ctrl+Q)
• Text/numbers displayed in dialogs
• Text/numbers displayed on screen as part of the current view
• Error messages
• Toolbar button captions
• The name of your application as reported in the ‘Open files/programs’ dialog

The system of using resource files which contain the relevant details for each language provides an easy way to take care of everything. This document explains how to create and use such files in several easy steps, as well as how to access the existing resource files on the ROM of an Symbian OS device which are used by the built in applications.

2. Files Supplied with this Document

The following files should accompany this document. If you used the ‘Restore folders’ (or equivalent) option when you expanded the .ZIP file this document came in, the files should be located in the folders indicated:

3. The Basics

The first step is to get ready to build your project. All of the resource related tools (with the exception of ConvRSG and EIKON.oph) are PC based, so the most efficient way to develop and test resource files, at least in the beginning, is to use WINS as supplied with your SDK. ConvRSG is a tool which will be explained in more detail - it is written in OPL and must be run from WINS or on a real Symbian OS machine. The EIKON.oph include file can be also used on either WINS or an Symbian OS machine).

When you create an OPL application, you can keep your source code in any folder you like. After you have translated your code, all of the output files will be placed in the path <Code Drive>:\System\Apps\CodeFileName\CodeFileName.app. Since your finished application will be loading resource files from a similar folder, this is where the tools will output the compiled files.

The first file you need to install is EIKRSS.bat. This is a modified version of ‘EIKRS.bat’ which is supplied with the Symbian OS v5 SDK. This new file should be placed in x:\epoc32\tools\ - where x: is the letter of the drive on which your SDK is installed. This means it can be accessed from anywhere (provided you did not remove the PATH to this folder which the SDK installation created).

Secondly, it would be a wise idea to install the sample program, RSCExamp, provided with this document. This illustrates all the concepts covered here, and is clearly commented. Instructions for the installation can be found in the file ‘RSCExamp.txt’ (inside the ‘RSCExamp Program.zip’ archive). From now on, this document will assume you have installed RSCExamp as per the instructions, and the RSCExamp program and folder locations will be used as a basis for examples in this document.

The EIKON.oph file should be placed in \System\OPL\ on any drive (of either WINS or an Symbian OS device), so that it can be included in any OPL program with a simple statement of INCLUDE "EIKON.OPH".

The final file which needs attention at this stage is ‘Make RSCExamp.bat’. This is a batch file written specifically to automate the compilation of all the current RSCExamp resources. It should be placed in the same folder as the RSCExamp source code (e.g. as the RSCExamp instructions suggest, c:\RSCExamp\ on the emulator (it is not needed when working on a real Symbian OS device as batch files are a feature of the Windows Operating System). Be sure to check that RSCExa*.rss also exist in this folder, or the batch file will not work correctly. Once you are ready to create your own resource files, you can use this .BAT as a basis or template for one which will build all of your own resources.

To create your own resource files, you will have to write the .RSS source file. Each source file will vary greatly between different applications, both in content and layout, hence it is difficult to illustrate how to write the one you will need. However, a useful example is the program supplied with this document, RSCExamp. This is clearly commented, and should serve to illustrate all the fundamental concepts required for writing .RSS files. You could also use it as a basis for your own files if you become stuck.

If you are worried that the layout of .RSS files looks confusing, and the whole process seems to be a lot of extra work, then don’t! To address the first issue, it only looks confusing because it is new - once you have adjusted to the principles involved, you will find that working with resource files becomes second nature to you. And to address the second point, it probably is more work initially to get a resource file written and working. However, the end result is worth it. If you are not convinced, run the RSCExamp program and see how quick and easy it is to change languages at the touch of a button – and this occurs throughout the entire program too. Add to this the fact that all language dependent text is included in the .RSS file, making life easy for translators, and you have a very powerful and useful format. All it requires is a little groundwork.

4. Compiling resource files

Once the resource script is written you will need to compile it. This is done using the tools supplied with the OPL SDK. To stick with our example program, RSCExamp, bring up a command prompt in Windows and change directory to the folder where you installed the source code under the emulator (e.g. \epoc32\wins\c\RSCExamp\). To compile an individual resource, you would simply type:

EIKRSS RSCExamp UK rel

Looking at this more closely, the EIKRSS part will call the batch file supplied with this document which will invoke the compiler, etc. to do the work for you. RSCExamp is the name of the resource script (RSCExamp.rss in this case) – note that it is important that the file name is supplied without the extension. The third part, UK, is probably the most important. This tells the compiler what the target language of the resource file will be. Also note, that language codes must be in upper case.

When writing the .RSS file, it is entirely possible for you to include lines which differentiate between one or more potential languages as the file is being compiled, for example:

#ifdef LANGUAGE_UK
	RESOURCE TBUF text_colour {buf="Colour";}
	RESOURCE TBUF text_colour_grey {buf="Grey";}
#else
	RESOURCE TBUF text_colour {buf="Color";}
	RESOURCE TBUF text_colour_grey {buf="Gray";}
#endif

You will find a couple of examples of this technique within the RSCExamp.rss file. However, it should be noted that this method is really only suitable for languages which differ slightly. UK and US English variants are the prime example, as shown above and also with RSCExamp.rss.

If the languages differ vastly (e.g. English and French), then it is more advisable to create a separate .RSS file for each. Again, RSCExamp illustrates this by having RSCExamp.rss for the UK and US English languages, RSCExaFR.rss for the French and RSCExaGE.rss for the German. The actual names of these files do not matter, so long as the correct argument is passed when you use EIKRSS.bat – the French resource file could be called ‘Madness.rss’ so long as you called ‘EIKRSS.bat Madness FR rel’! However, more meaningful names will obviously be helpful to you later on when you want to decide which resource scripts belong to which program, etc.

Although inadvisable, should you decide to do all language variants inside just one .RSS file, then you can put multiple RESOURCE TBUF lines within the #ifdef to save time and space, and group all the languages together. This is, again, illustrated in the RSCExamp.rss file (near the start).

To obtain the complete set of compiled resources for RSCExamp, you can either compile them individually like this:

EIKRSS RSCExamp UK rel
EIKRSS RSCExamp US rel
EIKRSS RSCExaFR FR rel
EIKRSS RSCExaGE GE rel

or, of course, you can simply run the ‘Make RSCExamp.bat’ file, as this does all of these for you and tidies up afterwards too.

For reference, the language codes used by the resource compiler are the same as those accepted by Makesis when writing PKG script files. For more details, see the Makesis instructions (‘Preparing applications for installation’) in the SDK.

The final part of the call to EIKRSS (rel) is not really important to OPL programmers. The resource tools which ship on the OPL SDK are the same ones which ship on the C++ SDK. This flag allows C++ developers to note whether the resource file should be compiled for use in a debug, release, Unicode, etc. environment. As far as OPL applications go, you will be safe to always call EIKRSS with the ‘rel’ (for ‘release’) flag.

5. The Output Files

After EIKRSS has finished, some new files will have been produced – these are the actual resource files. If you used ‘Make RSCExamp.bat’, you would end up with:

\epoc32\wins\c\System\Apps\RSCExamp\RSCExamp.rUK
\epoc32\wins\c\System\Apps\RSCExamp\RSCExamp.rUS
\epoc32\wins\c\System\Apps\RSCExamp\RSCExamp.rGE
\epoc32\wins\c\System\Apps\RSCExamp\RSCExamp.rFR
\epoc32\wins\c\System\Apps\RSCExamp\RSCExamp.rSG

The folder tree of \epoc32\wins\c\System\Apps\<RSCName>\ is the default output folder for the EIKRSS.bat file. If this does not exist, then \epoc32\wins\c\System\Apps\ will be used. However, ‘Make RSCExamp.bat’ includes a command which will create
\epoc32\wins\c\System\Apps\RSCExamp\ if it does not exist, so if you used ‘Make RSCExamp.bat’, that is always where the above files will be located.

The reason for this is so that when you switch back to the emulator to retranslate or use your application, the resource files are immediately in the correct place for it to ‘see’ them.

The only file listed above which is of any note at this point is the .RSG file. This is a list of the resource ‘variables’ and their values. This file needs converting into an OPL include file so that you can translate your application with it using the standard INCLUDE command. To do this conversion, you will need to use the small 'ConvRSG' program supplied with this document. When run, ConvRSG will create an OSG file in the same folder as the RSG file (on the emulator or your Symbian OS machine). This OSG file will be an Symbian OS OPL (‘Program’) document, and all the original #define statements which appear in the RSG will have been replaced by standard OPL CONST statements instead.

In your application code, all you need to do is include the OSG file at the top of the code, as you do for (for example) an OPX. The OSG file should be placed in the same folder as your main code file or in \System\OPL\ so that the translator can find it when you use the INCLUDE statement.

At this point, it is worth pointing out that the RSCExamp program is slightly nonstandard in the way it handles its resource files. The whole point of RSCExamp is to load a resource and then let you change that to a different one ‘on the fly’ - for example, it defaults to loading the UK English resource, but you can change the entire language and operation of the program into French by just altering which resource is loaded using the appropriate menu option. The purpose of this is to demonstrate how easy resource files make the creation of multi-lingual applications.

To facilitate this, RSCExamp expects a default resource file called RSCExamp.rUK, and it also looks for the existence of several other resources (RSCExamp.rUS, RSCExamp.rFR and RSCExamp.rGE) in the \System\Apps\RSCExamp\ folder.

Most ‘normal’ applications expect to find a default resource file called AppName.rsc (where AppName is the name of the application) in their \System\Apps\AppName\ folder, and they do not expect or check for the existence of other resource files as RSCExamp does.

This situation can be neatly handled by the Symbian OS Installer technologies, which allow you to specify multiple files for different languages inside your SIS file. When the user installs the application, only the relevant files for the language they select are installed, the others are discarded.

If RSCExamp were a ‘normal’ application, this PKG file (script file for Makesis - see the SDK for more details) illustrates how things would be installed:

; Example PKG for a multi-lingual application
; Last updated 06 January 2000
; Copyright (c) Symbian Ltd. 1999-2000. All Rights Reserved.
;
; Languages supported...
&EN,AM,FR,GE
;
; SIS file header (one ‘title’ for each language)...
#{"RSCExamp","RSCExamp","RSCExamp","RSCExamp"},
    (0x100016A0),1,00,029,ID
;
; Files to be removed when the app is removed. In this case we want 
    to
; remove the INI file (if one has been created)
""-"C:\System\Apps\RSCExamp\RSCExamp.ini",FN
;
;
; Language resource files (Essential) - language dependant
{
"\epoc32\wins\c\system\apps\RSCExamp\RSCExamp.rUK"
"\epoc32\wins\c\system\apps\RSCExamp\RSCExamp.rUS"
"\epoc32\wins\c\system\apps\RSCExamp\RSCExamp.rFR"
"\epoc32\wins\c\system\apps\RSCExamp\RSCExamp.rGE"
}-"!:\System\Apps\RSCExamp\RSCExamp.rsc"
;
; Application files (Essential) - language independent
"\epoc32\wins\c\system\apps\RSCExamp\RSCExamp.aif"-"!:
    \System\Apps\RSCExamp\RSCExamp.aif"
"\epoc32\wins\c\system\apps\RSCExamp\RSCExamp.app"-"!:
    \System\Apps\RSCExamp\RSCExamp.app"
"\epoc32\wins\c\system\apps\RSCExamp\RSCExamp.mbm"-"!:
    \System\Apps\RSCExamp\RSCExamp.mbm"

6. Using the Resource File in your Application

To use the new file within your application when it is running, you must first load it into memory. This has to be done using the ‘LoadRSC&:’ command from SYSTEM.OPX, e.g.

RSCId&=LoadRSC&:("c:\System\Apps\RSCExamp\RSCExamp.rUK")

To recall the variables from the file, simply use the SYSTEM.OPX command, ReadRSC$:, e.g.:

ReadRSC$:(TEXT_COLOUR&)

This returns a string which you labeled ‘Text_Colour' within the original .RSS file (see above). As always, RSCExamp is the best place to refer to a working situation of loading and reading from resource files.

It is important to note that every resource file (provided it is compiled with its own 4 letter ‘NAME’ variable as illustrated in the RSCExamp files) is unique. The data held in it also has unique identifiers. This means it is possible to use more than one resource file at a time. Simply load the files you wish to use, and ReadRSC$: will work out on its own inside which file the resource you want is, once you supply it the value from the INCLUDE file.

7. Using Resource Files on the ROM

Just as it is possible to use the contents of a resource file you have written yourself from RAM, it is also possible to use the contents of the standard resource files supplied in the ROM. For example, this OPL program will show how to obtain the locale value for the text ‘Busy’ for the current machine:

INCLUDE "SYSTEM.OXH"

CONST KSRBusy&=&F3B184

PROC Main:
	LOCAL RSCId&
	RSCId&=LoadRSC&:("Z:\System\Data\Eiksrv.rsc")
	PRINT ReadRSC$:(KSRBusy&)
	GET
ENDP

This can be applied to any of the resource files and using different numbers you can experiment to find the different resources. However, also be aware that it is not necessary to load the above ‘Eiksrv.rsc’ file from your OPL program. The reason being that this file is automatically loaded by every OPL program when it is run. Thus it is possible to simply execute the following code:

INCLUDE "SYSTEM.OXH"

CONST KSRBusy&=&F3B184

PROC Main:
	PRINT ReadRSC$:(KSRBusy&)
	GET
ENDP

To further facilitate the use of the standard System resources, you can use the OPL include file supplied with this document. Simply add the line INCLUDE "EIKON.OPH" at the top of your code (assuming you placed the file in \System\OPL\ as explained above), and all of the resources will be available to you via easy to use CONST values.

8. A Note About Long Integer Resources

The resource files used throughout this tutorial only make use of string values. This is mainly for reasons of simplicity. However, it is worth noting that OPL is also able to access long integer values from resource files. In the RSCExamp program where integers are needed (for example in some of the menu hotkeys), they have been coded as strings in the resource file and are then converted from a string to an integer using OPL’s VAL function. If you used this approach frequently, a small procedure would be advisable to help automate it, e.g.:

PROC RRL&:(aResourceID&)
	RETURN INT(VAL(ReadRSC$:(aResourceID&)))
ENDP

If you wish to use long integers directly you should define a new STRUCT at the top of your resource file, e.g.:

// Define new KEY structure
STRUCT KEY
	{
	LONG key;
	}

Further down the resource file you can then define resource to use this structure as follows:

RESOURCE KEY Resource_Name {key = 12;}
 

To gain access to this resource from your OPL program you need to use ReadRSCLong&: function in SYSTEM.OPX, i.e.:

PRINT ReadRSCLong&:(RESOURCE_NAME&)

would cause the value 12 to be printed based on the above declaration.

9. Acknowledgements

In compiling this document, we would like to express our thanks Gérald Aubard for translating the English resource file of RSCExamp into French, and to Fredy Ott for the German translation. Thanks also to Jochen Siegenthaler for compiling the EIKON.oph file.