[Last updated at Build 0.5.5]

AbiWord Localization

Version 1.0

Jeff Hostetler

jeff@abisource.com

AbiSource, Inc.

1. Introduction

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.

2. Overview

No, we don't use gettext. Sorry.

3. Steps

Our localization procedure consists of three basic steps:
[1] create a LabelSet for the menu;
[2] create a LabelSet for the toolbar; and

[3] create a set of strings for the dialogs and error messages.

3.1. Menu LabelSet

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:
[a] the Potential Set of menu actions (the complete set of actions to which a menu item may be bound);
[b] the set of menu-helper functions (used to compute gray-state and etc. on menu activation);
[c] a series of Menu_Layouts (one or more nested lists giving the Menu_Items and their ordering);
[d] a series of Menu_LabelSets (one for each language we want to support).

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.

The part we are most interested in is [d]. The file abi/src/wp/ap/xp/ap_Menu_LabelSet_en-US.h 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 BeginSet() macro. Save this new file by substituting the en-US with your language identifier. Finally, add an #include line to ap_Menu_LabelSet_Languages.h

3.2. Toolbar LabelSet

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 B for the BOLD button and a slanted I for the ITALIC button; this is appropriate in English, but might not be in other languages.

The file abi/src/wp/ap/xp/ap_TB_LabelSet_en-US.h 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 BeginSet() macro and add a #include line in ap_TB_LabelSet_Languages.h

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 ap_Toolbar_Icons_All.h -- be sure to add it to both sections in this file.

3.3. Dialog and Error Messages

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 xx-XX.string file for all other languages.

With a DEBUG build of version 0.5.5 (or later), launch AbiWord with the command:

./AbiWord -dumpstrings

This will create the file en-US.strings 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 language= in the AbiStrings tag. Also be sure to update the credits for the translation near the top of the file. Save this file in the abi/user/wp/strings directory.

3.3.1. Caveats

As of 0.5.5, there are a few problems with this:

[1] Sometimes, expat (the XML parser that we use) doesn't like some high-byte Latin-1 characters. I've had it choke on ä 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 (ä for example).

[2] We currently following Win32 convention of using & 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 & -- I'm currently looking for an alternative way of dealing with this....

3.4 system.profile files

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 xx-YY is your locale.

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.

Common variables found:

[1] DocumentLocale: your xx-YY from above. This is used to set the default language of the document being edited

[2] RulerUnits: inch, cm, mm

[3] DefaultPageSize: Letter, A4, B3, etc...

3.5 Add a new entry for your language/locale in the language dialog

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

3.6 Add a new entry for your language in the spell-checking code

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

4. Testing Your Translation

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

[1] look at your preferences file:

on Unix this is ~/.AbiSuite/AbiWord.Profile

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

[2] change both occurrences of _builtin_ to custom.

[3] change all three instances of en-US to your language identifier.

[4] either change the value of {Win32,Unix,BeOS}StringSetDirectory to the directory you placed the .strings file or move the .strings file to the directory listed in this value.

[5] launch AbiWord again. In the debug output, you should find something like the following:

Found strings file for application [AbiWord] (this is [AbiWord]).

Found strings for language [fi-FI].

Using StringSet [C:\work\abi\user\wp\strings\fi-FI.strings]

If you are missing any strings in the .strings file, you'll see warning like the following:

WARNING: Translation for id [DLG_Zoom_ZoomTitle] not found.

WARNING: Translation for id [DLG_Zoom_RadioFrameCaption] not found.

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

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

5. Maintenance Issues

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.

We'll need your help to occasionally review the translation files and update them as things change in the English version. Thanks.