
===============================================================================
                  Internationalization (I18N) For OS/2                 
===============================================================================

                Copyright IBM Corporation -- 1993, 1994, 1995

DISCLAIMER: This package is not a full implementation of the X/Open XPG4 
specification and does not make any claims of XPG4 branding. It implements 
only the portions of the XPG4 specification which deal with 
internationalization.

X/Open is a trademark of the X/Open Company Limited.

===============================================================================


/************************/
/***     Contents     ***/
/************************/

1.  Overview
2.  How to run the sample program
3.  How to compile the sample program
4.  Files in this directory
5.  How to add a new locale to the WORLD demo
6.  Notes

1.  Overview
============

This directory contains the "world" program.  world is a simple PM application
which uses some of the I18N functions.  It also demonstrates many of the
techniques one can use to internationalize PM programs, including message
catalogs, an icon per locale (where the icon can be changed outside of the
executable program), internationalized dialogs (centered, with no hard-coded
buttons), and more.

The program shows a map of the world, and some cities for which there are
locales defined.  Clicking on the box next to a city shows a dialog box
with culturally formatted information, and a list of strings which can be
collated in a cultural manner.  Pressing the "collate" button will cause the
strings in the list box to be sorted.

WORLD can also display its messages (static text) in different languages.
Selecting a locale from the "Messages" menu will cause the static text
(such as titles, menus, and buttons) to be converted over to the language
of that locale.  In addition, the minimized icon will change to the flag
of the new locale.  Selecting the "Show icons" option in the options menu
will toggle between text and flag bitmaps in the "Messages" menu.

WORLD is extensively commented, and can be used as a template of an
interationalized PM program.


2.  How to run the sample program
=================================

The following steps show how the program can be run.

     1) Run the \i18n\bin\new_vars command file (or have the environment
        variables already set).

     2) Execute the world.exe program.

          Ex:   world


3.  How to compile the sample program
=====================================

NOTE: The sample program is already compiled for you.  If you want to see the
 behavior of the program, you can just run it.  The following instructions
 are needed only if you want to modify the program and recompile it.

To compile the sample application:

     1) Make sure that the CSET/2 compiler and OS/2 toolkit are installed
        correctly on your system.

     2) cd to the directory which contains the info source files.

     3) Type "build" at the command prompt.


4.  Files in this directory
===========================

File            Purpose
------------------------------------------------------------------------------
world.c         Source code for the world sample program.
world.h         Include file for the program.
localpth.h      Include file for the locale path dialog.
about.h         Include file for the about dialog.

wrld.msg        English language version of the message catalog.

world.rc        Resource file for the program.
about.dlg       Dialog definition for the about dialog box.
localpth.dlg    Dialog definition for the locale path dialog box.
world.dlg       Dialog definitions for the world program.

world.def       Definition file needed for compiling the program.
world.mak       Make file used to compile the sample.
world.exe       Compiled version of the world sample.

texas.ico       Texas flag icon for the about dialog box.
*.bmp           Bitmaps of the locale flags used in the menu.

build.cmd       A command file which will compile and link the sample program.
read.me         This file.

In addition, there are message catalogs and icon files for each locale already
written for you.  They are located in the directories: \i18n\messages\xxyyzzzz
where "xxyyzzzz" is a locale name.

In each of these directories, the file: "wrld.cat" is the message catalog,
and the file: "world.ico" is the minimized icon to use for that locale.  Users
can use the ICONEDIT program to change the icons for any of the locales.


5.  How to add a new locale to the WORLD demo
=============================================

The following are the steps to follow to add a new locale to the WORLD demo
program:

     1) Add a new city on the world bitmap (WORLD.BMP) with a program such as
        PC Paintbrush (ICONEDIT cannot hold the bitmap for WORLD).
     2) Add the following to world.h:
        A) Add a new define for the locale menu item (look for MENU_LANGS_LANG0)
        B) Add a new define for the locale bitmap (look for BITMAP_LANG0).
        C) Increase the NUM_LOCALES by 1.
        D) Add a new #define for the locale (look for LOCALE_EN_US).
        E) Add to the end of the "locale_names" array.
        F) Add to the array of dialog locations ("locale_locs").
        G) Add to the array of hit test locations ("locale_hit_locs").  This may
            take some experimenting (with clicking the mouse) to see where the
            proper rectangle hit location is.
     3) Add a .bmp file for the flag of the locale to the WORLD directory.
     4) Add a .ico file for the flag (called world.ico) in a locale directory
         (ex: \i18n\messages\enus437\world.ico).
     5) Add the following to world.rc:
        A) Add a BITMAP statement for the bitmap added in #3 above (with the
            same name as in #2B above).
        B) Add a new menu item to the MENU_LANGS menu.
     6) Add the following to world.c:
        A) Add a new case to the switch statement for the new menu item
            (look for "case MENU_LANGS_LANG1").
     7) Add the following to world.mak:
        A) Add a dependency for the world.res file for the new bitmap file
            (look for usa.bmp).
     8) Add the following to each existing message catalog:
        A) A string for the locale name (look for MEN_LANGS_LANG0).
        B) A country name (look for 3020 - which is United States).
     9) Add a translated message catalog for the new locale to the proper
         locale directory (such as \i18n\messages\xxxxxxxx\wrld.cat), where
         xxxxxxxx is the new locale name.


6.  Notes
=========

1. Some of the locales (jajp, araa) use code sets which are not natively
   supported on most versions of OS/2.  Thus, the messages may not be displayed
   correctly on the screen for those locales (because OS/2 cannot render the
   proper arabic or kanjii characters).  If WORLD is run on a machine which
   *does* support those code pages, the messages will display correctly.
