X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/ae474d8e14631ff519ed7d54bb64eaa0538f56d9..eeeda1295f08337f1321860d2b839732a46786e4:/doc/plugins/po.mdwn?ds=sidebyside diff --git a/doc/plugins/po.mdwn b/doc/plugins/po.mdwn index 756012890..8e87e2638 100644 --- a/doc/plugins/po.mdwn +++ b/doc/plugins/po.mdwn @@ -55,7 +55,7 @@ Supported languages languages, such as: po_slave_languages => { 'fr' => 'Français', - 'es' => 'Castellano', + 'es' => 'Español', 'de' => 'Deutsch', } @@ -150,24 +150,9 @@ display things only on translatable or translation pages. The `OTHERLANGUAGES` loop provides ways to display other languages' versions of the same page, and the translations' status. -One typically adds the following code to `templates/page.tmpl`: - - -
- -
- - -The following variables are available inside the loop (for every page in): +An example of its use can be found in the default +`templates/page.tmpl`. In case you want to customize it, the following +variables are available inside the loop (for every page in): * `URL` - url to the page * `CODE` - two-letters language code @@ -178,15 +163,8 @@ The following variables are available inside the loop (for every page in): ### Display the current translation status The `PERCENTTRANSLATED` variable is set to the translation -completeness, expressed in percent, on "slave" pages. - -One can use it this way: - - -
- -
- +completeness, expressed in percent, on "slave" pages. It is used by +the default `templates/page.tmpl`. Additional PageSpec tests ------------------------- @@ -231,8 +209,8 @@ preferred `$EDITOR`, without needing to be online. Markup languages support ------------------------ -Markdown is well supported. Some other markup languages supported by -ikiwiki mostly work, but some pieces of syntax are not rendered +[[Markdown|mdwn]] is well supported. Some other markup languages supported +by ikiwiki mostly work, but some pieces of syntax are not rendered correctly on the slave pages: * [[reStructuredText|rst]]: anonymous hyperlinks and internal @@ -246,7 +224,7 @@ correctly on the slave pages: Security ======== -[[./security]] contains a detailed security analysis of this plugin +[[po/discussion]] contains a detailed security analysis of this plugin and its dependencies. When using po4a older than 0.35, it is recommended to uninstall @@ -272,41 +250,56 @@ once [[intrigeri]]'s `meta` branch is merged. An integration branch, called `meta-po`, merges [[intrigeri]]'s `po` and `meta` branches, and thus has thise additional features. -Robustness tests ----------------- -### Enabling/disabling the plugin +Language display order +---------------------- + +Jonas pointed out that one might want to control the order that links to +other languages are listed, for various reasons. Currently, there is no +order, as `po_slave_languages` is a hash. It would need to be converted +to an array to support this. (If twere done, twere best done quickly.) +--[[Joey]] + +po files in underlay +-------------------- + +I think this plugin doesn't yet allow po files to be present in an +underlay to translate files also from the underlay. -* enabling the plugin with `po_translatable_pages` set to blacklist: **OK** -* enabling the plugin with `po_translatable_pages` set to whitelist: **OK** -* enabling the plugin without `po_translatable_pages` set: **OK** -* disabling the plugin: **OK** +In `istranslatablefile`, it specifically checks that +the file is present in srcdir. -### Changing the plugin config +Problem with this is that it precludes using po to translate +the basewiki (work which is well under way for Danish BTW), +since the translated po files cannot really be used. -* adding existing pages to `po_translatable_pages`: **OK** -* removing existing pages from `po_translatable_pages`: **OK** -* adding a language to `po_slave_languages`: **OK** -* removing a language from `po_slave_languages`: **OK** -* changing `po_master_language`: **OK** -* replacing `po_master_language` with a language previously part of - `po_slave_languages`: needs two rebuilds, but **OK** (this is quite - a perverse test actually) +A further problem comes if one wants to use a non-English language as the +`po_master_language`. It would be good to get a translated +basewiki, taking po files from the underlay and using them as the primary +page sources, but this plugin doesn't yet support that. -### Creating/deleting/renaming pages +And, maybe it shouldn't? A user would not expect to see a po file when +editing the index page of their wiki, just because they're using a +different language. Instead, we might want to build localized .mdwn files +for the basewiki, and then ikiwiki would just use that translated underlay. +The when the user edits index, they get a nice mdwn file to start from. -All cases of master/slave page creation/deletion/rename, both via RCS -and via CGI, have been tested. +So, we seem to have two cases, in one po files from the underlay should be +used, in the other not. Hmm. Support both? -### Misc +> Update -- I've written po2wiki, which can spit out translated underlays +> in markdown format, and made the po plugin enable use of such underlays +> when the master language is not `en`. +--[[Joey]] -* general test with `usedirs` disabled: **OK** -* general test with `indexpages` enabled: **not OK** -* general test with `po_link_to=default` with `userdirs` enabled: **OK** -* general test with `po_link_to=default` with `userdirs` disabled: **OK** +Duplicate %links ? +------------------ -Misc. bugs ----------- +I notice code in the scan hook that seems to assume +that %links will accumulate duplicate links for a page. +That used to be so, but the bug was fixed. Does this mean +that po might be replacing the only link on a page, in error? +--[[Joey]] Documentation -------------