WHAT'S GTKCONV?		(This file is in early alpha stage.) -*-text-*-

  gtkconv is an new feature of Gtk+ for execution-time localization of its
  applications.


BASIC IDEA:

  Main idea is modifying gtk_label_set as:

  void
  gtk_label_set (GtkLabel *label, gchar *str)
  {
     str = look_up_dictionary (str);

     /* original work */
  }

  (The current version of gtkconv converts text in label, frame, tooltips
  widgets.)

  Since gtk+ is an internationalized program based on locale system, you can
  use English and one more language (coding system) for real text labels.
  By converting `str' to corresponding string in the language with
  dictionary in gtk/gdk layer, most gtk+ applications can be localized in
  transparent way (i.e., any modifications are no need).

  Conversion is done only if environment variable: GDK_CONV is set.
  If it isn't set, there is no difference from the original gtk.


IS THIS A SUBSTITUTE (ALTERNATIVE) FOR GETTEXT?

  NO. We don't intend that gtkconv is a substitute for gettext.  If you make
  a new program on gtk+, please use gettext instead of gtkconv. gtkconv is a
  localization mechanism of the program that made ONLY FOR ENGLISH USER. The
  gimp is one of the biggest examples, that is huge and developed by a lot
  of programmer without gettext.  Making a patch for i18n-ed gimp is tough
  work rather than gtkconv approach, isn't it?

  And there is another demerit. Since now gtk_label_set changes the string
  to another string internally, any program that uses gtk_label_get would
  not work! 
  To solve this problem (partially?), we added a new member to GtkLabel
  widget: orig_label. Here's current definitions:

  void
  gtk_label_set (GtkLabel *label, gchar *str)
  {
     label->label = look_up_dictionary (str);
     label->orig_label = str;

     /* original work */
  }

  void
  gtk_label_get (GtkLabel *label, char **str)
  {
    if label-uses-converted-string
      *str = label->orig_label;
    else  
      *str = label->label;
  }

  It also would not work on some programs, but rarely (we hope).

DICTIONARY:

  The dictionary used for conversion is read in gtk's initialization step:
  gtk_init().
  To reduce the size of dictionary, each gtk application has a corresponding
  dictionary determined by the application's name (gtk_programname in gtk
  layer). For example, "menu.gimp" is used for gimp's dictionary,
  "menu.testgtk" for testgtk similarly.

  Furthermore, you can choose the dictionaries' directory by the value of an
  environment variable: GDK_CONV, which holds the pathname for a directory
  (files). 
  For example, if you have two dictionary directories: German, Spanish in
  /usr/share/gtk, you can choose one by (supposed you use sh instead of csh):

     GDK_CONV=/usr/share/gtk/german gimp
  or 
     GDK_CONV=/usr/share/gtk/spanish gimp

  Finally, after loading a dictionary for the application in the directory
  $GDK_CONV, a default dictionary: "menu.default" in the same directory is
  also loaded.

  Dictionary is TAB separated phrase list like:

		### English to Japanese
  Japan				Nippon
  Japanese old clothes		Kimono

  (A line starting with TAB, like the first line of above example, is treated
  as a comment line.)

  This distribution contains sample dictionary files under menu.jp_JP for
  Japan-ization. But gtkconv will work for most languages.


INSTALL:

  Apply patch "gtkconv.patch" to a flesh gtk+, (shell script:
  ../apply-gtkconv will work if you extracted gtkconv.tar.gz under the
  directory which has gtk+-$(VERSION) as a subdirectory.)

  then do: ./configure; make
  (if your OS does not recognize locale add --with-locale to configure, as
  described in gtk/INSTALL) 


USAGE:

  1. User settings about locale are required. You should set some environment
     variables: LANG, LC_ALL, LC_CTYPE to suitable values. 
  2. set an environment variable: GDK_CONV as above.
  3. set fontset resource for default or label widget in file: gtkrc for the
     application which you want to localize. 
     Without it, conversion is never invoked.


NOTE:

  All of files are distributed under LGPL.

--
Wed Jul 1 23:34:00 1998
Yoichi Izumi <asura@hi-ho.ne.jp>
Shuji Narazaki <narazaki@gimp.org>
The latest version is placed in:  http://www.hi-ho.ne.jp/~asura/gtk/gtkconv.html#current
