Getting the i18n/l10n machinery to work
---------------------------------------

The string extractor is a Python script
tools/extract-translation.py
It has hardwired the files to scan.

There are two ways to tell the string extractor how to treat the string:

----------------------

1)

Extractor mark syntax: //t??? at the end of line, each "?" stands for one
string literal on the same line, if there are fewer than strings, last is
repeated as many times as neccessary. Flags:
+  include
-  exclude
f  include as format

Example usage:

MyProc(Format(_('My string is: %s'), [S]), 'hehe', Translate('error')); //tf-+
                 ^ format                   ^ excluded        ^ included

Writeln(Translate('blah'), 'lorem ipsum', 'dolor sit amet', '?'); //t+-
                   ^ first included
                            ^ second excluded, all other inherit status


----------------------

2)

Another thing are directives. These are in form {t default ?} and set the
default action to do when strings without any marking are encountered.
Typically you want to set this to "-" so as not to bother with marking all the
strings that should not appear in translations, but some blocks may be easier to
mark before and after with directives rather than marking each string with one
extra mark.

Example usage:

{t default +}
a:= Translate('blah blah');
b:= Translate('hahaha');
c:= Translate('this is a lot of translatable strings');
d:= Translate('so you better think about');
e:= Translate('sth better than //t+//t+//t+');
{t default -}


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

Translate() versus _()
----------------------

The external unit responsible for translating strings mimicks to some (small)
extent GETTEXT interface, but was born in labor and long-term confusion. Thus
the original function is called Translate, but since gettext uses _, it was
added as well. Current status quo is that where is directly written string
literal, _ is used since it's clear it should be translated. Where the
situation is less obvious, use Translate which "spells out" the action. Such
places are eg. when the string is chosen from more options depending on
directives, or when it is passed from IfThen, or when it is one of the
fossilized constants from ConstStrU ... and so on.

Example usage:

Label.Caption:= _('This is a translated label...');

Grid[_('Machine processor has MMX')]:=
  Translate(IfThen(HasMMX, sscYes, sscNo));

Grid[_('Debug output')]:= Translate(
  {$IFDEF DEBUG_OUTPUT} 'enabled' {$ELSE} 'disabled' {$ENDIF});

