

Once a developer has internationalized their application the next step
is to test it.  In order to test internationalization (i18n) the
application needs to be run in a locale other than the native locale.
It becomes necessary to have one or more alternate locales available
without having to know a specific language.  The utility in this
directory and this file are designed to assist the developer in testing
an "i18nized" application using alternative locales.

A brief description of the makepo utility is followed by an
example of how to test a localized application. 

	makepo [options] <filename>

			Used to create various types of .po files.  No
			options will create a standard .po file from
			the input file (usually an existing
			.po that has been sorted and uniq
			(uniqued)).

			The -p option takes an existing .po file and
			creates a Piglatin translation of the msgid
			string as the msgstr string.  
			
			The -e option takes an existing .po file and
			creates a msgstr string made up of various
			European characters (8 bit characters) closely
			resembling the msgid string.

			The -v option allows replacement of any vowel
			in the msgid string with any number of similar
			vowels from zero to five.  This allows the
			developer to check out the display of their
			application when translated strings are shorter
			or longer than normal.  Obviously, "zero" means
			removal of all vowels.  
			
			Type makepo -? to see command line usage.

After an application has been internationalized (using the "-g" option
on gxv for Devguide based applications) the developer must create the
Portable Message Object files.  This is the file containing the
base-language text - the .po file.  The xgettext utility (/usr/bin)  is
used to extract the strings from the source file and create a .po
file.  The msgfmt utility (found in the same place as xgettext) is used
to compile the .po file into its binary form, a .mo file.

Once the .po file(s) has been created the developer will want to test
the localization of their product. A few things need to be done first:
	1) Decide on a locale for the application to run in.
	2) Make sure your application is able to tell the OS where 
	   the .mo files will be found (bindtextdomain()).
	3) Build and install the alternative .po file(s);

For example, to test an application in the Piglatin locale would go
something like this:

	1)	-Edit your .Xdefaults file and remove the following
		 lines

				*basicLocale:  C
				*displayLang:  C
				*inputLang:    C
				*numeric:      C
				*timeFormat:   C

		 NOTE:  these lines are placed in .Xdefaults each time you
			use the saveworkspace utility.

		-Tell your server you have modified your .Xdefaults
		 file

				% xrdb .Xdefaults
		

	2)	In the application's initialization code (usually in
		main()) a call should have been made to the
		bindtextdomain() function.  This function lets the OS
		know where the message file(s) can be found.  The first
		parameter to the function is the name of a message
		file, sometimes referred to as the domain name.  A
		message file is constructed like this:
		<domainname.suffix>, where suffix is "mo" or "po". The
		name of the domain that goes in the bindtextdomain call
		does not have the suffix attached. The second parameter
		is the path to where the databases of various locales
		can be found.  Example:

			Your .po file is called my_messages.po.  After
			running msgfmt you should have a binary called
			my_messages.mo.  This binary message file needs
			to be installed in the following directory:

			<user defined path>/<locale_name>/LC_MESSAGES

			For piglatin it would be:

			<user defined path>/piglatin/LC_MESSAGES
		
		The bindtextdomain() call would look like this:

			bindtextdomain(<domain name>, 
					<user defined path>);

		for this example:
			bindtextdomain("my_messages", 
					"/my/specified/path");

	4)	-Build and install the piglatin database (also called
		 message files):

		% makepo -p my_messages.po
		% msgfmt my_messages.po.new
		% mkdir -p /my/specified/path/piglatin/LC_MESSAGES
		% cp my_messages.mo /my/specified/path/piglatin/LC_MESSAGES

		- run your application using the -lc_displaylang
		  option, for example:
			% my_app_name -lc_displaylang piglatin
		
		- If the application is not displaying in piglatin
		  recheck the steps mentioned above and focus on the
		  following questions:

			- Does .Xdefaults have any references to some 
			  other locale.
			-"Are my files installed in the correct place?" 
			-"Are the parameters to bindtextdomain correct?"

	NOTE: SunOS 5.0 comes with several locales that the OS
	      understands. These are de, fr, it, ja, and sv. It is
	      recommended that you test your application using your own
	      locale, but these other ones can be used. There is one
	      benefit. If using the available locales, instead of
	      running the application with the -lc_displaylang option,
	      you can set the LANG environment variable to one of the
	      available locales (matching the directory you created
	      where the .mo files reside) beforehand. This is useful
	      if you want the application to always come up in it's
	      localized state, for instance, in a demo situation.

Other useful documentation includes the i18n appendix to the Devguide
3.0 gxv manual (part no. 800-6587-10) and the Software
Internationalization Guide (part no.  800-5972-08).

	Enjoy,
	The OpenWindows Developer's Guide Group

