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 Security
 244 ========
 245
 246 [[./security]] contains a detailed security analysis of this plugin
 247 and its dependencies.
 248
 249 When using po4a older than 0.35, it is recommended to uninstall
 250 `Text::WrapI18N` (Debian package `libtext-wrapi18n-perl`), in order to
 251 avoid a potential denial of service.
 252
 253 TODO
 254 ====
 255
 256 Better links
 257 ------------
 258
 259 ### Page title in links
 260
 261 Using the fix to
 262 [[bugs/pagetitle_function_does_not_respect_meta_titles]] from
 263 [[intrigeri]]'s `meta` branch, the generated links' text is based on
 264 the page titles set with the [[meta|plugins/meta]] plugin. This has to
 265 be merged into ikiwiki upstream, though.
 266
 267 Robustness tests
 268 ----------------
 269
 270 ### Enabling/disabling the plugin
 271
 272 * enabling the plugin with `po_translatable_pages` set to blacklist: **OK**
 273 * enabling the plugin with `po_translatable_pages` set to whitelist: **OK**
 274 * enabling the plugin without `po_translatable_pages` set: **OK**
 275 * disabling the plugin: **OK**
 276
 277 ### Changing the plugin config
 278
 279 * adding existing pages to `po_translatable_pages`: **OK**
 280 * removing existing pages from `po_translatable_pages`: **OK**
 281 * adding a language to `po_slave_languages`: **OK**
 282 * removing a language from `po_slave_languages`: **OK**
 283 * changing `po_master_language`: **OK**
 284 * replacing `po_master_language` with a language previously part of
 285   `po_slave_languages`: needs two rebuilds, but **OK** (this is quite
 286   a perverse test actually)
 287
 288 ### Creating/deleting/renaming pages
 289
 290 All cases of master/slave page creation/deletion/rename, both via RCS
 291 and via CGI, have been tested.
 292
 293 ### Misc
 294
 295 * general test with `usedirs` disabled: **OK**
 296 * general test with `indexpages` enabled: **not OK**
 297 * general test with `po_link_to=default` with `userdirs` enabled: **OK**
 298 * general test with `po_link_to=default` with `userdirs` disabled: **OK**
 299
 300 Misc. bugs
 301 ----------
 302
 303 Documentation
 304 -------------
 305
 306 Maybe write separate documentation depending on the people it targets:
 307 translators, wiki administrators, hackers. This plugin may be complex
 308 enough to deserve this.