Translation Readme
==================

Files:

  *.cvs.po (for example de.cvs.po) 
      - contains translated strings 
      - is stored in cvs

  *.cvs.new.po (for example de.cvs.new.po) 
      - is created on build
      - contains all strings from *.cvs.po and all .pot files of this firmware
      - if a firmware contains new strings or you translated some strings 
        then rename this file to *.cvs.po and checkin

  All other files are created during build and must not be checked in.


The creation of the .po files is done for each package when it is compiled.
To make xgettext find the strings to translate, they have to be marked in
the source.

Firmware files (*.c)
********************

To make use of the translation makros and functions, you have to include
the header file of libpp_intl:
    #include <pp/intl.h>

All strings which have to be translated at the moment they appear should be
marked with _(string), e.g.
    printf("Hello World\n");
becomes
    printf(_("Hello World\n"));

Some strings should also be translated, but not when they are defined, but
later when they are used. This is especially needed for string constants.
Such strings should should be marked with N_(string). This makes xgettext
find the strings, but they are not translated by gettext. This has to be
done later when the strings are used, e.g.
    const char* hello = "Hello";
    const char* world = "World";
    printf("%s %s\n", hello, world);
becomes
    const char* hello = N_("Hello");
    const char* world = N_("World");
    printf("%s %s\n", pp_intl_translate(hello), pp_intl_translate(world));

All other strings (which are not marked) are not found by xgettext and not
translated.

Applet (*.java)
***************

All strings must be marked with T._(string) - these strings will be
translated immediately - or with T.N_(string) - these strings are found by
xgettext, but not translated immediately. To translate the strings later,
a call to T._() is needed. T is a Java class which internally handles the
translation.

Use Java format strings whenever concatenation is needed instead of a
simple "+". This allows the translator to change the style of the
sentence. Example:

Original string:
    "RFB: connected successfully to " + hp;
This might be translated via
    T._("RFB: connected successfully to" + " " + hp);
But this does not allow a good german sentence. Better would be:
    MessageFormat.format(T._("RFB: connected successfully to {0}"),
	                 new Object[] { hp });
This allows the sentence to be translated into
    "RFB: Erfolgreich zu {0} verbunden"

Webpages (*.asp.in)
*******************

For the webpages, three translation asp functions are definde. To
translate a string immediately and write the string directly to the
website, call _(string), e.g.
    <% _("Hello World"); %>
To translate a string immediately that is not written directly to the
website, call the T_(string) asp, e.g.
    <% write(T_("Hello World")); %>
If you want to mark a string for xgettext that should not be translated
at the moment the string appears, use the asp call N_(string). This
call just returns the original string. To translate it later, use the
_() or T_() call.

In the webpages, it is also necessary to use format strings whenever
string concatenation appears to keep a good translation. Therefore a
asp call named wprintf() is implemented which works similar to the C
function printf(). The only difference is that only "%s" is implemented
because all asp variables are strings. You can write "%d", "%f" or
whatever you want, internally the function does not distinguish between
the formats. To use wprintf with translated strings, do only call the
T_() function! _() will cause problems!

The character set of the currently used language can be queried with
the asp call getCharset() which just returns the name, e.g. ISO-8859-1.
This can be used for the html header of the page. As a shortcut to the
header line with the encoding, the asp function encodingLine() can be
used. This call automatically writes the line
    <meta http-equiv="content-type" content="text/html; charset=...">
to the webpage.

NOTE: Strings between quotation marks are not found by xgettext! That
means, in ' ... value="<% _("bla"); %>" ...' the text "bla" is not
found by xgettext. Therefore, another asp call Q_(string) is defined
which writes the string in quotation marks, you have to call
' ... value=<% Q_("bla"); %> ...'. The call Q_() automatically adds
quotation marks before and after the string. If you want to use more
complicated statements inbetween quotation marks, you might use instead:
value=<% write('"'); _("bla"); write('"'); %>
Additionally the two functions A_(x) and AQ_(x) were added:
 A_("x") expands to <% _("x") %>
AQ_("x") expands to <% Q_("x") %>