LOCE32 notes

Contents

• Overview
• Structure of the LOCE32 component
• Adding a new locale
• Building LOCE32
• Creating a LOCE32 for a new EPOC platform

Overview

Localisation DLLs conform to an interface defined by E32 and they provide support for localisation for components that are too low-level to participate in the normal EPOC localisation mechanisms. LOCE32 provides several implementations of this interface.

Structure of the LOCE32 component

Directory structure

\LOCE32

Contains an overall "Bldmake" project file.

\LOCE32\DOC

Contains this file.

\LOCE32\MMPFILES

Contains "Makmake" project files for each locale.

\LOCE32\SRC

Contains the source code for building the localisation DLLs.

Source files

Localisation DLLs are built from variants of the following source files in the \LOCE32\SRC directory:

LS_CYxx.CPP

Contains default locale settings like distance units, currency symbol, date and time formats, etc. (also some code to vary the behaviour of F32's FAT file system).

LS_LNyyy.CPP

Contains things like day names, month names, etc.

LS_MSyyy.CPP

Contains messages that base software may need to issue without the benefit of access to compiled resources.

LS_LAT1.CPP, LS_TABLE.CPP, LS_UNIC.CPP

Contain standard Latin1, Unicode character encoding and the Collation data for the locale.

Where xx is a two-letter locale identifier and yyy is a three-letter language identifier.

Build files

Like most EPOC components, LOCE32's build is controlled by two EPOC tools, "Makmake" and "Bldmake":

Makmake project files

Each Makmake file describes one locale-specific version of the localisation DLL. Makmake files are named:

ELOCLxx.MMP

Where by convention xx is a the same two-letter locale identifier mentioned above.

Bldmake project file

The Bldmake file BLD.INF contains a list of names of Makmake project files. Bldmake will only build localisation DLLs that are described by Makmake project files that are listed in this file.

Binaries

LOCE32 builds a number of locale-specific versions of the localisation DLL. These DLLs are given filenames of the following form:

\epoc32\release\platform\build\ELOCL.nn

Adding a new locale

LOCE32 is supplied with source for a number of locales. Further locales may be added by copying and modifying the source for an existing locale and by modifying the Makmake and Bldmake files.

Choosing identifiers

Before you start adding a locale you will first need to discover and choose appropriate identifiers for the source files and for the filename of the resulting localisation DLL.

Find the symbolic name for the locale in the file \epoc32\include\e32std.h. The locales supported by EPOC may be found inside the TLanguage list at around line 200 of that file. Eg the symbolic name for the American locale is ELangAmerican.

Determine the numeric identifier for the locale. The numeric identifier is found from the position of the locale in the TLanguage list when couting from zero, eg ELangTest is the zeroth locale and ELangAmerican is the tenth locale so the numeric identifier for American is 10.

Choose a new two-letter identifier for the new locale, eg "US" for America. If the new locale uses a language not already supplied with LOCE32 then also choose a new three-letter language identifier, eg "ENG" for English.

In summary, you need the following information which will be referred to below:

Source files

The source files reside in the \LOCE32\SRC directory:

Locale settings file

If possible identify an existing locale settings file (LS_CY*.CPP) that is for a locale broadly similar to the new locale. Otherwise start with LS_CYUK.CPP for the UK locale. Copy your chosen existing locale settings file to LS_CYxx.CPP.

Modify the new copy of the locale settings file for the new locale. The first source code line of the locale settings file should use the symbolic locale name obtained from e32std.h:

const TLanguage LCountry::Language = NAME;

Note: LCountry::CountryCode in this file is a redundant value that remains for backwards compatibility but is no longer used and need not be edited.

Language and message files

If the new locale uses a language not already supplied with LOCE32 then copy the English language file LS_LNENG.CPP and message file LS_MSENG.CPP to LS_LNyyy.CPP and LS_MSyyy.CPP respectively. Replace the quoted English text in your copies of these files with translations.

Collation rules and tables

EPOC follows the Unicode Collation algorithm.This system allows almost any kind of collation behaviour to be expressed. The collation data are stored in tables.The Collation Method consists of two sets of tables. The first set provides the standard keys, the optional second set tailors them for a particular locale.See the definition of TCollationMethod in \e32\include\collate.h:

The standard rules, which form the base from which the tailoring or tailorings for a given locale differ, are encoded as constant static data in \e32\euser\unicode\collate.cpp. The locale-specific rules for the default locale are kept in \loce32\src\ls_unic.cpp. Locale-specific rules for other locales are kept in other files of the form \loce32\src\ls_unic_yyy.cpp, where yyy is the language name or locale code to be decided upon. For example see the collation method for the Japanese locale in: \loce32\src\ls_unic_template_japanese.cpp

The standard rules might not be sufficient for locales that uses exotic character sets, for example Japanese, Arabic, etc. They might have collation rules that are specific to their language. Internationalisation provides a tool Coltab that allows the user to create the locale specific tailored collation table. To get a better understanding of Coltab read: //Londata04/Internationalisation/V6/COLTAB.doc

Build files

The build files reside in the \LOCE32 directory:

Makmake project file

Copy the Makmake project file for the UK locale ELOCLUK.MMP to ELOCLxx.MMP and replace the text marked below:

// ELOCLxx.MMP
//
// Copyright (c) 1997-1999 Symbian Ltd.  All rights reserved.
//

//
// Localisation DLL for LOCALE
//

TARGET          elocl.NN

TARGETTYPE      dll

SOURCEPATH      ..\src
SOURCE          ls_cyxx.cpp ls_lnyyy.cpp ls_msyyy.cpp
SOURCE          ls_lat1.cpp ls_table.cpp ls_unic.cpp

SYSTEMINCLUDE   \epoc32\include \epoc32\include\kernel

#if defined(WINS)
DEFFILE         \epoc32\release\wins\elocl.def
#elif defined(MARM)
DEFFILE         \epoc32\release\marm\elocl.def
#else
error
#endif

LIBRARY         euser.lib

START WINS
BASEADDRESS     0x58000000
END

UID      0x100039e6 0xUUUUUUUU

Bldmake project files

Add the name of the new Makmake project file without the .MMP extension (ie ELOCLxx) to the Bldmake project file BLD.INF.

Building LOCE32

Building LOCE32 requires a full OAK to be installed. LOCE32 uses the standard EPOC build tools (documented elsewhere). In short to build all the localisation DLLs change directory to \LOCE32 and type:

1. bldmake bldfiles
2. abld build or abld build platform build

Creating a LOCE32 for a new EPOC platform

The following source files in \LOCE32\SRC:

• LS_LAT1.CPP
• LS_TABLE.CPP
• LS_UNIC.CPP

The locale settings, language and message source files in \LOCE32\SRC are localised copies of the following files in the E32 component:

• LS_CYUK.CPP
• LS_LENG.CPP
• LS_MSG.CPP

A small point to note. With the Elocl DLLs there is a DLL name ELOCL.LOC. This is used as a default locale if the Window Server cannot find the locale DLL that it tries to get from the Hal. Since in WINS Hal returns nothing, ELOCL.LOC is the default locale. To change a locale in WINS, rename the required locale DLL as ELOCL.LOC.