*All information is Cobalt confidential*

Author: Kevin K.M. Chiu <kevin@cobalt.com>
$Id: i18nArchDesign.txt,v 1.2 2000/11/22 13:13:04 pbaltz Exp $

INTERNATIONALIZATION

REQUIREMENTS

    * Establish standardized ways to add, modify or remove locales to the
      architecture.

    * Establish standardized ways to add, modify or remove localization
      resources (e.g. strings, images, etc) to locale modules. Reources
	should be kept in standard places within the file system.


ARCHITECTURE DESIGN

    +----------+ +-----------------+
    |PHP Module| |Command-line Tool|
    +----------+ +-----------------+
          |               |
    +-----------------------------+
    |C Resource Management Library|
    +-----------------------------+


C RESOURCE MANAGEMENT LIBRARY

    A library of C functions is provided for locale resource management 
    purposes (See API below). Specifically, strings and file resources 
    are handled. This set of functions use GNU gettext (textdomain(), 
    gettext() and dgettext()) while adding features and supplying a more 
    stable interface (e.g. gettext may be substituted in the future).

    Locales are specified by strings that start with a ISO-639 2 letter 
    language code, followed by an optional ISO-3166 2 letter country code 
    and then an optional variant, all separated by underscores (e.g. en, 
    en_US, ja_JP_EUC).  The API definition below shows formal definition.

    A domain in this architecture means a group of similar resources for a 
    certain purpose. Often, a domain is mapped into one piece of software, 
    even though it is possible to have the software use resources from 
    several domains. For example, the email software utilizes resources in 
    the "email" domain.

    Locale negotiation is performed separately for each domain, and each 
    domain is able to define a 'default' locale to use in the event that 
    negotiation fails.  This enables us to have different sets of locales 
    for different 3PD-contributed domains.


APPLICATION PROGRAMMING INTERFACE

    The entire API is syntactically defined in spec.i18n.lib.txt.

    This library of C functions is accessible by other C/C++, Java, Perl 
    and command-line interface. C/C++ can directly call the library. Java 
    can access the library by a concrete subclass of ResourceBundle through 
    JNI. Perl can access through a wrapper. Other languages can access the 
    library through a wrapper command-line interface. This makes different 
    programs in the system able to share and address the same locale 
    resources.


FILE LOCATIONS

    i18n_get() is used to access string resources. It relies on GNU gettext.  
    Therefore, strings are stored in <domain>.mo files under 
    /usr/share/locale/<locale>/LC_MESSAGES/. 

    Locale property files are placed under /usr/share/locale/<locale>/ and 
    named in a .prop extension. For example, a German locale property file 
    for VPN is placed under /usr/share/locale/de/vpn.prop. 


THE GENERIC DOMAIN

    Strings for the "generic" domain is supplied by default. This domain 
    contains strings that are generic and can be shared across different 
    programs. For example, "Cannot open file [[var.file]]" and "Directory 
    [[var.directory]] does not exist" are strings within this domain.

    To get the string "fileNotFound" from the "generic" domain, the locale 
    preference of the requesting user is examined. i18n_get() is then called 
    with the domain parameter = "generic" to fetch the string.


LOCALE

    The system decides which locale to use based on this simple algorithm.  
    Locale preference of the user is looked up. If preference is a specific 
    locale, use it. Otherwise, user must have selected "browser selected" 
    because there are no other choices. In this case, the language preference 
    from the HTTP_ACCEPT_LANGUAGE header is used.


COMPONENT

    Locales are being packaged as components. Locale components contain only 
    locale-sensitive data that specifies a particular locale. For example, 
    strings, images, audio, currency format, date format and number format 
    are packaged into locale components. Strings are stored in gettext .mo 
    files under /usr/share/locale/<locale>/LC_MESSAGES/. Images and audio 
    files are stored under /usr/sausalito/ui/file/web/.  Absolute pathnames 
    are to be determined. 

    Locale components are classified in two dimensions - locale and owner, 
    because the system needs to handle new locale and new features. Owner 
    can be core, Apache manager, BIND manager and so on. Apache manager may 
    want the string "apacheDown" displayed through the user interface and 
    this string is stored under the locale modules for Apache manager. For 
    example, there can be an english locale for the core, english locale for
    Apache manager, Japanese locale for the core and Japanese locale for 
    Apache manager.

*All information is Cobalt confidential*
