doc/plugins/po.mdwn

   1 [[!template id=plugin name=po core=0 author="[[intrigeri]]"]]
   2 [[!tag type/format]]
   3
   4 This plugin adds support for multi-lingual wikis, translated with
   5 gettext, using [po4a](http://po4a.alioth.debian.org/).
   6
   7 It depends on the Perl `Locale::Po4a::Po` library (`apt-get install po4a`).
   8
   9 Introduction
  10 ============
  11
  12 A language is chosen as the "master" one, and any other supported
  13 language is a "slave" one.
  14
  15 A page written in the "master" language is a "master" page, and is
  16 written in any supported format but PO. It does not have to be named
  17 a special way: migration from/to this plugin does not imply heavy
  18 renaming work.
  19
  20 Example: `bla/page.mdwn` is a "master" Markdown page written in
  21 English; if `usedirs` is enabled, it is rendered as
  22 `bla/page/index.en.html`, else as `bla/page.en.html`.
  23
  24 Any translation of a "master" page into a "slave" language is called
  25 a "slave" page; it is written in the gettext PO format. PO is now
  26 a page type supported by ikiwiki.
  27
  28 Example: `bla/page.fr.po` is the PO "message catalog" used to
  29 translate `bla/page.mdwn` into French; if `usedirs` is enabled, it is
  30 rendered as `bla/page/index.fr.html`, else as `bla/page.fr.html`
  31
  32
  33 Configuration
  34 =============
  35
  36 `po_master_language` is used to set the master language in
  37 `ikiwiki.setup`, such as:
  38
  39         po_master_language => { 'code' => 'en', 'name' => 'English' }
  40
  41 `po_slave_languages` is used to set the list of supported "slave"
  42 languages, such as:
  43
  44         po_slave_languages => { 'fr' => 'Français',
  45                                 'es' => 'Castellano',
  46                                 'de' => 'Deutsch',
  47         }
  48
  49 Decide which pages are translatable
  50 -----------------------------------
  51
  52 The `po_translatable_pages` setting configures what pages are
  53 translatable. It is a [[ikiwiki/PageSpec]], so you have lots of
  54 control over what kind of pages are translatable.
  55
  56 The `*.LL.po` translations files are anyway not considered as being
  57 translatable, so you don't need to worry about excluding them manually
  58 from this [[ikiwiki/PageSpec]].
  59
  60 Internal links
  61 --------------
  62
  63 One can use the `po_link_to_` option in `ikiwiki.setup` to choose how
  64 internal links should be generated, depending on web server features
  65 and site-specific preferences.
  66
  67 ### Default linking behavior
  68
  69 If `po_link_to` is unset, or set to `default`, ikiwiki's default
  70 linking behavior is preserved: `\[[page]]` links to the master
  71 language's page.
  72
  73 ### Link to negotiated language
  74
  75 If `po_link_to` is set to `negotiated`, `\[[page]]` links to the
  76 negotiated preferred language, *i.e.* `foo/page/`.
  77
  78 (In)compatibility notes:
  79
  80 - `po_link_to => negotiated` provides no useful behavior if `usedirs`
  81   is disabled; this option combination is neither implemented nor
  82   allowed
  83 - `po_link_to => negotiated` provides no useful behavior if the web
  84   server does not support Content Negotiation
  85
  86 ### Link to current language
  87
  88 If `po_link_to` is set to `current` and the destination page is either
  89 a translatable page or a translation, `\[[page]]` links to the current
  90 page's language, *i.e.*:
  91
  92 - `foo/page/index.LL.html` if `usedirs` is enabled
  93 - `foo/page.LL.html` if `usedirs` is disabled
  94
  95
  96 Templates
  97 ---------
  98
  99 The `OTHERLANGUAGES` loop provides ways to display the existing
 100 translations and/or master page. One typically adds the following code
 101 to `templates/page.tmpl`:
 102
 103         <TMPL_IF NAME="OTHERLANGUAGES">
 104         <div id="otherlanguages">
 105           <ul>
 106           <TMPL_LOOP NAME="OTHERLANGUAGES">
 107             <li>
 108               <a href="<TMPL_VAR NAME="URL">"
 109                  class="is_master_<TMPL_VAR NAME="MASTER">">
 110               <TMPL_VAR NAME="LANGUAGE">
 111             </a>
 112             </li>
 113           </TMPL_LOOP>
 114           </ul>
 115         </div>
 116         </TMPL_IF>
 117
 118
 119 Server support
 120 ==============
 121
 122 Apache
 123 ------
 124
 125 Using `mod_negotiation` makes it really easy to have Apache serve the
 126 page in the client's preferred language, if available. This is the
 127 default Debian Apache configuration.
 128
 129 When `usedirs` is enabled, one has to set `DirectoryIndex index` for
 130 the wiki context.
 131
 132 Setting `DefaultLanguage LL` (replace `LL` with your default MIME
 133 language) for the wiki context can be needed, to ensure
 134 `bla/page/index.en.html` is served as `Content-Language: LL`.
 135 **FIXME**: is it still needed with the new `.en.html` naming convention?
 136
 137 lighttpd
 138 --------
 139
 140 lighttpd unfortunately does not support content negotiation.
 141
 142 **FIXME**: does `mod_magnet` provide the functionality needed to
 143  emulate this?
 144
 145
 146 TODO
 147 ====
 148
 149 Link relationships
 150 ------------------
 151
 152 Should pages using the `OTHERLANGUAGES` template loop be declared as
 153 linking to the same page in other versions?
 154
 155 View translation status
 156 -----------------------
 157
 158 One should be able to view some information about the translation
 159 completeness, either for a given page or for the whole wiki.
 160
 161 This should not be too hard using gettext tools. If this is
 162 implemented as a
 163 [HTML::Template](http://search.cpan.org/search?mode=dist&query=HTML%3A%3ATemplate)
 164 loop, a page using it should depend on any "master" and "slave" pages
 165 whose status is being displayed.
 166
 167 If it's not too heavy to compute, this status data may be made
 168 available in the `OTHERLANGUAGES` template loop; else, a dedicated
 169 loop would be needed.
 170
 171 Automatic PO files update
 172 -------------------------
 173
 174 Committing changes to a "master" page must:
 175
 176 1. update the POT file and the PO files for the supported languages,
 177    before putting them under version control
 178 2. trigger a refresh of the corresponding HTML slave pages
 179
 180 The former is to be done at a time when:
 181
 182 - we know which "master" page was modified, and thus, which POT/PO
 183   files have to be updated: the `needsbuild` hook is the first one to
 184   run that provides us with the necessary information
 185 - we can modify the list of pages needing a refresh; this is
 186   `needsbuild` hook's job
 187
 188 The latter can be implemented by making any "slave" page depend on the
 189 corresponding "master" page. The `add_depends` function can achieve
 190 this, if used in a **FIXME** hook.
 191
 192 UI consistency: rename "Edit" button on slave pages
 193 ---------------------------------------------------
 194
 195 It may be surprising to some, after having pressed *Edit* on a wiki
 196 page, to end up editing a strange looking PO file. The *Edit* button
 197 displayed on "slave" pages must therefore be renamed *Improve
 198 translation* .
 199
 200 Pages selection depending on language
 201 -------------------------------------
 202
 203 To improve user navigation in a multi-lingual wiki, site developers
 204 must be enabled to write:
 205
 206         \[[!map pages="dev/* and lang(LL)" feeds="no"]]
 207
 208         \[[!map pages="dev/* and currentlang()" feeds="no"]]
 209
 210 Translation quality assurance
 211 -----------------------------
 212
 213 Modifying a PO file via the CGI must only be allowed if the new
 214 version is a valid PO file. As a bonus, check that it provides a more
 215 complete translation than the existing one.
 216
 217 A new `cansave` type of hook would be needed to implement this.
 218
 219 Note: committing to the underlying repository is a way to bypass
 220 this check.
 221
 222 Translating online
 223 ------------------
 224
 225 As PO is a wiki page type, we already have an online PO editor, that
 226 is ikiwiki's CGI.
 227
 228 A message-by-message interface could also be implemented at some
 229 point; a nice way to do offline translation work (without VCS access)
 230 still has to be offered, though.
 231
 232 Translating offline without VCS access
 233 --------------------------------------
 234
 235 The following workflow should be made possible for translators without
 236 VCS access who need to edit the PO files in another editor than a web
 237 browser:
 238
 239 - download the page's PO file
 240 - use any PO editor to update the translation
 241 - upload the updated PO file
 242
 243 Implementation note: a generic mechanism to upload a page's source is
 244 needed: it's only an alternative way to allow saving a the modified
 245 page's source with the CGI.
 246
 247 ### Short-term workflow
 248
 249 A possible workaround is:
 250
 251 - pretend to edit the PO file online
 252 - copy the PO file content from the textarea
 253 - cancel the edit
 254 - paste the content into a local file.
 255 - edit the local file in any PO editor
 256 - pretend to edit the PO file online
 257 - paste the modified local file's content into the edit textarea
 258 - save