NAME
====
  vg_get_textformat() - translate text according to current language


SYNOPSIS
========
  const char * vg_get_textformat(const char * text)


DESCRIPTION
===========
  To support multiple languages for your game, you have to
   - create files "textformat.<language>" and "textformat"
     according to the rules below
   - call vg_get_textformat() to translate the original text
     to the text of the current language before giving it out

  Rules for the "textformat.??"-files:
  Normally in your game you give out a text in your favourite language,
  let's say in english.

  E.g. you call:
    vg_draw_text(NULL,RGB_WHITE,0,0,"Hello Boy",NULL,RGB_FULL).
  To support multiple languages, now you have to change this call into:
    vg_draw_text(NULL,RGB_WHITE,0,0,vg_get_textformat("Hello Boy"),NULL,RGB_FULL).

  You see, you didn't change your favourite language and still have in your
  game the same text "Hello Boy".
  vg_get_textformat() looks up in the file "textformat" the string "Hello Boy"
  and replaces it according to the current selected language with the
  string which is at the same line in another file "textformat.??",
  where ?? is the shortcut (with 2 characters lowercase,
  e.g. "en" for english or "de" for german) of the current selected language.
  (See below how to select a language).

  The files "textformat" and "textformat.??" must be put
  into the local directory "share/" of your game.

  The file "textformat" must contain the same strings which are used
  in your game, because this file is used as reference file.
  As this file has no language extension, it is wise to create an extra file
  for the language used in your game with a language extension
  and create "textformat" as a symlink to this extra file,
  e.g. if the language in your game is english:
    share/
      textformat -> textformat.en
      textformat.en
      textformat.de
      ...

  As mentioned above, all files "textformat.??" must have at the same line
  the same text, translated to their specific language.
  However not counted are empty lines and comment lines beginning with a "#".
  E.g. "textformat.en" is counted as follows:
    # this is a comment

    Hello Boy             <-- line 1
    At Stans woodhouse    <-- line 2

    # error messages
    Cannot believe it     <-- line 3
    That's not right      <-- line 4

  and is therefore the same as:
    Hello Boy
    At Stans woodhouse
    Cannot believe it
    That's not right

  Example:
  The text in your game is in english,
  and you support english ("en") and german ("de").
  Your files in "share/":
      textformat -> textformat.en
      textformat.en
      textformat.de

  Contents of "textformat.en":
    # this is a comment
    Hello Boy
    At Stans woodhouse

  Contents of "textformat.de":
    Hallo alter Knabe
    Bei Stans Holzkaschemme

  Your call to give out the language specific string of "Hello Boy":
    const char * ptr;
    ptr=vg_get_textformat("Hello Boy");
    vg_draw_text(NULL,RGB_WHITE,0,0,ptr,NULL,RGB_FULL).
  which will give out "Hello Boy" or "Hallo alter Knabe".

  Adding or removing languages or missing files
  It is no problem to add or remove languages, simply create a new
  "textformat.??" file or remove one.
  If it ever happened that a selected language does not (more) exist,
  the original text from the game is used.
  Therefore it is also no problem to use vg_get_textformat() even if no
  files "textformat.??" and "textformat" are present. Then always the
  original text from the game is used.

  More than text
  The strings in the "textformat.??" files can be more than just simple text,
  they also can be formats for a sprintf.
  E.g. a string could be:  "Give me %s".
  You use it as follows:
    const char * ptr;
    char buf[128];
    ptr=vg_get_textformat("Give me %s");
    snprintf(buf,sizeof(buf),ptr,vg_get_textformat("the paper"));
    vg_draw_text(NULL,RGB_WHITE,0,0,ptr,NULL,RGB_FULL).
  which gives out in
   - english:  "Give me the paper"
   - german:   "Gib mir das Papier"
  if you have in your
   - textformat.en:  "the paper"
                     "Give me %s"
   - textformat.de:  "das Papier"
                     "Gib mir %s"

  How to select a language
  You can select languages in the VgaGames-system-menu (press ESCAPE-key),
  which can also be called with vg_menu_language().

  The selected language will be saved in the VgaGames-properties file
  ".vgag2.rc".
  As long as in ".vgag2.rc" no language is saved, the original language of
  the game is used.
  If this is not desiderated, you can set the default language
  when calling vg_init_vgagames().


RETURN VALUE
============
  A pointer to the translated text (static value, don't free it)
  or to the passed text itself is returned.


SEE ALSO
========
  Index
  vg_font_width()
  vg_font_height()