# LOCE32 notes

Notes about the LOCE32 localisation framework for low-level EPOC components.

## 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`

Where platform is either ARMI, ARM4 or WINS, build is either UDEB or UREL and nn is a numeric locale identifier. Note that THUMB binaries are not built because the code in localisation DLLs is run inside the kernel (which is never THUMB). Note also that the code in localisation DLLs is also run outside the kernel. Localisation DLLs are in this respect the same as `E32`'s `EUSER.DLL` (i.e. in that they are run from both inside and outside the kernel). Therefore the localisation-DLL platform to use should match the platform of `EUSER.DLL` used in the ROM. (This is ARMI for a THUMB or ARMI ROM, and ARM4 for an ARM4 ROM.)

## 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:

Info | Description | Example
--- | --- | ---
LOCALE | The new locale | `America`
NAME | Symbolic locale name | `ELangAmerican`
NN | Numeric locale identifier | 10
XX | Two-letter locale identifier | US
YYY | Three-letter language identifier | ENG
0xUUUUUUUU | The UID | 0x1000659a

### 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`

Where platform is either ARMI, ARM4 or WINS and build is either UDEB or UREL. Note that the THUMB platform are not built for the reason outlined above.

## Creating a LOCE32 for a new EPOC platform

The following source files in `\LOCE32\SRC`:

- `LS_LAT1.CPP`
- `LS_TABLE.CPP`
- `LS_UNIC.CPP`

are direct copies of the corresponding files in the E32 component. When modifying LOCE32 for a new EPOC platform these files must be copied from the E32 component.

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`

When modifying LOCE32 for a new EPOC platform the locale settings, language and message source files must be synced with the corresponding source files in the E32 component.

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