You are currently viewing a snapshot of www.mozilla.org taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to www.mozilla.org, please file a bug.

Skip to main content

Platform Independent String Resources

- About file include/allxpstr.h

Draft: April 17,1998
Contact: Frank Tang <ftang@netscape.com>
Discussion: netscape.public.mozilla.i18n or mozilla-i18n@mozilla.org

Abstract

Mozilla source code stores all the cross-platform localizable strings in the file include/allxpstr.h . This paper discusses how to add additional strings into it, how to access them from the run-time, and concludes with the direction of future development.

History

  • 1.1i: First added

  • 2.0: No Major change.

  • 3.0:

    • Changed Macintosh build process from calling a Perl script in MPW to build it inside a Project file.

    • The Windows resources are built into a separate resource DLL (RESDLL.DLL) file. The location of the DLL is decided by a value in the registry.

  • 4.0:

    • Added GetStringForHTML API to solve the "Subject:", "To:", "Cc:" problem in Messenger.

    • the Macintosh resources are built into a separate resource file ("Essential Files:Netscape Resources").

    • The location of the Windows DLL is no longer decided by a value in the registry. The program simply uses the DLL in the same directory as the executable.

  • Free Source:

    • The Macintosh resources file is renamed from "Netscape Resources" to "Mozilla Resources"

How It Works

What Should Be Put Into This File?

All the cross-platform human readable text displayed by the Mozilla user interface should be put into ns/include/allxpstr.h:

  • Cross-platform text: This file contains all the text used in cross-platform code. Only cross-platform strings should be put in this file.

  • Human readable text: This file contains only human readable text. It is recommended to put English-like protocol code into this file if Mozilla needs to display it to the user (such as "Subject:", "Date:", "To:" in RFC822). The display to screen code should map the protocol code into human readable text (even if the protocol code and human readable text are the same in English) by using the platform independent string resource facility to achieve the goal of user friendliness. However, it should send the protocol code to the wire directly without mapping.

  • Whole sentences: See "Mozilla Localizability Guidelines" for details.

What Should Not Be Put Into This File?

  • Front-End only text: Text used by only one platform should not be put into this file. They should put into platform dependent resource formats. Otherwise, these strings will be built into each platform's binary, unecessarily increasing the size of that binary.

  • Protocol code: Protocol code (such as "Content-Type" in HTTP header) should not be put into allxpstr.h so translators won't accidentally change the protocol by changing the protocol code (in other words, prevent over-translation).

  • Partial sentences: See "Mozilla Localizability Guidelines" for details.

Development Model

  • Development: Developers working on the cross-platform code should make their code localizable by first putting all the human readable text into this file with a unique id. Then they should use the function XP_GetString (or XP_GetStringForHTML) in their cross-platform code to access this text. In the build process, this file is compiled into platform dependent resource files.

  • Localization: Translators may either translate this file directly into different language, or they may work on the compiled version in each platform's binary resource files. (Currently, for Windows and Macintosh, localization is done on the platform specific binary resource file, using leveraging tools and resource editing tools to help them.)

  • Run-Time: In the run-time, the functions XP_GetString and XP_GetStringForHTML access the compiled resource file by calling underlying platform dependent functions. These will access the different language version resources depending on which localized Mozilla they installed. In Unix, this also depends on which Locale the user selected before launching Mozilla. (Users can install multiple language versions of resource file.)

How To Put The Text Into It?

The include/allxpstr.h file is divided into several sections. Each section contains

  1. One and only one RES_START

  2. One and only one BEGIN_STR(section_name)

  3. Several ResDef(MESSAGE_ID, msg_number, msg). This is where you add your human readable text.

  4. One and only END_STR(section_name)
