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 Server support
  97 ==============
  98
  99 Apache
 100 ------
 101
 102 Using `mod_negotiation` makes it really easy to have Apache serve the
 103 page in the client's preferred language, if available. This is the
 104 default Debian Apache configuration.
 105
 106 When `usedirs` is enabled, one has to set `DirectoryIndex index` for
 107 the wiki context.
 108
 109 Setting `DefaultLanguage LL` (replace `LL` with your default MIME
 110 language) for the wiki context can be needed, to ensure
 111 `bla/page/index.en.html` is served as `Content-Language: LL`.
 112 **FIXME**: is it still needed with the new `.en.html` naming convention?
 113
 114 lighttpd
 115 --------
 116
 117 lighttpd unfortunately does not support content negotiation.
 118
 119 **FIXME**: does `mod_magnet` provide the functionality needed to
 120  emulate this?
 121
 122
 123 Usage
 124 =====
 125
 126 Templates
 127 ---------
 128
 129 ### Display page's versions in other languages
 130
 131 The `OTHERLANGUAGES` loop provides ways to display other languages'
 132 versions of the same page, and the translations' status.
 133
 134 One typically adds the following code to `templates/page.tmpl`:
 135
 136         <TMPL_IF NAME="OTHERLANGUAGES">
 137         <div id="otherlanguages">
 138           <ul>
 139           <TMPL_LOOP NAME="OTHERLANGUAGES">
 140             <li>
 141               <a href="<TMPL_VAR NAME="URL">"><TMPL_VAR NAME="LANGUAGE"></a>
 142               <TMPL_UNLESS NAME="MASTER">
 143                 (<TMPL_VAR NAME="PERCENT">&nbsp;%)
 144               </TMPL_UNLESS>
 145             </li>
 146           </TMPL_LOOP>
 147           </ul>
 148         </div>
 149         </TMPL_IF>
 150
 151 The following variables are available inside the loop (for every page in):
 152
 153 - `URL` - url to the page
 154 - `CODE` - two-letters language code
 155 - `LANGUAGE` - language name (as defined in `po_slave_languages`)
 156 - `MASTER` - is true (1) if, and only if the page is a "master" page
 157 - `PERCENT` - for "slave" pages, is set to the translation completeness, in percents
 158
 159 ### Display the current translation status
 160
 161 The `PERCENTTRANSLATED` variable is set to the translation
 162 completeness, expressed in percent, on "slave" pages.
 163
 164 Additional PageSpec tests
 165 -------------------------
 166
 167 This plugin enhances the regular [[ikiwiki/PageSpec]] syntax with some
 168 additional tests that are documented [[here|ikiwiki/pagespec/po]].
 169
 170
 171 TODO
 172 ====
 173
 174 OTHERLANGUAGES dependencies
 175 ---------------------------
 176
 177 Pages using `OTHERLANGUAGES` must depend on any "master" and "slave"
 178 pages whose status is being displayed. It will trigger dependency
 179 loops; how to sort this out?
 180
 181 Should pages using the `OTHERLANGUAGES` template loop be declared as
 182 linking to the same page in other versions? To be rigorous, they
 183 should, but this may clutter the backlinks.
 184
 185 Automatic PO files update
 186 -------------------------
 187
 188 Committing changes to a "master" page:
 189
 190 1. updates the POT file and the PO files for the supported languages;
 191    this is done in the `needsbuild` hook; **FIXME**: the updated PO
 192    files must then be put under version control
 193
 194 2. triggers a refresh of the corresponding HTML slave pages: this is
 195    achieved by making any "slave" page dependent on the corresponding
 196    "master" page, in the `needsbuild` hook.
 197
 198 **FIXME** Also, when the plugin has just been enabled, or when a page
 199 has just been declared as being translatable:
 200
 201 - all the needed POT and PO files have to be created
 202 - the PO files must be checked into version control
 203
 204 **FIXME** `refreshpofiles` uses `system()`, whose args have to be
 205 checked more thoroughly to prevent any security issue (command
 206 injection, etc.).
 207
 208 UI consistency: rename "Edit" button on slave pages
 209 ---------------------------------------------------
 210
 211 It may be surprising to some, after having pressed *Edit* on a wiki
 212 page, to end up editing a strange looking PO file. The *Edit* button
 213 displayed on "slave" pages must therefore be renamed *Improve
 214 translation* .
 215
 216 Translation quality assurance
 217 -----------------------------
 218
 219 Modifying a PO file via the CGI must only be allowed if the new
 220 version is a valid PO file. As a bonus, check that it provides a more
 221 complete translation than the existing one.
 222
 223 A new `cansave` type of hook would be needed to implement this.
 224
 225 Note: committing to the underlying repository is a way to bypass
 226 this check.
 227
 228 Translating online
 229 ------------------
 230
 231 As PO is a wiki page type, we already have an online PO editor, that
 232 is ikiwiki's CGI.
 233
 234 A message-by-message interface could also be implemented at some
 235 point; a nice way to do offline translation work (without VCS access)
 236 still has to be offered, though.
 237
 238 Translating offline without VCS access
 239 --------------------------------------
 240
 241 The following workflow should be made possible for translators without
 242 VCS access who need to edit the PO files in another editor than a web
 243 browser:
 244
 245 - download the page's PO file
 246 - use any PO editor to update the translation
 247 - upload the updated PO file
 248
 249 Implementation note: a generic mechanism to upload a page's source is
 250 needed: it's only an alternative way to allow saving a the modified
 251 page's source with the CGI.
 252
 253 ### Short-term workflow
 254
 255 A possible workaround is:
 256
 257 - pretend to edit the PO file online
 258 - copy the PO file content from the textarea
 259 - cancel the edit
 260 - paste the content into a local file.
 261 - edit the local file in any PO editor
 262 - pretend to edit the PO file online
 263 - paste the modified local file's content into the edit textarea
 264 - save