* Initial work on internationalization of the program code. po/ikiwiki.pot

  is available for translation.
* Export gettext() from IkiWiki module.

5 files changed, 47 insertions, 45 deletions

diff --git a/doc/bugs/hardcoded___34__Discussion__34___link.mdwn b/doc/bugs/hardcoded___34__Discussion__34___link.mdwn
index fc8406d87..4436f7101 100644
--- a/doc/bugs/hardcoded___34__Discussion__34___link.mdwn
+++ b/doc/bugs/hardcoded___34__Discussion__34___link.mdwn
@@ -38,5 +38,7 @@ or "History".
 >> In my wiki I use only Polish name of pages, so I would like to have
 >> dyskusja.html page, instead of discussion.html page. --Pawel
 
->>> I have an incomplete i10n patch for such hardcoded strings in the code, 
->>> which I hope to finish up eventually --[[Joey]]
+>>> Ikiwiki is now fully internationalised, so you can change the name of
+>>> the Discussion page and quite a lot more (but hardly everything) by
+>>> translating it. [[bugs/done]]! There's a `po/debconf.pot` in the source
+>>> now for translating. See [[translation]]. --[[Joey]]
diff --git a/doc/install.mdwn b/doc/install.mdwn
index 04600b17f..d9c2a79f7 100644
--- a/doc/install.mdwn
+++ b/doc/install.mdwn
@@ -11,7 +11,7 @@ installed, and also uses the following perl modules if available:
 [[cpan CGI::Session]], [[cpan CGI::FormBuilder]] (version 3.02.02 or newer),
 [[cpan Mail::Sendmail]], [[cpan Time::Duration]], [[cpan TimeDate]],
 [[cpan HTML::Scrubber]], [[cpan RPC::XML]], [[cpan XML::Simple]],
-[[cpan XML::Feed]], [[cpan File::MimeInfo]].
+[[cpan XML::Feed]], [[cpan File::MimeInfo]], [[cpan Locale::gettext]].
 
 The [[tla]] support also needs the [[cpan MailTools]] perl module.
 
diff --git a/doc/patchqueue/l10n.mdwn b/doc/patchqueue/l10n.mdwn
index 85e4f21e2..3369bec11 100644
--- a/doc/patchqueue/l10n.mdwn
+++ b/doc/patchqueue/l10n.mdwn
@@ -22,13 +22,6 @@ I've revised the patches (tested OK):
 
 However...
 
-> There are two places in IkiWiki, subject to localization: HTML::Template
-
-Unfortunately this is not correct.  There a few (?) exceptional places, for
-example button texts in CGI.pm:
-
-    my @buttons=("Save Page", "Preview", "Cancel");
-
 > fine.  Also a final note, I haven't examined the quality of generated
 > templates yet.
 
@@ -55,43 +48,14 @@ Birisi[1], ki muhtemelen bu sizsiniz, <TMPL_VAR WIKINAME>[2] üzerindeki
 bulundu. Parola: <TMPL_VAR USER_PASSWORD> -- ikiwiki [1] Parolayı isteyen
 kullanıcının ait IP adresi: <TMPL_VAR REMOTE_ADDR>[2] <TMPL_VAR WIKIURL>
 
-----
-
-> Unfortunately this is not correct.  There a few (?) exceptional places, for
-> example button texts in CGI.pm:
->
->     my @buttons=("Save Page", "Preview", "Cancel");
-
-Hmm, I've thought on this issue.  Using Locale::gettext seems to be the
-natural solution.  But this would need to create another po file and also,
-ikiwiki would depend another Perl module.  Kinda overkill...
-
-I have another idea...  What about to create another (flat) template file
-for this sort of strings?  Something like strings.tmpl with the content:
-
-    Save Page, Preview, Cancel
-
-or we could categorize these strings in some variables (',' is the
-delimiter for this code snippet):
-
-    <TMPL_IF NAME="BUTTONS">
-    Save Page, Preview, Cancel
-    </TMPL_IF>
-
-and then (preferably in a separate wrapper function in CGI.pm):
-
-     my $template=template("strings.tmpl");
-     $template->param("BUTTONS", 1);
-     my @buttons=split(/\s*,\s*/, $template->output);
-
-You get the idea...  I've tried this method.  All in one po file, kind of
-ugly, but it _really_ works.
-
-> > fine.  Also a final note, I haven't examined the quality of generated
-> > templates yet.
->
 > Looks like, tmpl_process3 cannot preserve line breaks in template files.
 > For example, it processed the following template:
 
 This could be easily worked around in tmpl_process3, but I wouldn't like to
 maintain a separate utility.
+
+----
+
+As to the hardcoded strings in ikiwiki, I've internationalized the program,
+and there is a po/ikiwiki.pot in the source that can be translated.
+--[[Joey]]
diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index f808d2e1e..6c475024a 100644
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -382,6 +382,10 @@ path to the first file found.
 
 Given a time, formats it for display.
 
+#### `gettext`
+
+This is the standard gettext function, although slightly optimised.
+
 ## RCS plugins
 
 ikiwiki's support for revision control systems also uses pluggable perl
diff --git a/doc/translation.mdwn b/doc/translation.mdwn
new file mode 100644
index 000000000..4f7bf347f
--- /dev/null
+++ b/doc/translation.mdwn
@@ -0,0 +1,32 @@
+If you want to translate your wiki into another language, there are
+essentailly three peices needed for a complete translation:
+
+1. The messages in the ikiwiki program itself need to be translated.
+   Ikiwiki is internationalised, and most such messages are already marked
+   with `gettext()`. The source has a `po/ikiwiki.pot` that can be copied
+   and translated as a po file. All very standard.
+
+   Note that a few things in the source are not currently translated. These
+   include:
+
+   * Error messages of the "should never happen" variety.
+   * Certian info in commit messages, which is not visible from inside the
+     wiki, but is visible in the commit logs. This needs to stay in English
+     so that ikiwiki can parse it back out of the logs.
+   * Some parts of FormBuilder forms, which should be translatable by
+     adding templates. Note that these forms don't need templates for the
+     English version.
+   * The name of the `index` page, which has a special meaning to browsers
+     anyway.
+   * The names of some other pages, like `sidebar` and `openid`.
+   * The names and values of parameters, both to the program, in the setup
+     file, and in preprocessor directives.
+
+1. The templates also need to be translated. Some work has been done on an
+   infrastructure for maintaining translated templates, as documented in
+   [[patchqueue/l10n]], but until that's complete, you'd need to copy and
+   translate the templates by hand.
+
+1. The basewiki itself needs to be translated. Whether to only translate
+   the page contents, or also translate the page names, is an open
+   question.