git.oblomov.eu Git - ikiwiki/blob - 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]]
  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
  35 Configuration
  36 =============
  37
  38 Supported languages
  39 -------------------
  40
  41 `po_master_language` is used to set the "master" language in
  42 `ikiwiki.setup`, such as:
  43
  44         po_master_language => { 'code' => 'en', 'name' => 'English' }
  45
  46 `po_slave_languages` is used to set the list of supported "slave"
  47 languages, such as:
  48
  49         po_slave_languages => { 'fr' => 'Français',
  50                                 'es' => 'Castellano',
  51                                 'de' => 'Deutsch',
  52         }
  53
  54 Decide which pages are translatable
  55 -----------------------------------
  56
  57 The `po_translatable_pages` setting configures what pages are
  58 translatable. It is a [[ikiwiki/PageSpec]], so you have lots of
  59 control over what kind of pages are translatable.
  60
  61 The `.po` files are not considered as being translatable, so you don't need to
  62 worry about excluding them explicitly from this [[ikiwiki/PageSpec]].
  63
  64 Internal links
  65 --------------
  66
  67 The `po_link_to` option in `ikiwiki.setup` is used to decide how
  68 internal links should be generated, depending on web server features
  69 and site-specific preferences.
  70
  71 ### Default linking behavior
  72
  73 If `po_link_to` is unset, or set to `default`, ikiwiki's default
  74 linking behavior is preserved: `\[[destpage]]` links to the master
  75 language's page.
  76
  77 ### Link to current language
  78
  79 If `po_link_to` is set to `current`, `\[[destpage]]` links to the
  80 `destpage`'s version written in the current page's language, if
  81 available, *i.e.*:
  82
  83 - `foo/destpage/index.LL.html` if `usedirs` is enabled
  84 - `foo/destpage.LL.html` if `usedirs` is disabled
  85
  86 ### Link to negotiated language
  87
  88 If `po_link_to` is set to `negotiated`, `\[[page]]` links to the
  89 negotiated preferred language, *i.e.* `foo/page/`.
  90
  91 (In)compatibility notes:
  92
  93 - if `usedirs` is disabled, it does not make sense to set `po_link_to`
  94   to `negotiated`; this option combination is neither implemented
  95   nor allowed.
  96 - if the web server does not support Content Negotiation, setting
  97   `po_link_to` to `negotiated` will produce a unusable website.
  98
  99
 100 Server support
 101 ==============
 102
 103 Apache
 104 ------
 105
 106 Using Apache `mod_negotiation` makes it really easy to have Apache
 107 serve any page in the client's preferred language, if available.
 108 This is the default Debian Apache configuration.
 109
 110 When `usedirs` is enabled, one has to set `DirectoryIndex index` for
 111 the wiki context.
 112
 113 Setting `DefaultLanguage LL` (replace `LL` with your default MIME
 114 language code) for the wiki context can help to ensure
 115 `bla/page/index.en.html` is served as `Content-Language: LL`.
 116
 117 lighttpd
 118 --------
 119
 120 lighttpd unfortunately does not support content negotiation.
 121
 122 **FIXME**: does `mod_magnet` provide the functionality needed to
 123  emulate this?
 124
 125
 126 Usage
 127 =====
 128
 129 Templates
 130 ---------
 131
 132 The `ISTRANSLATION` and `ISTRANSLATABLE` variables can be used to
 133 display things only on translatable or translation pages.
 134
 135 ### Display page's versions in other languages
 136
 137 The `OTHERLANGUAGES` loop provides ways to display other languages'
 138 versions of the same page, and the translations' status.
 139
 140 One typically adds the following code to `templates/page.tmpl`:
 141
 142         <TMPL_IF NAME="OTHERLANGUAGES">
 143         <div id="otherlanguages">
 144           <ul>
 145           <TMPL_LOOP NAME="OTHERLANGUAGES">
 146             <li>
 147               <a href="<TMPL_VAR NAME="URL">"><TMPL_VAR NAME="LANGUAGE"></a>
 148               <TMPL_UNLESS NAME="MASTER">
 149                 (<TMPL_VAR NAME="PERCENT">&nbsp;%)
 150               </TMPL_UNLESS>
 151             </li>
 152           </TMPL_LOOP>
 153           </ul>
 154         </div>
 155         </TMPL_IF>
 156
 157 The following variables are available inside the loop (for every page in):
 158
 159 - `URL` - url to the page
 160 - `CODE` - two-letters language code
 161 - `LANGUAGE` - language name (as defined in `po_slave_languages`)
 162 - `MASTER` - is true (1) if, and only if the page is a "master" page
 163 - `PERCENT` - for "slave" pages, is set to the translation completeness, in percents
 164
 165 ### Display the current translation status
 166
 167 The `PERCENTTRANSLATED` variable is set to the translation
 168 completeness, expressed in percent, on "slave" pages.
 169
 170 One can use it this way:
 171
 172         <TMPL_IF NAME="ISTRANSLATION">
 173         <div id="percenttranslated">
 174           <TMPL_VAR NAME="PERCENTTRANSLATED">
 175         </div>
 176         </TMPL_IF>
 177
 178 Additional PageSpec tests
 179 -------------------------
 180
 181 This plugin enhances the regular [[ikiwiki/PageSpec]] syntax with some
 182 additional tests that are documented [[here|ikiwiki/pagespec/po]].
 183
 184 Automatic PO file update
 185 ------------------------
 186
 187 Committing changes to a "master" page:
 188
 189 1. updates the POT file and the PO files for the "slave" languages;
 190    the updated PO files are then put under version control;
 191 2. triggers a refresh of the corresponding HTML slave pages.
 192
 193 Also, when the plugin has just been enabled, or when a page has just
 194 been declared as being translatable, the needed POT and PO files are
 195 created, and the PO files are checked into version control.
 196
 197 Discussion pages
 198 ----------------
 199
 200 Discussion should happen in the language in which the pages are
 201 written for real, *i.e.* the "master" one. If discussion pages are
 202 enabled, "slave" pages therefore link to the "master" page's
 203 discussion page.
 204
 205 Translating
 206 -----------
 207
 208 One can edit the PO files using ikiwiki's CGI (a message-by-message
 209 interface could also be implemented at some point).
 210
 211 If [[tips/untrusted_git_push]] is setup, one can edit the PO files in one's
 212 preferred `$EDITOR`, without needing to be online.
 213
 214 TODO
 215 ====
 216
 217 Security checks
 218 ---------------
 219
 220 ### Security history
 221
 222 The only past security issues I could find in GNU gettext and po4a
 223 are:
 224
 225 - [CVE-2004-0966](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2004-0966),
 226   *i.e.* [Debian bug #278283](http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=278283):
 227   the autopoint and gettextize scripts in the GNU gettext package
 228   1.14 and later versions, as used in Trustix Secure Linux 1.5
 229   through 2.1 and other operating systems, allows local users to
 230   overwrite files via a symlink attack on temporary files.
 231 - [CVE-2007-4462](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2007-4462):
 232   `lib/Locale/Po4a/Po.pm` in po4a before 0.32 allows local users to
 233   overwrite arbitrary files via a symlink attack on the
 234   gettextization.failed.po temporary file.
 235
 236 **FIXME**: check whether this plugin would have been a possible attack
 237 vector to exploit these vulnerabilities.
 238
 239 Depending on my mood, the lack of found security issues can either
 240 indicate that there are none, or reveal that no-one ever bothered to
 241 find (and publish) them.
 242
 243 ### PO file features
 244
 245 Can any sort of directives be put in po files that will cause mischief
 246 (ie, include other files, run commands, crash gettext, whatever)?
 247
 248 > No [documented](http://www.gnu.org/software/gettext/manual/gettext.html#PO-Files)
 249 > directive is supposed to do so.
 250
 251 ### Running po4a on untrusted content
 252
 253 Are there any security issues on running po4a on untrusted content?
 254
 255 > To say the least, this issue is not well covered, at least publicly:
 256 >
 257 > - the documentation does not talk about it;
 258 > - grep'ing the source code for `security` or `trust` gives no answer.
 259 >
 260 > I'll ask their opinion to the po4a maintainers.
 261 >
 262 > I'm not in a position to audit the code, but I had a look anyway:
 263 >
 264 > - no use of `system()`, `exec()` or backticks in `Locale::Po4a`; are
 265 >   there any other way to run external programs in Perl?
 266 > - a symlink attack vulnerability was already discovered, so I "hope"
 267 >   the code has been checked to find some more already
 268 > - the po4a parts we are using themselves use the following Perl
 269 >   modules: `DynaLoader`, `Encode`, `Encode::Guess`,
 270 >   `Text::WrapI18N`, `Locale::gettext` (`bindtextdomain`,
 271 >   `textdomain`, `gettext`, `dgettext`)
 272 >
 273 >  --[[intrigeri]]
 274
 275 ### Fuzzing input
 276
 277 I was not able to find any public information about gettext or po4a
 278 having been tested with a fuzzing program, such as `zzuf` or `fusil`.
 279 Moreover, some gettext parsers seem to be quite
 280 [easy to crash](http://fusil.hachoir.org/trac/browser/trunk/fuzzers/fusil-gettext),
 281 so it might be useful to bang gettext/po4a's heads against such
 282 a program in order to easily detect some of the most obvious DoS.
 283 [[--intrigeri]]
 284
 285 gettext/po4a rough corners
 286 --------------------------
 287
 288 - fix infinite loop when synchronizing two ikiwiki (when checkouts
 289   live in different directories): say bla.fr.po has been updated in
 290   repo2; pulling repo2 from repo1 seems to trigger a PO update, that
 291   changes bla.fr.po in repo1; then pushing repo1 to repo2 triggers
 292   a PO update, that changes bla.fr.po in repo2; etc.; quickly fixed in
 293   `629968fc89bced6727981c0a1138072631751fee`, by disabling references
 294   in Pot files. Using `Locale::Po4a::write_if_needed` might be
 295   a cleaner solution.
 296 - new translations created in the web interface must get proper
 297   charset/encoding gettext metadata, else the next automatic PO update
 298   removes any non-ascii chars; possible solution: put such metadata
 299   into the Pot file, and let it propagate; should be fixed in
 300   `773de05a7a1ee68d2bed173367cf5e716884945a`, time will tell.
 301
 302 Misc. improvements
 303 ------------------
 304
 305 ### page titles
 306
 307 Use nice page titles from meta plugin in links, as inline already
 308 does. This is actually a duplicate for
 309 [[bugs/pagetitle_function_does_not_respect_meta_titles]], which might
 310 be fixed by something like [[todo/using_meta_titles_for_parentlinks]].
 311
 312 Translation quality assurance
 313 -----------------------------
 314
 315 Modifying a PO file via the CGI must be forbidden if the new version
 316 is not a valid PO file. As a bonus, check that it provides a more
 317 complete translation than the existing one.
 318
 319 A new `cansave` type of hook would be needed to implement this.
 320
 321 Note: committing to the underlying repository is a way to bypass
 322 this check.