|
0
|
1 |
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
|
|
|
2 |
<!--
|
|
|
3 |
Copyright (c) 1999-2009 Nokia Corporation and/or its subsidiary(-ies).
|
|
|
4 |
All rights reserved.
|
|
|
5 |
This component and the accompanying materials are made available
|
|
|
6 |
under the terms of the License "Eclipse Public License v1.0"
|
|
|
7 |
which accompanies this distribution, and is available
|
|
|
8 |
at the URL "http://www.eclipse.org/legal/epl-v10.html".
|
|
|
9 |
|
|
|
10 |
Initial Contributors:
|
|
|
11 |
Nokia Corporation - initial contribution.
|
|
|
12 |
|
|
|
13 |
Contributors:
|
|
|
14 |
|
|
|
15 |
Description:
|
|
|
16 |
|
|
|
17 |
-->
|
|
|
18 |
|
|
|
19 |
|
|
|
20 |
|
|
|
21 |
<HTML>
|
|
|
22 |
<HEAD>
|
|
|
23 |
<TITLE>LOCE32 notes</TITLE>
|
|
|
24 |
</HEAD>
|
|
|
25 |
|
|
|
26 |
<BODY>
|
|
|
27 |
|
|
|
28 |
<H1 ALIGN = CENTER>LOCE32 notes</H1>
|
|
|
29 |
|
|
|
30 |
Notes about the LOCE32 localisation framework for low-level EPOC
|
|
|
31 |
components.
|
|
|
32 |
|
|
|
33 |
<H2><A NAME="contents">Contents</A></H2>
|
|
|
34 |
|
|
|
35 |
<UL>
|
|
|
36 |
<LI><A HREF="#overview">Overview</A></LI>
|
|
|
37 |
<LI><A HREF="#structure">Structure of the LOCE32 component</A></LI>
|
|
|
38 |
<LI><A HREF="#adding">Adding a new locale</A></LI>
|
|
|
39 |
<LI><A HREF="#building">Building LOCE32</A></LI>
|
|
|
40 |
<LI><A HREF="#creating">Creating a LOCE32 for a new EPOC platform</A></LI>
|
|
|
41 |
</UL>
|
|
|
42 |
|
|
|
43 |
<H2><A NAME="overview">Overview</A></H2>
|
|
|
44 |
|
|
|
45 |
<P>
|
|
|
46 |
Localisation DLLs conform to an interface defined by <CODE>E32</CODE> and they provide
|
|
|
47 |
support for localisation for components that are too low-level to
|
|
|
48 |
participate in the normal EPOC localisation mechanisms. LOCE32
|
|
|
49 |
provides several implementations of this interface.
|
|
|
50 |
</P>
|
|
|
51 |
|
|
|
52 |
<H2><A NAME="structure" HREF="#contents">Structure of the LOCE32 component</A></H2>
|
|
|
53 |
|
|
|
54 |
<H3>Directory structure</H3>
|
|
|
55 |
|
|
|
56 |
<DL>
|
|
|
57 |
<DT><CODE>\LOCE32</CODE></DT>
|
|
|
58 |
<DD>Contains an overall "Bldmake" project file.</DD>
|
|
|
59 |
<DT><CODE>\LOCE32\DOC</CODE></DT>
|
|
|
60 |
<DD>Contains this file.</DD>
|
|
|
61 |
<DT><CODE>\LOCE32\MMPFILES</CODE></DT>
|
|
|
62 |
<DD>Contains "Makmake" project files for each locale.</DD>
|
|
|
63 |
<DT><CODE>\LOCE32\SRC</CODE></DT>
|
|
|
64 |
<DD>Contains the source code for building the localisation DLLs.</DD>
|
|
|
65 |
</DL>
|
|
|
66 |
|
|
|
67 |
<H3>Source files</H3>
|
|
|
68 |
|
|
|
69 |
<P>
|
|
|
70 |
Localisation DLLs are built from variants of the following source files
|
|
|
71 |
in the \LOCE32\SRC directory:
|
|
|
72 |
<DL>
|
|
|
73 |
<DT><CODE>LS_CY<VAR>xx</VAR>.CPP</CODE></DT>
|
|
|
74 |
<DD>Contains default locale settings like distance units, currency symbol, date and time formats,
|
|
|
75 |
etc. (also some code to vary the behaviour of F32's FAT file system).</DD>
|
|
|
76 |
<DT><CODE>LS_LN<VAR>yyy</VAR>.CPP</CODE></DT>
|
|
|
77 |
<DD>Contains things like day names, month names, etc.</DD>
|
|
|
78 |
<DT><CODE>LS_MS<VAR>yyy</VAR>.CPP</CODE></DT>
|
|
|
79 |
<DD>Contains messages that base software may need to issue without the
|
|
|
80 |
benefit of access to compiled resources.</DD>
|
|
|
81 |
<DT><CODE>LS_LAT1.CPP, LS_TABLE.CPP, LS_UNIC.CPP</CODE></DT>
|
|
|
82 |
<DD>Contain standard Latin1, Unicode character encoding and the Collation data for the locale.</DD>
|
|
|
83 |
</DL>
|
|
|
84 |
</P>
|
|
|
85 |
<P>
|
|
|
86 |
Where <VAR>xx</VAR> is a two-letter locale identifier and <VAR>yyy</VAR>
|
|
|
87 |
is a three-letter language identifier.
|
|
|
88 |
</P>
|
|
|
89 |
|
|
|
90 |
<H3>Build files</H3>
|
|
|
91 |
|
|
|
92 |
<P>
|
|
|
93 |
Like most EPOC components, LOCE32's build is controlled by two EPOC
|
|
|
94 |
tools, "Makmake" and "Bldmake":
|
|
|
95 |
</P>
|
|
|
96 |
|
|
|
97 |
<H4>Makmake project files</H4>
|
|
|
98 |
|
|
|
99 |
<P>
|
|
|
100 |
Each Makmake file describes one locale-specific version of the
|
|
|
101 |
localisation DLL. Makmake files are named:
|
|
|
102 |
<BLOCKQUOTE>ELOCL<VAR>xx</VAR>.MMP</BLOCKQUOTE>
|
|
|
103 |
</P>
|
|
|
104 |
<P>
|
|
|
105 |
Where by convention <VAR>xx</VAR> is a the same two-letter locale
|
|
|
106 |
identifier mentioned above.
|
|
|
107 |
</P>
|
|
|
108 |
|
|
|
109 |
<H4>Bldmake project file</H4>
|
|
|
110 |
|
|
|
111 |
<P>
|
|
|
112 |
The Bldmake file <CODE>BLD.INF</CODE> contains a list of names of
|
|
|
113 |
Makmake project files. Bldmake will only build localisation DLLs that
|
|
|
114 |
are described by Makmake project files that are listed in this file.
|
|
|
115 |
</P>
|
|
|
116 |
|
|
|
117 |
<H3><A NAME="binaries">Binaries</A></H3>
|
|
|
118 |
|
|
|
119 |
<P>
|
|
|
120 |
LOCE32 builds a number of locale-specific versions of the localisation
|
|
|
121 |
DLL. These DLLs are given filenames of the following form:
|
|
|
122 |
<BLOCKQUOTE><CODE>\epoc32\release\<VAR>platform</VAR>\<VAR>build</VAR>\ELOCL.<VAR>nn</VAR></CODE></BLOCKQUOTE>
|
|
|
123 |
Where <VAR>platform</VAR> is either ARMI, ARM4 or WINS, <VAR>build</VAR> is
|
|
|
124 |
either UDEB or UREL and <VAR>nn</VAR> is a numeric locale
|
|
|
125 |
identifier. Note that THUMB binaries are not built because the code in
|
|
|
126 |
localisation DLLs is run inside the kernel (which is never THUMB). Note also that the
|
|
|
127 |
code in localisation DLLs is also run outside the kernel. Localisation DLLs
|
|
|
128 |
are in this respect the same as <CODE>E32</CODE>'s <CODE>EUSER.DLL</CODE>
|
|
|
129 |
(i.e. in that they are run from both inside and outside the kernel).
|
|
|
130 |
Therefore the localisation-DLL platform to use should match the platform of
|
|
|
131 |
<CODE>EUSER.DLL</CODE> used in the ROM. (This is ARMI for a THUMB or ARMI ROM,
|
|
|
132 |
and ARM4 for an ARM4 ROM.)
|
|
|
133 |
</P>
|
|
|
134 |
|
|
|
135 |
<H2><A NAME="adding" HREF="#contents">Adding a new locale</A></H2>
|
|
|
136 |
|
|
|
137 |
<P>
|
|
|
138 |
LOCE32 is supplied with source for a number of locales. Further locales
|
|
|
139 |
may be added by copying and modifying the source for an existing locale
|
|
|
140 |
and by modifying the Makmake and Bldmake files.
|
|
|
141 |
</P>
|
|
|
142 |
|
|
|
143 |
<H3>Choosing identifiers</H3>
|
|
|
144 |
|
|
|
145 |
<P>
|
|
|
146 |
Before you start adding a locale you will first need to discover and
|
|
|
147 |
choose appropriate identifiers for the source files and for the filename
|
|
|
148 |
of the resulting localisation DLL.
|
|
|
149 |
</P>
|
|
|
150 |
<P>
|
|
|
151 |
Find the symbolic name for the locale in the file
|
|
|
152 |
<CODE>\epoc32\include\e32std.h</CODE>. The locales supported by EPOC may
|
|
|
153 |
be found inside the <CODE>TLanguage</CODE> list at around line 200 of
|
|
|
154 |
that file. Eg the symbolic name for the American locale is
|
|
|
155 |
<CODE>ELangAmerican</CODE>.
|
|
|
156 |
</P>
|
|
|
157 |
<P>
|
|
|
158 |
Determine the numeric identifier for the locale. The numeric identifier
|
|
|
159 |
is found from the position of the locale in the <CODE>TLanguage</CODE>
|
|
|
160 |
list when couting from zero, eg <CODE>ELangTest</CODE> is the zeroth
|
|
|
161 |
locale and <CODE>ELangAmerican</CODE> is the tenth locale so the numeric
|
|
|
162 |
identifier for American is 10.
|
|
|
163 |
</P>
|
|
|
164 |
<P>
|
|
|
165 |
Choose a new two-letter identifier for the new locale, eg "US" for
|
|
|
166 |
America. If the new locale uses a language not already supplied with
|
|
|
167 |
LOCE32 then also choose a new three-letter language identifier, eg "ENG"
|
|
|
168 |
for English.
|
|
|
169 |
</P>
|
|
|
170 |
<P>
|
|
|
171 |
In summary, you need the following information which will be referred to
|
|
|
172 |
below:
|
|
|
173 |
</P>
|
|
|
174 |
<CENTER><TABLE BORDER=1>
|
|
|
175 |
<TR><TH>Info</TH><TH>Description</TH><TH>Example</TH></TR>
|
|
|
176 |
<TR><TD>LOCALE</TD><TD>The new
|
|
|
177 |
locale</TD><TD><CODE>America</CODE></TD></TR>
|
|
|
178 |
<TR><TD>NAME</TD><TD>Symbolic locale
|
|
|
179 |
name</TD><TD><CODE>ELangAmerican</CODE></TD></TR>
|
|
|
180 |
<TR><TD>NN</TD><TD>Numeric locale
|
|
|
181 |
identifier</TD><TD>10</TD></TR>
|
|
|
182 |
<TR><TD>XX</TD><TD>Two-letter locale identifier</TD><TD>US</TD></TR>
|
|
|
183 |
<TR><TD>YYY</TD><TD>Three-letter language identifier</TD><TD>ENG</TD></TR>
|
|
|
184 |
<TR><TD>0xUUUUUUUU</TD><TD>The UID</TD><TD>0x1000659a</TD></TR>
|
|
|
185 |
</TABLE></CENTER>
|
|
|
186 |
|
|
|
187 |
<H3>Source files</H3>
|
|
|
188 |
|
|
|
189 |
<P>
|
|
|
190 |
The source files reside in the <CODE>\LOCE32\SRC</CODE> directory:
|
|
|
191 |
</P>
|
|
|
192 |
|
|
|
193 |
<H4>Locale settings file</H4>
|
|
|
194 |
|
|
|
195 |
<P>
|
|
|
196 |
If possible identify an existing locale settings file
|
|
|
197 |
(<CODE>LS_CY*.CPP</CODE>) that is for a locale broadly similar to the
|
|
|
198 |
new locale. Otherwise start with <CODE>LS_CYUK.CPP</CODE> for the UK
|
|
|
199 |
locale. Copy your chosen existing locale settings file to
|
|
|
200 |
<CODE>LS_CY<VAR>xx</VAR>.CPP</CODE>.
|
|
|
201 |
</P>
|
|
|
202 |
<P>
|
|
|
203 |
Modify the new copy of the locale settings file for the new
|
|
|
204 |
locale. The first source code line of the locale settings file should
|
|
|
205 |
use the symbolic locale name obtained from <CODE>e32std.h</CODE>:
|
|
|
206 |
|
|
|
207 |
<BLOCKQUOTE><CODE>const TLanguage LCountry::Language =
|
|
|
208 |
<VAR>NAME</VAR>;</CODE></BLOCKQUOTE>
|
|
|
209 |
</P>
|
|
|
210 |
<P>
|
|
|
211 |
Note: <CODE>LCountry::CountryCode</CODE> in this file is a redundant
|
|
|
212 |
value that remains for backwards compatibility but is no longer used and
|
|
|
213 |
need not be edited.
|
|
|
214 |
</P>
|
|
|
215 |
|
|
|
216 |
<H4>Language and message files</H4>
|
|
|
217 |
|
|
|
218 |
<P>
|
|
|
219 |
If the new locale uses a language not already supplied with LOCE32 then
|
|
|
220 |
copy the English language file <CODE>LS_LNENG.CPP</CODE> and message
|
|
|
221 |
file <CODE>LS_MSENG.CPP</CODE> to <CODE>LS_LN<VAR>yyy</VAR>.CPP</CODE>
|
|
|
222 |
and <CODE>LS_MS<VAR>yyy</VAR>.CPP</CODE> respectively. Replace the
|
|
|
223 |
quoted English text in your copies of these files with translations.
|
|
|
224 |
</P>
|
|
|
225 |
|
|
|
226 |
<H4>Collation rules and tables</H4>
|
|
|
227 |
|
|
|
228 |
<P>
|
|
|
229 |
EPOC follows the Unicode Collation algorithm.This system allows almost any kind of collation behaviour to be expressed.
|
|
|
230 |
The collation data are stored in tables.The Collation Method consists of two sets of tables. The first set provides the standard keys,
|
|
|
231 |
the optional second set tailors them for a particular locale.See the definition of TCollationMethod in <code>\e32\include\collate.h</code>:
|
|
|
232 |
</P>
|
|
|
233 |
|
|
|
234 |
<P>
|
|
|
235 |
The standard rules, which form the base from which the tailoring or tailorings for a given locale differ,
|
|
|
236 |
are encoded as constant static data in <code>\e32\euser\unicode\collate.cpp.</code> The locale-specific rules
|
|
|
237 |
for the default locale are kept in <code>\loce32\src\ls_unic.cpp.</code> Locale-specific rules for other locales are
|
|
|
238 |
kept in other files of the form \loce32\src\ls_unic_<var>yyy</var>.cpp, where <var>yyy</var> is the language name or
|
|
|
239 |
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>
|
|
|
240 |
</P>
|
|
|
241 |
|
|
|
242 |
<P>
|
|
|
243 |
The standard rules might not be sufficient for locales that uses exotic character sets, for example Japanese,
|
|
|
244 |
Arabic, etc. They might have collation rules that are specific to their language. Internationalisation provides a
|
|
|
245 |
tool <var>Coltab</var> that allows the user to create the locale specific tailored collation table.
|
|
|
246 |
To get a better understanding of <var>Coltab</var> read:
|
|
|
247 |
|
|
|
248 |
<code>//Londata04/Internationalisation/V6/COLTAB.doc</code>
|
|
|
249 |
|
|
|
250 |
</P>
|
|
|
251 |
|
|
|
252 |
<H3>Build files</H3>
|
|
|
253 |
|
|
|
254 |
<P>
|
|
|
255 |
The build files reside in the <CODE>\LOCE32</CODE> directory:
|
|
|
256 |
</P>
|
|
|
257 |
|
|
|
258 |
<H4>Makmake project file</H4>
|
|
|
259 |
|
|
|
260 |
<P>
|
|
|
261 |
Copy the Makmake project file for the UK locale <CODE>ELOCLUK.MMP</CODE>
|
|
|
262 |
to <CODE>ELOCL<VAR>xx</VAR>.MMP</CODE> and replace the text
|
|
|
263 |
<B><VAR>marked</VAR></B> below:
|
|
|
264 |
</P>
|
|
|
265 |
|
|
|
266 |
<PRE>
|
|
|
267 |
// ELOCL<B><VAR>xx</VAR></B>.MMP
|
|
|
268 |
//
|
|
|
269 |
// Copyright (c) 1997-1999 Symbian Ltd. All rights reserved.
|
|
|
270 |
//
|
|
|
271 |
|
|
|
272 |
//
|
|
|
273 |
// Localisation DLL for <B><VAR>LOCALE</VAR></B>
|
|
|
274 |
//
|
|
|
275 |
|
|
|
276 |
TARGET elocl.<B><VAR>NN</VAR></B>
|
|
|
277 |
|
|
|
278 |
TARGETTYPE dll
|
|
|
279 |
|
|
|
280 |
SOURCEPATH ..\src
|
|
|
281 |
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
|
|
|
282 |
SOURCE ls_lat1.cpp ls_table.cpp ls_unic.cpp
|
|
|
283 |
|
|
|
284 |
SYSTEMINCLUDE \epoc32\include \epoc32\include\kernel
|
|
|
285 |
|
|
|
286 |
#if defined(WINS)
|
|
|
287 |
DEFFILE \epoc32\release\wins\elocl.def
|
|
|
288 |
#elif defined(MARM)
|
|
|
289 |
DEFFILE \epoc32\release\marm\elocl.def
|
|
|
290 |
#else
|
|
|
291 |
error
|
|
|
292 |
#endif
|
|
|
293 |
|
|
|
294 |
LIBRARY euser.lib
|
|
|
295 |
|
|
|
296 |
START WINS
|
|
|
297 |
BASEADDRESS 0x58000000
|
|
|
298 |
END
|
|
|
299 |
|
|
|
300 |
UID 0x100039e6 <B><VAR>0xUUUUUUUU</VAR></B>
|
|
|
301 |
</PRE>
|
|
|
302 |
|
|
|
303 |
<H4>Bldmake project files</H4>
|
|
|
304 |
|
|
|
305 |
<P>
|
|
|
306 |
Add the name of the new Makmake project file without the .MMP extension
|
|
|
307 |
(ie <CODE>ELOCL<VAR>xx</VAR></CODE>) to the Bldmake project file
|
|
|
308 |
<CODE>BLD.INF</CODE>.
|
|
|
309 |
</P>
|
|
|
310 |
|
|
|
311 |
<H2><A NAME="building" HREF="#contents">Building LOCE32</A></H2>
|
|
|
312 |
|
|
|
313 |
<P>
|
|
|
314 |
Building LOCE32 requires a full OAK to be installed. LOCE32 uses the
|
|
|
315 |
standard EPOC build tools (documented elsewhere). In short to build
|
|
|
316 |
all the localisation DLLs change directory to
|
|
|
317 |
<CODE>\LOCE32</CODE> and type:
|
|
|
318 |
<OL>
|
|
|
319 |
<LI><CODE>bldmake bldfiles</CODE></LI>
|
|
|
320 |
<LI><CODE>abld build</CODE> or
|
|
|
321 |
<CODE>abld build <VAR>platform</VAR> <VAR>build</VAR></CODE></LI>
|
|
|
322 |
</OL>
|
|
|
323 |
|
|
|
324 |
Where <VAR>platform</VAR> is either ARMI, ARM4 or WINS and <VAR>build</VAR> is
|
|
|
325 |
either UDEB or UREL. Note that the THUMB platform are not built
|
|
|
326 |
for the reason outlined <A HREF="#binaries">above</A>.
|
|
|
327 |
</P>
|
|
|
328 |
|
|
|
329 |
<H2><A NAME="creating" HREF="#contents">Creating a LOCE32 for a new EPOC platform</A></H2>
|
|
|
330 |
|
|
|
331 |
<P>
|
|
|
332 |
The following source files in <CODE>\LOCE32\SRC</CODE>:
|
|
|
333 |
<UL>
|
|
|
334 |
<LI><CODE>LS_LAT1.CPP</CODE></LI>
|
|
|
335 |
<LI><CODE>LS_TABLE.CPP</CODE></LI>
|
|
|
336 |
<LI><CODE>LS_UNIC.CPP</CODE></LI>
|
|
|
337 |
</UL>
|
|
|
338 |
are direct copies of the corresponding files in the E32 component. When
|
|
|
339 |
modifying LOCE32 for a new EPOC platform these files must be copied from
|
|
|
340 |
the E32 component.
|
|
|
341 |
</P>
|
|
|
342 |
|
|
|
343 |
<P>
|
|
|
344 |
The locale settings, language and message source files in
|
|
|
345 |
<CODE>\LOCE32\SRC</CODE> are localised copies of the following files in
|
|
|
346 |
the E32 component:
|
|
|
347 |
<UL>
|
|
|
348 |
<LI><CODE>LS_CYUK.CPP</CODE></LI>
|
|
|
349 |
<LI><CODE>LS_LENG.CPP</CODE></LI>
|
|
|
350 |
<LI><CODE>LS_MSG.CPP</CODE></LI>
|
|
|
351 |
</UL>
|
|
|
352 |
When modifying LOCE32 for a new EPOC platform the locale settings,
|
|
|
353 |
language and message source files must be synced with the corresponding
|
|
|
354 |
source files in the E32 component.
|
|
|
355 |
</P>
|
|
|
356 |
|
|
|
357 |
<P>
|
|
|
358 |
A small point to note. With the Elocl DLLs there is a DLL name <code>ELOCL.LOC</code>.
|
|
|
359 |
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>.
|
|
|
360 |
</P>
|
|
|
361 |
<HR>
|
|
|
362 |
|
|
|
363 |
</BODY>
|
|
|
364 |
</HTML>
|