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