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 > I proposed a patch based on Joey's to po4a-devel, allowing to fully
 337 > disable this module's use. When it is merged upstream, we'll need to add
 338 > `use Locale::Po4a::Common qw(nowrapi18n)` to `po.pm`, before loading
 339 > any other `Locale::Po4a` module. A versioned dependency may be needed.
 340 > --[[intrigeri]]
 341
 342 ##### Term::ReadKey
 343
 344 `Term::ReadKey` is not a hard dependency in our case, *i.e.* po4a
 345 works nicely without it. But the po4a Debian package recommends
 346 `libterm-readkey-perl`, so it will probably be installed on most
 347 systems using the po plugin.
 348
 349 `Term::ReadKey` has too far reaching implications for us to
 350 be able to guarantee anything wrt. security.
 351
 352 > The option that disables `Text::WrapI18N` also disables
 353 > `Term::ReadKey` as a consequence. [[--intrigeri]]
 354
 355 ### msgmerge
 356
 357 `refreshpofiles()` runs this external program.
 358
 359 A po4a developer answered he does "not expect any security issues from
 360 it". I did not manage to crash it with `zzuf`, nor was able to find
 361 any past security holes.
 362
 363 ### msgfmt
 364
 365 `isvalidpo()` runs this external program.
 366
 367 * I could not manage to make it behave badly using zzuf, it exits
 368   cleanly when too many errors are detected.
 369 * I could not find any past security holes.
 370
 371 ### Fuzzing input
 372
 373 Test conditions:
 374
 375 - a 21M file containing 100 concatenated copies of all the files in my
 376   `/usr/share/common-licenses/`; I had no existing PO file or
 377   translated versions at hand, which renders these tests
 378   quite incomplete.
 379 - po4a was the Debian 0.34-2 package; the same tests were also run
 380   after replacing the `Text` module with the CVS one (the core was not
 381   changed in CVS since 0.34-2 was released), without any significant
 382   difference in the results.
 383 - Perl 5.10.0-16
 384
 385 #### po4a-gettextize
 386
 387 `po4a-gettextize` uses more or less the same po4a features as our
 388 `refreshpot` function.
 389
 390 Without specifying an input charset, zzuf'ed `po4a-gettextize` quickly
 391 errors out, complaining it was not able to detect the input charset;
 392 it leaves no incomplete file on disk.
 393
 394 So I had to pretend the input was in UTF-8, as does the po plugin.
 395
 396 Two ways of crashing were revealed by this command-line:
 397
 398         zzuf -vc -s 0:100 -r 0.1:0.5 \
 399           po4a-gettextize -f text -o markdown -M utf-8 -L utf-8 \
 400             -m LICENSES >/dev/null
 401
 402 They are:
 403
 404         Malformed UTF-8 character (UTF-16 surrogate 0xdcc9) in substitution iterator at /usr/share/perl5/Locale/Po4a/Po.pm line 1443.
 405         Malformed UTF-8 character (fatal) at /usr/share/perl5/Locale/Po4a/Po.pm line 1443.
 406
 407 and
 408
 409         Malformed UTF-8 character (UTF-16 surrogate 0xdcec) in substitution (s///) at /usr/share/perl5/Locale/Po4a/Po.pm line 1443.
 410         Malformed UTF-8 character (fatal) at /usr/share/perl5/Locale/Po4a/Po.pm line 1443.
 411
 412 Perl seems to exit cleanly, and an incomplete PO file is written on
 413 disk. I not sure whether if this is a bug in Perl or in `Po.pm`.
 414
 415 > It's fairly standard perl behavior when fed malformed utf-8. As long as it doesn't
 416 > crash ikiwiki, it's probably acceptable. Ikiwiki can do some similar things itself when fed malformed utf-8 (doesn't crash tho) --[[Joey]]
 417
 418 #### po4a-translate
 419
 420 `po4a-translate` uses more or less the same po4a features as our
 421 `filter` function.
 422
 423 Without specifying an input charset, same behaviour as
 424 `po4a-gettextize`, so let's specify UTF-8 as input charset as of now.
 425
 426         zzuf -cv \
 427           po4a-translate -d -f text -o markdown -M utf-8 -L utf-8 \
 428             -k 0 -m LICENSES -p LICENSES.fr.po -l test.fr
 429
 430 ... prints tons of occurences of the following error, but a complete
 431 translated document is written (obviously with some weird chars
 432 inside):
 433
 434         Use of uninitialized value in string ne at /usr/share/perl5/Locale/Po4a/TransTractor.pm line 854.
 435         Use of uninitialized value in string ne at /usr/share/perl5/Locale/Po4a/TransTractor.pm line 840.
 436         Use of uninitialized value in pattern match (m//) at /usr/share/perl5/Locale/Po4a/Po.pm line 1002.
 437
 438 While:
 439
 440         zzuf -cv -s 0:10 -r 0.001:0.3 \
 441           po4a-translate -d -f text -o markdown -M utf-8 -L utf-8 \
 442             -k 0 -m LICENSES -p LICENSES.fr.po -l test.fr
 443
 444 ... seems to lose the fight, at the `readpo(LICENSES.fr.po)` step,
 445 against some kind of infinite loop, deadlock, or any similar beast.
 446
 447 The root of this bug lies in `Text::WrapI18N`, see above for
 448 possible solutions.
 449
 450 gettext/po4a rough corners
 451 --------------------------
 452
 453 - fix infinite loop when synchronizing two ikiwiki (when checkouts
 454   live in different directories): say bla.fr.po has been updated in
 455   repo2; pulling repo2 from repo1 seems to trigger a PO update, that
 456   changes bla.fr.po in repo1; then pushing repo1 to repo2 triggers
 457   a PO update, that changes bla.fr.po in repo2; etc.; quickly fixed in
 458   `629968fc89bced6727981c0a1138072631751fee`, by disabling references
 459   in Pot files. Using `Locale::Po4a::write_if_needed` might be
 460   a cleaner solution. (warning: this function runs the external
 461   `diff` program, have to check security)
 462 - new translations created in the web interface must get proper
 463   charset/encoding gettext metadata, else the next automatic PO update
 464   removes any non-ascii chars; possible solution: put such metadata
 465   into the Pot file, and let it propagate; should be fixed in
 466   `773de05a7a1ee68d2bed173367cf5e716884945a`, time will tell.
 467
 468 Better links
 469 ------------
 470
 471 ### Page title in links
 472
 473 Using the fix to
 474 [[bugs/pagetitle_function_does_not_respect_meta_titles]] from
 475 [[intrigeri]]'s `meta` branch, the generated links' text is based on
 476 the page titles set with the [[meta|plugins/meta]] plugin. This has to
 477 be merged into ikiwiki upstream, though.
 478
 479 Robustness tests
 480 ----------------
 481
 482 ### Enabling/disabling the plugin
 483
 484 - enabling the plugin with `po_translatable_pages` set to blacklist: **OK**
 485 - enabling the plugin with `po_translatable_pages` set to whitelist: **OK**
 486 - enabling the plugin without `po_translatable_pages` set: **OK**
 487 - disabling the plugin: **OK**
 488
 489 ### Changing the plugin config
 490
 491 - adding existing pages to `po_translatable_pages`: **OK**
 492 - removing existing pages from `po_translatable_pages`: **OK**
 493 - adding a language to `po_slave_languages`: **OK**
 494 - removing a language from `po_slave_languages`: **OK**
 495 - changing `po_master_language`: **OK**
 496 - replacing `po_master_language` with a language previously part of
 497   `po_slave_languages`: needs two rebuilds, but **OK** (this is quite
 498   a perverse test actually)
 499
 500 ### Creating/deleting/renaming pages
 501
 502 All cases of master/slave page creation/deletion/rename, both via RCS
 503 and via CGI, have been tested.
 504
 505 ### Misc
 506
 507 - general test with `usedirs` disabled: **OK**
 508 - general test with `indexpages` enabled: **not OK**
 509 - general test with `po_link_to=default` with `userdirs` enabled: **TODO**
 510 - general test with `po_link_to=default` with `userdirs` disabled: **OK**
 511
 512 Misc. bugs
 513 ----------
 514
 515 * link to create missing page from translation is wrong (translations
 516   have no subpages)
 517
 518 Documentation
 519 -------------
 520
 521 Maybe write separate documentation depending on the people it targets:
 522 translators, wiki administrators, hackers. This plugin may be complex
 523 enough to deserve this.