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

[ikiwiki.git] / doc / translation.mdwn

diff --git a/doc/translation.mdwn b/doc/translation.mdwn
new file mode 100644 (file)
index 0000000..4f7bf34
--- /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.