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 [[!toc levels=2]]
  10
  11 Introduction
  12 ============
  13
  14 A language is chosen as the "master" one, and any other supported
  15 language is a "slave" one.
  16
  17 A page written in the "master" language is a "master" page. It can be
  18 of any page type supported by ikiwiki, except `po`. It does not have to be
  19 named a special way: migration to this plugin does not imply any page
  20 renaming work.
  21
  22 Example: `bla/page.mdwn` is a "master" Markdown page written in
  23 English; if `usedirs` is enabled, it is rendered as
  24 `bla/page/index.en.html`, else as `bla/page.en.html`.
  25
  26 Any translation of a "master" page into a "slave" language is called
  27 a "slave" page; it is written in the gettext PO format. `po` is now
  28 a page type supported by ikiwiki.
  29
  30 Example: `bla/page.fr.po` is the PO "message catalog" used to
  31 translate `bla/page.mdwn` into French; if `usedirs` is enabled, it is
  32 rendered as `bla/page/index.fr.html`, else as `bla/page.fr.html`
  33
  34 (In)Compatibility
  35 =================
  36
  37 This plugin does not support the `indexpages` mode. If you don't know
  38 what it is, you probably don't care.
  39
  40
  41 Configuration
  42 =============
  43
  44 Supported languages
  45 -------------------
  46
  47 `po_master_language` is used to set the "master" language in
  48 `ikiwiki.setup`, such as:
  49
  50         po_master_language => { 'code' => 'en', 'name' => 'English' }
  51
  52 `po_slave_languages` is used to set the list of supported "slave"
  53 languages, such as:
  54
  55         po_slave_languages => { 'fr' => 'Français',
  56                                 'es' => 'Castellano',
  57                                 'de' => 'Deutsch',
  58         }
  59
  60 Decide which pages are translatable
  61 -----------------------------------
  62
  63 The `po_translatable_pages` setting configures what pages are
  64 translatable. It is a [[ikiwiki/PageSpec]], so you have lots of
  65 control over what kind of pages are translatable.
  66
  67 The `.po` files are not considered as being translatable, so you don't need to
  68 worry about excluding them explicitly from this [[ikiwiki/PageSpec]].
  69
  70 Internal links
  71 --------------
  72
  73 The `po_link_to` option in `ikiwiki.setup` is used to decide how
  74 internal links should be generated, depending on web server features
  75 and site-specific preferences.
  76
  77 ### Default linking behavior
  78
  79 If `po_link_to` is unset, or set to `default`, ikiwiki's default
  80 linking behavior is preserved: `\[[destpage]]` links to the master
  81 language's page.
  82
  83 ### Link to current language
  84
  85 If `po_link_to` is set to `current`, `\[[destpage]]` links to the
  86 `destpage`'s version written in the current page's language, if
  87 available, *i.e.*:
  88
  89 - `foo/destpage/index.LL.html` if `usedirs` is enabled
  90 - `foo/destpage.LL.html` if `usedirs` is disabled
  91
  92 ### Link to negotiated language
  93
  94 If `po_link_to` is set to `negotiated`, `\[[page]]` links to the
  95 negotiated preferred language, *i.e.* `foo/page/`.
  96
  97 (In)compatibility notes:
  98
  99 - if `usedirs` is disabled, it does not make sense to set `po_link_to`
 100   to `negotiated`; this option combination is neither implemented
 101   nor allowed.
 102 - if the web server does not support Content Negotiation, setting
 103   `po_link_to` to `negotiated` will produce a unusable website.
 104
 105
 106 Server support
 107 ==============
 108
 109 Apache
 110 ------
 111
 112 Using Apache `mod_negotiation` makes it really easy to have Apache
 113 serve any page in the client's preferred language, if available.
 114 This is the default Debian Apache configuration.
 115
 116 When `usedirs` is enabled, one has to set `DirectoryIndex index` for
 117 the wiki context.
 118
 119 Setting `DefaultLanguage LL` (replace `LL` with your default MIME
 120 language code) for the wiki context can help to ensure
 121 `bla/page/index.en.html` is served as `Content-Language: LL`.
 122
 123 lighttpd
 124 --------
 125
 126 lighttpd unfortunately does not support content negotiation.
 127
 128 **FIXME**: does `mod_magnet` provide the functionality needed to
 129  emulate this?
 130
 131
 132 Usage
 133 =====
 134
 135 Templates
 136 ---------
 137
 138 When `po_link_to` is not set to `negotiated`, one should replace some
 139 occurrences of `BASEURL` with `HOMEPAGEURL` to get correct links to
 140 the wiki homepage.
 141
 142 The `ISTRANSLATION` and `ISTRANSLATABLE` variables can be used to
 143 display things only on translatable or translation pages.
 144
 145 ### Display page's versions in other languages
 146
 147 The `OTHERLANGUAGES` loop provides ways to display other languages'
 148 versions of the same page, and the translations' status.
 149
 150 One typically adds the following code to `templates/page.tmpl`:
 151
 152         <TMPL_IF NAME="OTHERLANGUAGES">
 153         <div id="otherlanguages">
 154           <ul>
 155           <TMPL_LOOP NAME="OTHERLANGUAGES">
 156             <li>
 157               <a href="<TMPL_VAR NAME="URL">"><TMPL_VAR NAME="LANGUAGE"></a>
 158               <TMPL_UNLESS NAME="MASTER">
 159                 (<TMPL_VAR NAME="PERCENT">&nbsp;%)
 160               </TMPL_UNLESS>
 161             </li>
 162           </TMPL_LOOP>
 163           </ul>
 164         </div>
 165         </TMPL_IF>
 166
 167 The following variables are available inside the loop (for every page in):
 168
 169 - `URL` - url to the page
 170 - `CODE` - two-letters language code
 171 - `LANGUAGE` - language name (as defined in `po_slave_languages`)
 172 - `MASTER` - is true (1) if, and only if the page is a "master" page
 173 - `PERCENT` - for "slave" pages, is set to the translation completeness, in percents
 174
 175 ### Display the current translation status
 176
 177 The `PERCENTTRANSLATED` variable is set to the translation
 178 completeness, expressed in percent, on "slave" pages.
 179
 180 One can use it this way:
 181
 182         <TMPL_IF NAME="ISTRANSLATION">
 183         <div id="percenttranslated">
 184           <TMPL_VAR NAME="PERCENTTRANSLATED">
 185         </div>
 186         </TMPL_IF>
 187
 188 Additional PageSpec tests
 189 -------------------------
 190
 191 This plugin enhances the regular [[ikiwiki/PageSpec]] syntax with some
 192 additional tests that are documented [[here|ikiwiki/pagespec/po]].
 193
 194 Automatic PO file update
 195 ------------------------
 196
 197 Committing changes to a "master" page:
 198
 199 1. updates the POT file and the PO files for the "slave" languages;
 200    the updated PO files are then put under version control;
 201 2. triggers a refresh of the corresponding HTML slave pages.
 202
 203 Also, when the plugin has just been enabled, or when a page has just
 204 been declared as being translatable, the needed POT and PO files are
 205 created, and the PO files are checked into version control.
 206
 207 Discussion pages and other sub-pages
 208 ------------------------------------
 209
 210 Discussion should happen in the language in which the pages are
 211 written for real, *i.e.* the "master" one. If discussion pages are
 212 enabled, "slave" pages therefore link to the "master" page's
 213 discussion page.
 214
 215 Likewise, "slave" pages are not supposed to have sub-pages;
 216 [[WikiLinks|wikilink]] that appear on a "slave" page therefore link to
 217 the master page's sub-pages.
 218
 219 Translating
 220 -----------
 221
 222 One can edit the PO files using ikiwiki's CGI (a message-by-message
 223 interface could also be implemented at some point).
 224
 225 If [[tips/untrusted_git_push]] is setup, one can edit the PO files in one's
 226 preferred `$EDITOR`, without needing to be online.
 227
 228 Markup languages support
 229 ------------------------
 230
 231 Markdown is well supported. Some other markup languages supported by
 232 ikiwiki mostly work, but some pieces of syntax are not rendered
 233 correctly on the slave pages:
 234
 235 * [[reStructuredText|rst]]: anonymous hyperlinks and internal
 236   cross-references
 237 * [[wikitext]]: conversion of newlines to paragraphs
 238 * [[creole]]: verbatim text is wrapped, tables are broken
 239 * [[html]] and LaTeX: not supported yet; the dedicated po4a modules
 240   could be used to support them, but they would need a security audit
 241 * other markup languages have not been tested.
 242
 243
 244 TODO
 245 ====
 246
 247 Security checks
 248 ---------------
 249
 250 ### Security history
 251
 252 The only past security issues I could find in GNU gettext and po4a
 253 are:
 254
 255 - [CVE-2004-0966](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2004-0966),
 256   *i.e.* [Debian bug #278283](http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=278283):
 257   the autopoint and gettextize scripts in the GNU gettext package
 258   1.14 and later versions, as used in Trustix Secure Linux 1.5
 259   through 2.1 and other operating systems, allows local users to
 260   overwrite files via a symlink attack on temporary files.
 261 - [CVE-2007-4462](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2007-4462):
 262   `lib/Locale/Po4a/Po.pm` in po4a before 0.32 allows local users to
 263   overwrite arbitrary files via a symlink attack on the
 264   gettextization.failed.po temporary file.
 265
 266 **FIXME**: check whether this plugin would have been a possible attack
 267 vector to exploit these vulnerabilities.
 268
 269 Depending on my mood, the lack of found security issues can either
 270 indicate that there are none, or reveal that no-one ever bothered to
 271 find (and publish) them.
 272
 273 ### PO file features
 274
 275 Can any sort of directives be put in po files that will cause mischief
 276 (ie, include other files, run commands, crash gettext, whatever)?
 277
 278 > No [documented](http://www.gnu.org/software/gettext/manual/gettext.html#PO-Files)
 279 > directive is supposed to do so. [[--intrigeri]]
 280
 281 ### Running po4a on untrusted content
 282
 283 Are there any security issues on running po4a on untrusted content?
 284
 285 To say the least, this issue is not well covered, at least publicly:
 286
 287 - the documentation does not talk about it;
 288 - grep'ing the source code for `security` or `trust` gives no answer.
 289
 290 On the other hand, a po4a developer answered my questions in
 291 a convincing manner, stating that processing untrusted content was not
 292 an initial goal, and analysing in detail the possible issues.
 293
 294 #### Already checked
 295
 296 - the core (`Po.pm`, `Transtractor.pm`) should be safe
 297 - po4a source code was fully checked for other potential symlink
 298   attacks, after discovery of one such issue
 299 - the only external program run by the core is `diff`, in `Po.pm` (in
 300   parts of its code we don't use)
 301 - `Locale::gettext`: only used to display translated error messages
 302 - Nicolas François "hopes" `DynaLoader` is safe, and has "no reason to
 303   think that `Encode` is not safe"
 304 - Nicolas François has "no reason to think that `Encode::Guess` is not
 305   safe". The po plugin nevertheless avoids using it by defining the
 306   input charset (`file_in_charset`) before asking `Transtractor` to
 307   read any file. NB: this hack depends on po4a internals to stay
 308   the same.
 309
 310 ##### Locale::Po4a modules
 311
 312 The modules we want to use have to be checked, as not all are safe
 313 (e.g. the LaTeX module's behaviour is changed by commands included in
 314 the content); they may use regexps generated from the content.
 315
 316 `Chooser.pm` only loads the plugin we tell it too: currently, this
 317 means the `Text` module only.
 318
 319 `Text` module (I checked the CVS version):
 320
 321 - it does not run any external program
 322 - only `do_paragraph()` builds regexp's that expand untrusted
 323   variables; they seem safe to me, but someone more expert than me
 324   will need to check. Joey?
 325
 326   > Freaky code, but seems ok due to use of `quotementa`.
 327
 328 #### To be checked
 329
 330 ##### Text::WrapI18N
 331
 332 `Text::WrapI18N` can cause DoS (see the
 333 [Debian bug #470250](http://bugs.debian.org/470250)), but it is
 334 optional and we do not need the features it provides.
 335
 336 > If a recent enough po4a is installed, this module's use is fully disabled.
 337 > This feature has been merged in po4a CVS on 2009-01-15. --[[intrigeri]]
 338
 339 ##### Term::ReadKey
 340
 341 `Term::ReadKey` is not a hard dependency in our case, *i.e.* po4a
 342 works nicely without it. But the po4a Debian package recommends
 343 `libterm-readkey-perl`, so it will probably be installed on most
 344 systems using the po plugin.
 345
 346 `Term::ReadKey` has too far reaching implications for us to
 347 be able to guarantee anything wrt. security.
 348
 349 > The option that disables `Text::WrapI18N` also disables
 350 > `Term::ReadKey` as a consequence. [[--intrigeri]]
 351
 352 ### msgmerge
 353
 354 `refreshpofiles()` runs this external program.
 355
 356 A po4a developer answered he does "not expect any security issues from
 357 it". I did not manage to crash it with `zzuf`, nor was able to find
 358 any past security holes.
 359
 360 ### msgfmt
 361
 362 `isvalidpo()` runs this external program.
 363
 364 * I could not manage to make it behave badly using zzuf, it exits
 365   cleanly when too many errors are detected.
 366 * I could not find any past security holes.
 367
 368 ### Fuzzing input
 369
 370 Test conditions:
 371
 372 - a 21M file containing 100 concatenated copies of all the files in my
 373   `/usr/share/common-licenses/`; I had no existing PO file or
 374   translated versions at hand, which renders these tests
 375   quite incomplete.
 376 - po4a was the Debian 0.34-2 package; the same tests were also run
 377   after replacing the `Text` module with the CVS one (the core was not
 378   changed in CVS since 0.34-2 was released), without any significant
 379   difference in the results.
 380 - Perl 5.10.0-16
 381
 382 #### po4a-gettextize
 383
 384 `po4a-gettextize` uses more or less the same po4a features as our
 385 `refreshpot` function.
 386
 387 Without specifying an input charset, zzuf'ed `po4a-gettextize` quickly
 388 errors out, complaining it was not able to detect the input charset;
 389 it leaves no incomplete file on disk.
 390
 391 So I had to pretend the input was in UTF-8, as does the po plugin.
 392
 393 Two ways of crashing were revealed by this command-line:
 394
 395         zzuf -vc -s 0:100 -r 0.1:0.5 \
 396           po4a-gettextize -f text -o markdown -M utf-8 -L utf-8 \
 397             -m LICENSES >/dev/null
 398
 399 They are:
 400
 401         Malformed UTF-8 character (UTF-16 surrogate 0xdcc9) in substitution iterator at /usr/share/perl5/Locale/Po4a/Po.pm line 1443.
 402         Malformed UTF-8 character (fatal) at /usr/share/perl5/Locale/Po4a/Po.pm line 1443.
 403
 404 and
 405
 406         Malformed UTF-8 character (UTF-16 surrogate 0xdcec) in substitution (s///) at /usr/share/perl5/Locale/Po4a/Po.pm line 1443.
 407         Malformed UTF-8 character (fatal) at /usr/share/perl5/Locale/Po4a/Po.pm line 1443.
 408
 409 Perl seems to exit cleanly, and an incomplete PO file is written on
 410 disk. I not sure whether if this is a bug in Perl or in `Po.pm`.
 411
 412 > It's fairly standard perl behavior when fed malformed utf-8. As long as it doesn't
 413 > crash ikiwiki, it's probably acceptable. Ikiwiki can do some similar things itself when fed malformed utf-8 (doesn't crash tho) --[[Joey]]
 414
 415 #### po4a-translate
 416
 417 `po4a-translate` uses more or less the same po4a features as our
 418 `filter` function.
 419
 420 Without specifying an input charset, same behaviour as
 421 `po4a-gettextize`, so let's specify UTF-8 as input charset as of now.
 422
 423         zzuf -cv \
 424           po4a-translate -d -f text -o markdown -M utf-8 -L utf-8 \
 425             -k 0 -m LICENSES -p LICENSES.fr.po -l test.fr
 426
 427 ... prints tons of occurences of the following error, but a complete
 428 translated document is written (obviously with some weird chars
 429 inside):
 430
 431         Use of uninitialized value in string ne at /usr/share/perl5/Locale/Po4a/TransTractor.pm line 854.
 432         Use of uninitialized value in string ne at /usr/share/perl5/Locale/Po4a/TransTractor.pm line 840.
 433         Use of uninitialized value in pattern match (m//) at /usr/share/perl5/Locale/Po4a/Po.pm line 1002.
 434
 435 While:
 436
 437         zzuf -cv -s 0:10 -r 0.001:0.3 \
 438           po4a-translate -d -f text -o markdown -M utf-8 -L utf-8 \
 439             -k 0 -m LICENSES -p LICENSES.fr.po -l test.fr
 440
 441 ... seems to lose the fight, at the `readpo(LICENSES.fr.po)` step,
 442 against some kind of infinite loop, deadlock, or any similar beast.
 443
 444 The root of this bug lies in `Text::WrapI18N`, see above for
 445 possible solutions.
 446
 447 gettext/po4a rough corners
 448 --------------------------
 449
 450 - fix infinite loop when synchronizing two ikiwiki (when checkouts
 451   live in different directories): say bla.fr.po has been updated in
 452   repo2; pulling repo2 from repo1 seems to trigger a PO update, that
 453   changes bla.fr.po in repo1; then pushing repo1 to repo2 triggers
 454   a PO update, that changes bla.fr.po in repo2; etc.; quickly fixed in
 455   `629968fc89bced6727981c0a1138072631751fee`, by disabling references
 456   in Pot files. Using `Locale::Po4a::write_if_needed` might be
 457   a cleaner solution. (warning: this function runs the external
 458   `diff` program, have to check security)
 459 - new translations created in the web interface must get proper
 460   charset/encoding gettext metadata, else the next automatic PO update
 461   removes any non-ascii chars; possible solution: put such metadata
 462   into the Pot file, and let it propagate; should be fixed in
 463   `773de05a7a1ee68d2bed173367cf5e716884945a`, time will tell.
 464
 465 Better links
 466 ------------
 467
 468 ### Page title in links
 469
 470 Using the fix to
 471 [[bugs/pagetitle_function_does_not_respect_meta_titles]] from
 472 [[intrigeri]]'s `meta` branch, the generated links' text is based on
 473 the page titles set with the [[meta|plugins/meta]] plugin. This has to
 474 be merged into ikiwiki upstream, though.
 475
 476 Robustness tests
 477 ----------------
 478
 479 ### Enabling/disabling the plugin
 480
 481 - enabling the plugin with `po_translatable_pages` set to blacklist: **OK**
 482 - enabling the plugin with `po_translatable_pages` set to whitelist: **OK**
 483 - enabling the plugin without `po_translatable_pages` set: **OK**
 484 - disabling the plugin: **OK**
 485
 486 ### Changing the plugin config
 487
 488 - adding existing pages to `po_translatable_pages`: **OK**
 489 - removing existing pages from `po_translatable_pages`: **OK**
 490 - adding a language to `po_slave_languages`: **OK**
 491 - removing a language from `po_slave_languages`: **OK**
 492 - changing `po_master_language`: **OK**
 493 - replacing `po_master_language` with a language previously part of
 494   `po_slave_languages`: needs two rebuilds, but **OK** (this is quite
 495   a perverse test actually)
 496
 497 ### Creating/deleting/renaming pages
 498
 499 All cases of master/slave page creation/deletion/rename, both via RCS
 500 and via CGI, have been tested.
 501
 502 ### Misc
 503
 504 - general test with `usedirs` disabled: **OK**
 505 - general test with `indexpages` enabled: **not OK**
 506 - general test with `po_link_to=default` with `userdirs` enabled: **OK**
 507 - general test with `po_link_to=default` with `userdirs` disabled: **OK**
 508
 509 Misc. bugs
 510 ----------
 511
 512 Documentation
 513 -------------
 514
 515 Maybe write separate documentation depending on the people it targets:
 516 translators, wiki administrators, hackers. This plugin may be complex
 517 enough to deserve this.