<!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>po</title> <meta name="viewport" content="width=device-width, initial-scale=1" /> <link rel="stylesheet" href="../style.css" type="text/css" /> <link rel="stylesheet" href="../local.css" type="text/css" /> </head> <body> <div class="page"> <div class="pageheader"> <div class="header"> <span> <span class="parentlinks"> <a href="../index.html">ikiwiki</a>/ <a href="../plugins.html">plugins</a>/ </span> <span class="title"> po </span> </span> </div> </div> <div id="pagebody"> <div id="content" role="main"> <p><span class="infobox"> Plugin: po<br /> Author: <span class="createlink">intrigeri</span><br /> Included in ikiwiki: yes<br /> Enabled by default: no<br /> Included in <a href="./goodstuff.html">goodstuff</a>: no<br /> Currently enabled: no<br /> </span></p> <p>This plugin adds support for multi-lingual wikis, translated with gettext, using <a href="http://po4a.alioth.debian.org/">po4a</a>.</p> <p>It depends on the Perl <code>Locale::Po4a::Po</code> library (<code>apt-get install po4a</code>). As detailed bellow in the security section, <code>po4a</code> is subject to denial-of-service attacks before version 0.35.</p> <div class="toc"> <ol> <li class="L1"><a href="#index1h1">Introduction</a> </li> <li class="L1"><a href="#index2h1">(In)Compatibility</a> </li> <li class="L1"><a href="#index3h1">Configuration</a> <ol> <li class="L2"><a href="#index1h2">Supported languages</a> </li> <li class="L2"><a href="#index2h2">Decide which pages are translatable</a> </li> <li class="L2"><a href="#index3h2">Internal links</a> </li> </ol> </li> <li class="L1"><a href="#index4h1">Server support</a> <ol> <li class="L2"><a href="#index4h2">Apache</a> </li> <li class="L2"><a href="#index5h2">lighttpd</a> </li> </ol> </li> <li class="L1"><a href="#index5h1">Usage</a> <ol> <li class="L2"><a href="#index6h2">Templates</a> </li> <li class="L2"><a href="#index7h2">Additional PageSpec tests</a> </li> <li class="L2"><a href="#index8h2">Automatic PO file update</a> </li> <li class="L2"><a href="#index9h2">Discussion pages and other sub-pages</a> </li> <li class="L2"><a href="#index10h2">Translating</a> </li> <li class="L2"><a href="#index11h2">Markup languages support</a> </li> <li class="L2"><a href="#index12h2">Renaming a page</a> </li> </ol> </li> <li class="L1"><a href="#index6h1">Security</a> </li> <li class="L1"><a href="#index7h1">BUGS</a> </li> <li class="L1"><a href="#index8h1">TODO</a> </li> </ol> </div> <h1><a name="index1h1"></a>Introduction</h1> <p>A language is chosen as the "master" one, and any other supported language is a "slave" one.</p> <p>A page written in the "master" language is a "master" page. It can be of any page type supported by ikiwiki, except <code>po</code>. It does not have to be named a special way: migration to this plugin does not imply any page renaming work.</p> <p>Example: <code>bla/page.mdwn</code> is a "master" Markdown page written in English; if <code>usedirs</code> is enabled, it is rendered as <code>bla/page/index.en.html</code>, else as <code>bla/page.en.html</code>.</p> <p>Any translation of a "master" page into a "slave" language is called a "slave" page; it is written in the gettext PO format. <code>po</code> is now a page type supported by ikiwiki.</p> <p>Example: <code>bla/page.fr.po</code> is the PO "message catalog" used to translate <code>bla/page.mdwn</code> into French; if <code>usedirs</code> is enabled, it is rendered as <code>bla/page/index.fr.html</code>, else as <code>bla/page.fr.html</code></p> <h1><a name="index2h1"></a>(In)Compatibility</h1> <p>This plugin does not support the <code>indexpages</code> mode (a.k.a. "use page/index.mdwn source files"). If you don't know what it is, you probably don't care.</p> <h1><a name="index3h1"></a>Configuration</h1> <h2><a name="index1h2"></a>Supported languages</h2> <p><code>po_master_language</code> is used to set the "master" language in <code>ikiwiki.setup</code>, such as:</p> <pre><code> po_master_language: en|English </code></pre> <p><code>po_slave_languages</code> is used to set the list of supported "slave" languages, such as:</p> <pre><code> po_slave_languages: - fr|Français - es|Español - de|Deutsch </code></pre> <h2><a name="index2h2"></a>Decide which pages are translatable</h2> <p>The <code>po_translatable_pages</code> setting configures what pages are translatable. It is a <a href="../ikiwiki/pagespec.html">PageSpec</a>, so you have lots of control over what kind of pages are translatable.</p> <p>The <code>.po</code> files are not considered as being translatable, so you don't need to worry about excluding them explicitly from this <a href="../ikiwiki/pagespec.html">PageSpec</a>.</p> <h2><a name="index3h2"></a>Internal links</h2> <h3><a name="index1h3"></a>Links targets</h3> <p>The <code>po_link_to</code> option in <code>ikiwiki.setup</code> is used to decide how internal links should be generated, depending on web server features and site-specific preferences.</p> <h4><a name="index1h4"></a>Default linking behavior</h4> <p>If <code>po_link_to</code> is unset, or set to <code>default</code>, ikiwiki's default linking behavior is preserved: <code>[[destpage]]</code> links to the master language's page.</p> <h4><a name="index2h4"></a>Link to current language</h4> <p>If <code>po_link_to</code> is set to <code>current</code>, <code>[[destpage]]</code> links to the <code>destpage</code>'s version written in the current page's language, if available, <em>i.e.</em>:</p> <ul> <li><code>foo/destpage/index.LL.html</code> if <code>usedirs</code> is enabled</li> <li><code>foo/destpage.LL.html</code> if <code>usedirs</code> is disabled</li> </ul> <h4><a name="index3h4"></a>Link to negotiated language</h4> <p>If <code>po_link_to</code> is set to <code>negotiated</code>, <code>[[page]]</code> links to the negotiated preferred language, <em>i.e.</em> <code>foo/page/</code>.</p> <p>(In)compatibility notes:</p> <ul> <li>if <code>usedirs</code> is disabled, it does not make sense to set <code>po_link_to</code> to <code>negotiated</code>; this option combination is neither implemented nor allowed.</li> <li>if the web server does not support Content Negotiation, setting <code>po_link_to</code> to <code>negotiated</code> will produce a unusable website.</li> </ul> <h1><a name="index4h1"></a>Server support</h1> <h2><a name="index4h2"></a>Apache</h2> <p>Using Apache <code>mod_negotiation</code> makes it really easy to have Apache serve any page in the client's preferred language, if available.</p> <p>Add 'Options MultiViews' to the wiki directory's configuration in Apache.</p> <p>When <code>usedirs</code> is enabled, you should also set <code>DirectoryIndex index</code>.</p> <p>These settings are also recommended, in order to avoid serving up rss files as index pages:</p> <pre><code>AddType application/rss+xml;qs=0.8 .rss AddType application/atom+xml;qs=0.8 .atom </code></pre> <p>For details, see <a href="http://httpd.apache.org/docs/2.2/content-negotiation.html">Apache's documentation</a>.</p> <h2><a name="index5h2"></a>lighttpd</h2> <p>Recent versions of lighttpd should be able to use <code>$HTTP["language"]</code> to configure the translated pages to be served.</p> <p>See <a href="http://redmine.lighttpd.net/issues/show/1119">Lighttpd Issue</a></p> <p>TODO: Example</p> <h1><a name="index5h1"></a>Usage</h1> <h2><a name="index6h2"></a>Templates</h2> <p>When <code>po_link_to</code> is not set to <code>negotiated</code>, one should replace some occurrences of <code>BASEURL</code> with <code>HOMEPAGEURL</code> to get correct links to the wiki homepage.</p> <p>The <code>ISTRANSLATION</code> and <code>ISTRANSLATABLE</code> variables can be used to display things only on translatable or translation pages.</p> <p>The <code>LANG_CODE</code> and <code>LANG_NAME</code> variables can respectively be used to display the current page's language code and pretty name.</p> <h3><a name="index2h3"></a>Display page's versions in other languages</h3> <p>The <code>OTHERLANGUAGES</code> loop provides ways to display other languages' versions of the same page, and the translations' status.</p> <p>An example of its use can be found in the default <code>templates/page.tmpl</code>. In case you want to customize it, the following variables are available inside the loop (for every page in):</p> <ul> <li><code>URL</code> - url to the page</li> <li><code>CODE</code> - two-letters language code</li> <li><code>LANGUAGE</code> - language name (as defined in <code>po_slave_languages</code>)</li> <li><code>MASTER</code> - is true (1) if, and only if the page is a "master" page</li> <li><code>PERCENT</code> - for "slave" pages, is set to the translation completeness, in percents</li> </ul> <h3><a name="index3h3"></a>Display the current translation status</h3> <p>The <code>PERCENTTRANSLATED</code> variable is set to the translation completeness, expressed in percent, on "slave" pages. It is used by the default <code>templates/page.tmpl</code>.</p> <h2><a name="index7h2"></a>Additional PageSpec tests</h2> <p>This plugin enhances the regular <a href="../ikiwiki/pagespec.html">PageSpec</a> syntax with some additional tests that are documented <a href="../ikiwiki/pagespec/po.html">here</a>.</p> <h2><a name="index8h2"></a>Automatic PO file update</h2> <p>Committing changes to a "master" page:</p> <ol> <li>updates the POT file and the PO files for the "slave" languages; the updated PO files are then put under version control;</li> <li>triggers a refresh of the corresponding HTML slave pages.</li> </ol> <p>Also, when the plugin has just been enabled, or when a page has just been declared as being translatable, the needed POT and PO files are created, and the PO files are checked into version control.</p> <h2><a name="index9h2"></a>Discussion pages and other sub-pages</h2> <p>Discussion should happen in the language in which the pages are written for real, <em>i.e.</em> the "master" one. If discussion pages are enabled, "slave" pages therefore link to the "master" page's discussion page.</p> <p>Likewise, "slave" pages are not supposed to have sub-pages; <a href="../ikiwiki/wikilink.html">WikiLinks</a> that appear on a "slave" page therefore link to the master page's sub-pages.</p> <h2><a name="index10h2"></a>Translating</h2> <p>One can edit the PO files using ikiwiki's CGI (a message-by-message interface could also be implemented at some point).</p> <p>If <a href="../tips/untrusted_git_push.html">untrusted git push</a> is setup, one can edit the PO files in one's preferred <code>$EDITOR</code>, without needing to be online.</p> <h2><a name="index11h2"></a>Markup languages support</h2> <p><a href="./mdwn.html">Markdown</a> and <a href="./html.html">html</a> are well supported. Some other markup languages supported by ikiwiki mostly work, but some pieces of syntax are not rendered correctly on the slave pages:</p> <ul> <li><a href="./rst.html">reStructuredText</a>: anonymous hyperlinks and internal cross-references</li> <li><a href="./wikitext.html">wikitext</a>: conversion of newlines to paragraphs</li> <li><a href="./creole.html">creole</a>: verbatim text is wrapped, tables are broken</li> <li>LaTeX: not supported yet; the dedicated po4a module could be used to support it, but it would need a security audit</li> <li>other markup languages have not been tested.</li> </ul> <h2><a name="index12h2"></a>Renaming a page</h2> <p>A translatable page may be renamed using the web interface and the <a href="./rename.html">rename plugin</a>, or using the VCS directly; in the latter case, <em>both</em> the "master" page and every corresponding <code>.po</code> file must be renamed in the same commit.</p> <h1><a name="index6h1"></a>Security</h1> <p><span class="createlink">discussion</span> contains a detailed security analysis of this plugin and its dependencies.</p> <p>When using po4a older than 0.35, it is recommended to uninstall <code>Text::WrapI18N</code> (Debian package <code>libtext-wrapi18n-perl</code>), in order to avoid a potential denial of service.</p> <h1><a name="index7h1"></a>BUGS</h1> <h1><a name="index8h1"></a>TODO</h1> </div> </div> <div id="footer" class="pagefooter" role="contentinfo"> <div id="pageinfo"> <div class="tags"> Tags: <a href="./type/format.html" rel="tag">type/format</a> </div> <div id="backlinks"> Links: <a href="./contrib/linguas.html">contrib/linguas</a> <a href="../features.html">features</a> <a href="../translation.html">translation</a> <a href="./write.html">write</a> </div> <div class="pagedate"> Last edited <span class="date">Tue Feb 26 23:01:54 2019</span> <!-- Created <span class="date">Tue Feb 26 23:01:54 2019</span> --> </div> </div> <!-- from ikiwiki --> </div> </div> </body> </html>
