My first commit on the Symbian Hg repository. Testng how branches are working.
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<!--
Copyright (c) 1999-2009 Nokia Corporation and/or its subsidiary(-ies).
All rights reserved.
This component and the accompanying materials are made available
under the terms of the License "Eclipse Public License v1.0"
which accompanies this distribution, and is available
at the URL "http://www.eclipse.org/legal/epl-v10.html".
Initial Contributors:
Nokia Corporation - initial contribution.
Contributors:
Description:
-->
<HTML>
<HEAD>
<TITLE>LOCE32 notes</TITLE>
</HEAD>
<BODY>
<H1 ALIGN = CENTER>LOCE32 notes</H1>
Notes about the LOCE32 localisation framework for low-level EPOC
components.
<H2><A NAME="contents">Contents</A></H2>
<UL>
<LI><A HREF="#overview">Overview</A></LI>
<LI><A HREF="#structure">Structure of the LOCE32 component</A></LI>
<LI><A HREF="#adding">Adding a new locale</A></LI>
<LI><A HREF="#building">Building LOCE32</A></LI>
<LI><A HREF="#creating">Creating a LOCE32 for a new EPOC platform</A></LI>
</UL>
<H2><A NAME="overview">Overview</A></H2>
<P>
Localisation DLLs conform to an interface defined by <CODE>E32</CODE> 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.
</P>
<H2><A NAME="structure" HREF="#contents">Structure of the LOCE32 component</A></H2>
<H3>Directory structure</H3>
<DL>
<DT><CODE>\LOCE32</CODE></DT>
<DD>Contains an overall "Bldmake" project file.</DD>
<DT><CODE>\LOCE32\DOC</CODE></DT>
<DD>Contains this file.</DD>
<DT><CODE>\LOCE32\MMPFILES</CODE></DT>
<DD>Contains "Makmake" project files for each locale.</DD>
<DT><CODE>\LOCE32\SRC</CODE></DT>
<DD>Contains the source code for building the localisation DLLs.</DD>
</DL>
<H3>Source files</H3>
<P>
Localisation DLLs are built from variants of the following source files
in the \LOCE32\SRC directory:
<DL>
<DT><CODE>LS_CY<VAR>xx</VAR>.CPP</CODE></DT>
<DD>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).</DD>
<DT><CODE>LS_LN<VAR>yyy</VAR>.CPP</CODE></DT>
<DD>Contains things like day names, month names, etc.</DD>
<DT><CODE>LS_MS<VAR>yyy</VAR>.CPP</CODE></DT>
<DD>Contains messages that base software may need to issue without the
benefit of access to compiled resources.</DD>
<DT><CODE>LS_LAT1.CPP, LS_TABLE.CPP, LS_UNIC.CPP</CODE></DT>
<DD>Contain standard Latin1, Unicode character encoding and the Collation data for the locale.</DD>
</DL>
</P>
<P>
Where <VAR>xx</VAR> is a two-letter locale identifier and <VAR>yyy</VAR>
is a three-letter language identifier.
</P>
<H3>Build files</H3>
<P>
Like most EPOC components, LOCE32's build is controlled by two EPOC
tools, "Makmake" and "Bldmake":
</P>
<H4>Makmake project files</H4>
<P>
Each Makmake file describes one locale-specific version of the
localisation DLL. Makmake files are named:
<BLOCKQUOTE>ELOCL<VAR>xx</VAR>.MMP</BLOCKQUOTE>
</P>
<P>
Where by convention <VAR>xx</VAR> is a the same two-letter locale
identifier mentioned above.
</P>
<H4>Bldmake project file</H4>
<P>
The Bldmake file <CODE>BLD.INF</CODE> 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.
</P>
<H3><A NAME="binaries">Binaries</A></H3>
<P>
LOCE32 builds a number of locale-specific versions of the localisation
DLL. These DLLs are given filenames of the following form:
<BLOCKQUOTE><CODE>\epoc32\release\<VAR>platform</VAR>\<VAR>build</VAR>\ELOCL.<VAR>nn</VAR></CODE></BLOCKQUOTE>
Where <VAR>platform</VAR> is either ARMI, ARM4 or WINS, <VAR>build</VAR> is
either UDEB or UREL and <VAR>nn</VAR> 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 <CODE>E32</CODE>'s <CODE>EUSER.DLL</CODE>
(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
<CODE>EUSER.DLL</CODE> used in the ROM. (This is ARMI for a THUMB or ARMI ROM,
and ARM4 for an ARM4 ROM.)
</P>
<H2><A NAME="adding" HREF="#contents">Adding a new locale</A></H2>
<P>
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.
</P>
<H3>Choosing identifiers</H3>
<P>
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.
</P>
<P>
Find the symbolic name for the locale in the file
<CODE>\epoc32\include\e32std.h</CODE>. The locales supported by EPOC may
be found inside the <CODE>TLanguage</CODE> list at around line 200 of
that file. Eg the symbolic name for the American locale is
<CODE>ELangAmerican</CODE>.
</P>
<P>
Determine the numeric identifier for the locale. The numeric identifier
is found from the position of the locale in the <CODE>TLanguage</CODE>
list when couting from zero, eg <CODE>ELangTest</CODE> is the zeroth
locale and <CODE>ELangAmerican</CODE> is the tenth locale so the numeric
identifier for American is 10.
</P>
<P>
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.
</P>
<P>
In summary, you need the following information which will be referred to
below:
</P>
<CENTER><TABLE BORDER=1>
<TR><TH>Info</TH><TH>Description</TH><TH>Example</TH></TR>
<TR><TD>LOCALE</TD><TD>The new
locale</TD><TD><CODE>America</CODE></TD></TR>
<TR><TD>NAME</TD><TD>Symbolic locale
name</TD><TD><CODE>ELangAmerican</CODE></TD></TR>
<TR><TD>NN</TD><TD>Numeric locale
identifier</TD><TD>10</TD></TR>
<TR><TD>XX</TD><TD>Two-letter locale identifier</TD><TD>US</TD></TR>
<TR><TD>YYY</TD><TD>Three-letter language identifier</TD><TD>ENG</TD></TR>
<TR><TD>0xUUUUUUUU</TD><TD>The UID</TD><TD>0x1000659a</TD></TR>
</TABLE></CENTER>
<H3>Source files</H3>
<P>
The source files reside in the <CODE>\LOCE32\SRC</CODE> directory:
</P>
<H4>Locale settings file</H4>
<P>
If possible identify an existing locale settings file
(<CODE>LS_CY*.CPP</CODE>) that is for a locale broadly similar to the
new locale. Otherwise start with <CODE>LS_CYUK.CPP</CODE> for the UK
locale. Copy your chosen existing locale settings file to
<CODE>LS_CY<VAR>xx</VAR>.CPP</CODE>.
</P>
<P>
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 <CODE>e32std.h</CODE>:
<BLOCKQUOTE><CODE>const TLanguage LCountry::Language =
<VAR>NAME</VAR>;</CODE></BLOCKQUOTE>
</P>
<P>
Note: <CODE>LCountry::CountryCode</CODE> in this file is a redundant
value that remains for backwards compatibility but is no longer used and
need not be edited.
</P>
<H4>Language and message files</H4>
<P>
If the new locale uses a language not already supplied with LOCE32 then
copy the English language file <CODE>LS_LNENG.CPP</CODE> and message
file <CODE>LS_MSENG.CPP</CODE> to <CODE>LS_LN<VAR>yyy</VAR>.CPP</CODE>
and <CODE>LS_MS<VAR>yyy</VAR>.CPP</CODE> respectively. Replace the
quoted English text in your copies of these files with translations.
</P>
<H4>Collation rules and tables</H4>
<P>
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 <code>\e32\include\collate.h</code>:
</P>
<P>
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 <code>\e32\euser\unicode\collate.cpp.</code> The locale-specific rules
for the default locale are kept in <code>\loce32\src\ls_unic.cpp.</code> Locale-specific rules for other locales are
kept in other files of the form \loce32\src\ls_unic_<var>yyy</var>.cpp, where <var>yyy</var> is the language name or
locale code to be decided upon. For example see the collation method for the Japanese locale in: <code>\loce32\src\ls_unic_template_japanese.cpp </code>
</P>
<P>
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 <var>Coltab</var> that allows the user to create the locale specific tailored collation table.
To get a better understanding of <var>Coltab</var> read:
<code>//Londata04/Internationalisation/V6/COLTAB.doc</code>
</P>
<H3>Build files</H3>
<P>
The build files reside in the <CODE>\LOCE32</CODE> directory:
</P>
<H4>Makmake project file</H4>
<P>
Copy the Makmake project file for the UK locale <CODE>ELOCLUK.MMP</CODE>
to <CODE>ELOCL<VAR>xx</VAR>.MMP</CODE> and replace the text
<B><VAR>marked</VAR></B> below:
</P>
<PRE>
// ELOCL<B><VAR>xx</VAR></B>.MMP
//
// Copyright (c) 1997-1999 Symbian Ltd. All rights reserved.
//
//
// Localisation DLL for <B><VAR>LOCALE</VAR></B>
//
TARGET elocl.<B><VAR>NN</VAR></B>
TARGETTYPE dll
SOURCEPATH ..\src
SOURCE ls_cy<B><VAR>xx</VAR></B>.cpp ls_ln<B><VAR>yyy</VAR></B>.cpp ls_ms<B><VAR>yyy</VAR></B>.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 <B><VAR>0xUUUUUUUU</VAR></B>
</PRE>
<H4>Bldmake project files</H4>
<P>
Add the name of the new Makmake project file without the .MMP extension
(ie <CODE>ELOCL<VAR>xx</VAR></CODE>) to the Bldmake project file
<CODE>BLD.INF</CODE>.
</P>
<H2><A NAME="building" HREF="#contents">Building LOCE32</A></H2>
<P>
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
<CODE>\LOCE32</CODE> and type:
<OL>
<LI><CODE>bldmake bldfiles</CODE></LI>
<LI><CODE>abld build</CODE> or
<CODE>abld build <VAR>platform</VAR> <VAR>build</VAR></CODE></LI>
</OL>
Where <VAR>platform</VAR> is either ARMI, ARM4 or WINS and <VAR>build</VAR> is
either UDEB or UREL. Note that the THUMB platform are not built
for the reason outlined <A HREF="#binaries">above</A>.
</P>
<H2><A NAME="creating" HREF="#contents">Creating a LOCE32 for a new EPOC platform</A></H2>
<P>
The following source files in <CODE>\LOCE32\SRC</CODE>:
<UL>
<LI><CODE>LS_LAT1.CPP</CODE></LI>
<LI><CODE>LS_TABLE.CPP</CODE></LI>
<LI><CODE>LS_UNIC.CPP</CODE></LI>
</UL>
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.
</P>
<P>
The locale settings, language and message source files in
<CODE>\LOCE32\SRC</CODE> are localised copies of the following files in
the E32 component:
<UL>
<LI><CODE>LS_CYUK.CPP</CODE></LI>
<LI><CODE>LS_LENG.CPP</CODE></LI>
<LI><CODE>LS_MSG.CPP</CODE></LI>
</UL>
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.
</P>
<P>
A small point to note. With the Elocl DLLs there is a DLL name <code>ELOCL.LOC</code>.
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, <code>ELOCL.LOC</code> is the default locale. To change a locale in WINS, rename the required locale DLL as <code> ELOCL.LOC</code>.
</P>
<HR>
</BODY>
</HTML>