1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
|
<?xml version="1.0"?>
<abiword version="unnumbered" fileformat="1.0">
<!-- ===================================================================== -->
<!-- This file is an AbiWord document. -->
<!-- AbiWord is a free, Open Source word processor. -->
<!-- You may obtain more information about AbiWord at www.abisource.com -->
<!-- You should not edit this file by hand. -->
<!-- ===================================================================== -->
<!-- Build_ID = (none) -->
<!-- Build_Version = unnumbered -->
<!-- Build_Options = LicensedTrademarks:Off Debug:On BiDi:Off Bonobo:Off DirectPrint:On Gnome:On LibXML:Off Pspell:On Scripting:Off -->
<!-- Build_Target = /home/dom/abiword/abi/src/../src/Linux_2.2.14-5.0_i386_GNOME/obj -->
<!-- Build_CompileTime = 17:09:03 -->
<!-- Build_CompileDate = Jun 21 2001 -->
<pagesize pagetype="Letter" orientation="portrait" width="8.500000" height="11.000000" units="inch" page-scale="1.000000"/>
<section>
<p style="Plain Text">[Last updated at Build 0.5.5]</p>
<p style="Plain Text"></p>
<p style="Plain Text"></p>
<p style="Normal" props="text-align:center"><c props="font-weight:bold; font-size:24pt">AbiWord Localization</c></p>
<p props="text-align:center">Version 1.0</p>
<p props="text-align:center">Copyright (C) 1999 AbiSource, Inc., All Rights Reserved.</p>
<p></p>
<p props="text-align:center"><c props="font-style:italic">Jeff Hostetler</c></p>
<p style="Plain Text" props="text-align:center">jeff@abisource.com</p>
<p props="text-align:center">AbiSource, Inc.</p>
<p></p>
<p><c props="font-weight:bold">1. Introduction</c></p>
<p></p>
<p>This document describes the steps necessary to localize AbiWord to a new language. At the present time (build 0.5.5) localization is limited to the strings for menu and toolbars that are compiled into the executable and the strings for various dialogs and error message boxes that can be dynamically loaded at runtime. We have not yet addressed localization issues for the application installers, on-line help, manuals, and etc.</p>
<p></p>
<p><c props="font-weight:bold">2. Overview</c></p>
<p></p>
<p>No, we don't use <c props="font-family:Courier New">gettext</c>. Sorry.</p>
<p></p>
<p><c props="font-weight:bold">3. Steps</c></p>
<p></p>
<p>Our localization procedure consists of three basic steps: <br/> [1] create a LabelSet for the menu; <br/> [2] create a LabelSet for the toolbar; and </p>
<p> [3] create a set of strings for the dialogs and error messages.</p>
<p></p>
<p><c props="font-weight:bold">3.1. Menu LabelSet</c></p>
<p></p>
<p>AbiWord contains a dynamic, cross-platform menu system that allows various builtin (and eventually dynamically loaded) menu layouts to be selected and synthesized as needed. Code for the menu system is broken into the following parts: <br/> [a] the Potential Set of menu actions (the complete set of actions to which a menu item may be bound); <br/> [b] the set of menu-helper functions (used to compute gray-state and etc. on menu activation);<br/> [c] a series of Menu_Layouts (one or more nested lists giving the Menu_Items and their ordering);<br/> [d] a series of Menu_LabelSets (one for each language we want to support).</p>
<p></p>
<p>For most Latin-1 languages, you should be able to just use the Menu_Layouts as is. If, for example, your language has no concept of Italic, you might want to make a new layout which did not include Italic. It is my belief that this feature will not be used until we get to CJKV. I'll describe this in a future update.</p>
<p></p>
<p style="Normal">The part we are most interested in is [d]. The file <c props="font-family:Courier New">abi/src/wp/ap/xp/ap_Menu_LabelSet_en-US.h</c> contains the English strings that are used for the Menu_Items and the Status Bar Help Text. Clone this file and translate the values in the second and third columns. Note that despite the thick layer of CPP macros, this is in fact a C++ header file, so the string values must be legal C++. Also, give yourself credit for the translation near the top of the file (include your name and email address). Be sure to update the language identifier in the <c props="font-family:Courier New">BeginSet()</c> macro. Save this new file by substituting the <c props="font-family:Courier New">en-US</c> with your language identifier. Finally, add an <c props="font-family:Courier New">#include</c> line to <c props="font-family:Courier New">ap_Menu_LabelSet_Languages.h</c></p>
<p></p>
<p><c props="font-weight:bold">3.2. Toolbar LabelSet</c></p>
<p></p>
<p>AbiWord contains a dynamic, cross-platform toolbar system .... blah, blah, blah .... just like the menu system. The only difference is that the Toolbar_LabelSet also includes a reference to the icon to be used on the toolbar button. I put this here so that we could change the icon by language. For example, we use an icon with a fat <c props="font-weight:bold">B</c> for the BOLD button and a slanted <c props="font-style:italic; font-weight:bold">I</c> for the ITALIC button; this is appropriate in English, but might not be in other languages.</p>
<p></p>
<p>The file <c props="font-family:Courier New">abi/src/wp/ap/xp/ap_TB_LabelSet_en-US.h</c> contains the English button labels, tooltips, status messages, and icons. Clone this file (or one of the other translations) and make your changes. Again, please give yourself credit near the top. Again, be sure to update the language identifier in the <c props="font-family:Courier New">BeginSet()</c> macro and add a <c props="font-family:Courier New">#include</c> line in <c props="font-family:Courier New">ap_TB_LabelSet_Languages.h</c></p>
<p></p>
<p>If you'd like to change the icons -- especially for BOLD, ITALIC, UNDERLINE, and STRIKEOUT, look in the directory abi/src/wp/ap/xp/ToolbarIcons and see if there's an XPM that suits your needs or create one. If you do decide to create a new XPM, add a reference to it in <c props="font-family:Courier New">ap_Toolbar_Icons_All.h</c> -- be sure to add it to both sections in this file.</p>
<p></p>
<p><c props="font-weight:bold">3.3. Dialog and Error Messages</c></p>
<p></p>
<p>Menu and Toolbar strings are compiled into the source -- so that the program always remains mostly usable in each language no matter how trashed the system installation. Dialogs and Error Messages are builtin for English and are dynamically loaded from an x<c props="font-family:Courier New">x-XX.string</c> file for all other languages.</p>
<p></p>
<p>With a DEBUG build of version 0.5.5 (or later), launch AbiWord with the command:</p>
<p></p>
<p style="Plain Text" props="text-align:center">./AbiWord -dumpstrings</p>
<p></p>
<p>This will create the file en-<c props="font-family:Courier New">US.strings</c> in the current directory. This XML file can be used as a template. Simply edit this file and make your translations. Be sure to update the value of <c props="font-family:Courier New">language=</c> in the <c props="font-family:Courier New">AbiStrings</c> tag. Also be sure to update the credits for the translation near the top of the file. Save this file in the <c props="font-family:Courier New">abi/user/wp/strings</c> directory.</p>
<p></p>
<p><c props="font-weight:bold">3.3.1. Caveats</c></p>
<p></p>
<p>As of 0.5.5, there are a few problems with this:</p>
<p></p>
<p>[1] Sometimes, expat (the XML parser that we use) doesn't like some high-byte Latin-1 characters. I've had it choke on <c props="font-weight:bold; font-family:Courier New; font-size:12pt">ä</c> in one place in the file but not in another. I'm still looking into this. If this causes you problems, you can substitute an XML numeric entity for the character (<c props="font-weight:bold; font-family:Courier New; font-size:12pt">&#xE4;</c> for example).</p>
<p></p>
<p>[2] We currently following Win32 convention of using <c props="font-weight:bold; font-family:Courier New; font-size:12pt">&</c> in a string to indicate the letter that should be underlined in a dialog. (The Win32 version passes it straight through and the Unix/GTK version either strips it our or translates it into the necessary widget calls to get it to work.) You may use this at your discretion, but you'll need to see the resulting dialog to check for duplicates and make the letter placement make sense in your language. Also, the ampersand character is a reserved character in XML, so you'll need to escape it using <c props="font-weight:bold; font-family:Courier New; font-size:12pt">&amp;</c> -- I'm currently looking for an alternative way of dealing with this....</p>
<p></p>
<p><c props="font-weight:bold">3.4 system.profile files</c></p>
<p><c props="font-weight:normal"></c></p>
<p><c props="font-weight:normal">These files are located in the abi/user/wp directory and set the default settings for your particular locale. These files’ names take the form ‘system.profile-xx-YY’ where </c><c props="font-weight:bold">xx-YY</c><c props="font-weight:normal"> is your locale.</c></p>
<p><c props="font-weight:normal"></c></p>
<p><c props="font-weight:normal">The contents of these files are simple and straightforward. Your best bet is to copy an existing file over to your locale and edit it. </c></p>
<p><c props="font-weight:normal"></c></p>
<p><c props="font-weight:normal">Common variables found:</c></p>
<p><c props="font-weight:normal"></c></p>
<p><c props="font-weight:normal">[1] DocumentLocale: your xx-YY from above. This is used to set the default language of the document being edited</c></p>
<p><c props="font-weight:normal">[2] RulerUnits: inch, cm, mm</c></p>
<p><c props="font-weight:normal">[3] DefaultPageSize: Letter, A4, B3, etc...</c></p>
<p></p>
<p><c props="font-weight:bold">3.5 Add a new entry for your language/locale in the language dialog</c></p>
<p><c></c></p>
<p>In src/af/util/xp/ut_Language you’ll see a list of locale/language mappings. This is used to mark words as being in a particular language and is used by the spell-checker and could be used in a thesaurus, etc...</p>
<p><c></c></p>
<p><c props="font-weight:bold">3.6 Add a new entry for your language in the spell-checking code</c></p>
<p></p>
<p>You’ll want to add a locale/hashfile mapping for ispell dictionaries in src/other/spell/xp/ispell_checker.cpp - it’s 1 line of code</p>
<p></p>
<p><c props="font-weight:bold">4. Testing Your Translation</c></p>
<p></p>
<p>Testing your translation is a little awkward at this point because we haven't gotten the installer finished or the options/preferences dialog to let you interactively change your language. So, for now, we do it the hard way...</p>
<p></p>
<p>[1] look at your preferences file:</p>
<p props="margin-left:1.2cm">on Unix this is <c props="font-family:Courier New">~/.AbiSuite/AbiWord.Profile</c></p>
<p props="text-indent:0.0cm; margin-left:1.2cm">on Win32 this is varies considerably between Windows versions and how the system was installed, so check the debug output for the message "Constructed preference file name ...".</p>
<p></p>
<p>[2] change both occurrences of <c props="font-family:Courier New; font-weight:bold">_builtin_</c> to <c props="font-family:Courier New; font-weight:bold">custom</c>.</p>
<p></p>
<p>[3] change all three instances of <c props="font-weight:bold">en-</c><c props="font-family:Courier New; font-weight:bold">US</c> to your language identifier.</p>
<p></p>
<p>[4] either change the value of {<c props="font-family:Courier New">Win32</c>,<c props="font-family:Courier New">Unix</c>,<c props="font-family:Courier New">BeOS</c>}<c props="font-family:Courier New">StringSetDirectory</c> to the directory you placed the <c props="font-family:Courier New">.strings</c> file or move the <c props="font-family:Courier New">.strings</c> file to the directory listed in this value.</p>
<p>[5] launch AbiWord again. In the debug output, you should find something like the following:</p>
<p></p>
<p style="Plain Text"><c props="font-size:8pt">Found strings file for application [AbiWord] (this is [AbiWord]).</c></p>
<p style="Plain Text"><c props="font-size:8pt">Found strings for language [fi-FI].</c></p>
<p style="Plain Text"><c props="font-size:8pt">Using StringSet [C:\work\abi\user\wp\strings\fi-FI.strings]</c></p>
<p style="Plain Text"></p>
<p style="Normal">If you are missing any strings in the .strings file, you'll see warning like the following:</p>
<p style="Plain Text"></p>
<p style="Plain Text"><c props="font-size:8pt">WARNING: Translation for id [DLG_Zoom_ZoomTitle] not found.</c></p>
<p style="Plain Text"><c props="font-size:8pt">WARNING: Translation for id [DLG_Zoom_RadioFrameCaption] not found.</c></p>
<p style="Plain Text"></p>
<p style="Normal">[6] At this point, you have a **mostly** localized user-interface -- there are still some rough edges and places we still need help with, but all-in-all, this is a pretty good start.</p>
<p style="Normal"></p>
<p style="Normal">[7] email a patch file to me or to the abiword-dev mailing list and we'll get it into the next version of the source.</p>
<p style="Plain Text"></p>
<p><c props="font-weight:bold">5. Maintenance Issues</c></p>
<p></p>
<p>At present, AbiWord is still growing and evolving and occasionally there is a need to add new strings to the application. The code is set to use the selected language strings, if available, and to fall back to the builtin English strings when items are missing from the translation. The code is also set to issue warnings or asserts at startup should there be an incomplete translation.</p>
<p></p>
<p>We'll need your help to occasionally review the translation files and update them as things change in the English version. Thanks.</p>
<p></p>
</section>
</abiword>
|