where

  • section_name is a unique name representing this section. This section_name is needed later in the build process. You don't need to refer to it in the C/C++ source file. In most cases, you should put your message into the mcom_include_xp_msg_i_strings section.

  • MESSAGE_ID is a unique name. Used this id in the C/C++ source file when you call the function XP_GetString or XP_GetStringForHTML.

  • msg_number is a sequential number. You don't need to refer to it in the C/C++ source file.

  • msg is the referenced English message. Translators produce different language versions of allxpstr.h by translating this reference English. If you are using XP_GetStringForHTML() , you should make sure this is the same as the third argument EnglishMessage you put into XP_GetStringForHTML() .

How To Access This Text From C/C++ Source File?

  1. In the beginning of the C/C++ source file, add the line 
        #include "xpgetstr.h"

  2. In the beginning of the C/C++ source file, put down: (Note: in C++ file, remember to put extern "C" { and } around the include statement ) 
        #define WANT_ENUM_STRING_IDS
    #include "allxpstr.h"
    #undef WANT_ENUM_STRING_IDS

  3. In the place where you need to refer to the human readable text, call
    XP_GetString(MESSAGE_ID)
    This function will return a pointer to a global buffer which contains the human readable string. The caller should make a copy of that string if it needs to use it later. The caller should not free the memory returned by the function. See the XP_GetString on-line documentation [ADD LINK HERE] for details.

  4. If the text will be generated into HTML and mixed with content gotten from server, call
    XP_GetStringForHTML(MESSAGE_ID, CharSetID, EnglishMessage)
    instead. The reason is the charset used by the server content may not be the same as the one in the localized resource string. This function will compare the CharSetID with the charset used by the localized message (returned by INTL_ResourceCharSet() ). It will return the localized message if the charsets agree with each other, otherwise, the EnglishMessage will be used.

Example: (ns/lib/libnet/cvmime.c)

In the following example, the code displays a warning message "Cannot edit non-HTML documents!" to the user. The text is put into ns/include/allxpstr.h as: 
    ...
    ResDef(XP_EDITOR_NON_HTML, XP_MSG_BASE + 647,
           "Cannot edit non-HTML documents!")
    ...
In ns/lib/libnet/cvmime.c, the accessing code looks like: 
    ...
    #include "xpgetstr.h"
    extern int XP_EDITOR_NON_HTML;
    ...
        FE_Alert(window_id, XP_GetString(XP_EDITOR_NON_HTML));
    ...

Platform Details:

Macintosh:

  • The text in this file is built as "STR " resource types in the "Essential Files:Mozilla Resources" file.

Window:

  • The text in this file is built as STRINGTABLE resource types in the "PROGRAM/resdll.dll" file.

Unix:

  • The text in this file is built as X Window's resources in the Mozilla.ad file.

Misc.:

Why Not Using GETTEXT in Unix ?

For Unix, some people have asked us to use GETTEXT, instead of the X Window's Resource Manager. The reason we decided not to use GETTEXT is the lack of a standard binary format, lack of standard resource compiler usage, and lack of standard installation tools across different variation of Unix. Currently, the X Window's Resource Manager is standard and widely available on all the UNIX platforms upon which we build. We had a similar answer for requests to use the message system in XPG (catopen/catclose/catgets)

Where It's Headed

We have discussed changing the current implementation for years. Unfortunately, we still haven't changed it. Why? Maybe because we are too busy to fix other *NEW THINGS*, when this platform independent string resources system is in an *OK* stage.

We know the current implementation has the following problems. If you are interested in enhancing the system, consider these issues:

  • This file has become a hot spot. Everyone who works on the cross-platform code needs to touch this file. Conflicting number assignment in our parallel development environment causes a lot of problems. It will be worse in the open source development environment.

  • The final result is not 100% sharable across platforms.

  • Only one level of indexing. It is difficult to store a list of name-value pairs.

  • It is difficult to switch languages on-the-fly. This is indirectly related to the issue above.
As we know, there are some risks to changing the current system. Consider these when you think you can improve it:

  • We currently have in-house leveraging tools which reduce the cost of translation across versions. Changing the system means it is also necessary to change the leveraging tools.

  • It is difficult to educate English speaking developers to externalize text from code. Changing the system in a complex way may discourage them to do it.
Copyright © 1998 Netscape Communications Corporation