This directory contains the .po files (and build rules) for the localization
data used by Page Speed.  .po files contain translations of the UI strings used
in Page Speed, with one .po file per locale.  For instance, a "ko_KR.po" file
would contain translations of all the enlish strings into the dialect of Korean
(the "ko" part) used in South Korea (the "KR" part).

.po files are generated by the GNU gettext toolchain, and filled in by
translators.  Due to licensing and build issues, we don't want to link directly
against the GNU gettext implementation that reads the .po files.  Instead, we
roll our own implementation that compiles .po files into C source files to be
compiled and linked with our binaries.

There is also a single "pagespeed.pot" file, which is taken to be the canonical
list of english strings in the project.

poc
===
The poc tool takes as input a .po file, and generates a .po.cc file with a table
of the strings in their translated form.  In addition, it generates a
master.po.cc file that contains all the original (english) strings.  For
example, it might generate the following files for a french fr.po input,

###### master.po.cc ######
...
const char* master_string_table[] = {
  'UI string 1',
  'UI string 2',
  ...
  NULL
};

pagespeed::l10n::RegisterLocale locale(NULL, master_string_table);

###### fr.po.cc ######
...
const char* fr_string_table[] = {
  'UI string 1 in french',
  'UI string 2 in french',
  ...
  NULL
};

pagespeed::l10n::RegisterLocale locale("fr_FR", fr_string_table);

######################

In each file, there is a NULL-terminated table of strings in the corresponding
language, and a static RegisterLocale object.


RegisterLocale
==============
The pagespeed::l10n::RegisterLocale class allows locales to register themselves
dynamically at process startup.  That way, the set of locales included in a
binary can be determined at link time (or even load time if you use a shared
library), rather than having to hard-code it into the source.

RegisterLocale works by maintaining a static map from locale to string table,
populated in the RegisterLocale constructor.  Every time a RegisterLocale object
is constructed (one for each locale), the locale/string table pair is added to
the map.  This happens at process startup, before main().


Build Rules
===========
The pagespeed_gen_po target is responsible for invoking poc and generating
.po.cc files from .po files.  Its sources are a list of .po files used in the
project --- for each source file, it invokes poc.

The pagespeed_all_po and pagespeed_test_po are targets used to actually include
locales in a binary or library.  Instead of being '<(library)' targets with the
'*.po.cc' files listed as sources, we used a 'none' target.  If it were built as
a library, then the locale object files would be stripped by the linker (since
none of their symbols are referenced elsewhere).

Instead, they export a "sources" list to their dependents.  That is, if a target
(e.g. pagespeed_test) depends on pagespeed_test_po, then all of the sources
listed in pagespeed_test_po ("backwards.po.cc", "empty.po.cc" and
"master.po.cc") will be added to the sources list of pagespeed_test and compiled
in with it.
