`po_slave_languages` is used to set the list of supported "slave"
languages, such as:
- po_slave_languages => { 'fr' => 'Français',
- 'es' => 'Castellano',
+ po_slave_languages => [ 'fr' => 'Français',
+ 'es' => 'Español',
'de' => 'Deutsch',
- }
+ ]
Decide which pages are translatable
-----------------------------------
Using Apache `mod_negotiation` makes it really easy to have Apache
serve any page in the client's preferred language, if available.
-This is the default Debian Apache configuration.
+
+Add 'Options MultiViews' to the wiki directory's configuration in Apache.
When `usedirs` is enabled, one has to set `DirectoryIndex index` for
the wiki context.
language code) for the wiki context can help to ensure
`bla/page/index.en.html` is served as `Content-Language: LL`.
+For details, see [Apache's documentation](http://httpd.apache.org/docs/2.2/content-negotiation.html).
+
lighttpd
--------
-lighttpd unfortunately does not support content negotiation.
+Recent versions of lighttpd should be able to use
+`$HTTP["language"]` to configure the translated pages to be served.
-**FIXME**: does `mod_magnet` provide the functionality needed to
- emulate this?
+See [Lighttpd Issue](http://redmine.lighttpd.net/issues/show/1119)
+TODO: Example
Usage
=====
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`:
-
- <TMPL_IF NAME="OTHERLANGUAGES">
- <div id="otherlanguages">
- <ul>
- <TMPL_LOOP NAME="OTHERLANGUAGES">
- <li>
- <a href="<TMPL_VAR NAME="URL">"><TMPL_VAR NAME="LANGUAGE"></a>
- <TMPL_UNLESS NAME="MASTER">
- (<TMPL_VAR NAME="PERCENT"> %)
- </TMPL_UNLESS>
- </li>
- </TMPL_LOOP>
- </ul>
- </div>
- </TMPL_IF>
-
-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
### 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:
-
- <TMPL_IF NAME="ISTRANSLATION">
- <div id="percenttranslated">
- <TMPL_VAR NAME="PERCENTTRANSLATED">
- </div>
- </TMPL_IF>
+completeness, expressed in percent, on "slave" pages. It is used by
+the default `templates/page.tmpl`.
Additional PageSpec tests
-------------------------
Markup languages support
------------------------
-Markdown 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:
+[[Markdown|mdwn]] and [[html]] 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:
* [[reStructuredText|rst]]: anonymous hyperlinks and internal
cross-references
* [[wikitext]]: conversion of newlines to paragraphs
* [[creole]]: verbatim text is wrapped, tables are broken
-* [[html]] and LaTeX: not supported yet; the dedicated po4a modules
- could be used to support them, but they would need a security audit
+* LaTeX: not supported yet; the dedicated po4a module
+ could be used to support it, but it would need a security audit
* other markup languages have not been tested.
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
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.
+and `meta` branches, and thus has this additional features.
+
+Pagespecs
+---------
+
+I was suprised that, when using the map directive, a pagespec of "*"
+listed all the translated pages as well as regular pages. That can
+make a big difference to an existing wiki when po is turned on,
+and seems generally not wanted.
+(OTOH, you do want to match translated pages by
+default when locking pages.) --[[Joey]]
+
+Edit links on untranslated pages
+--------------------------------
-Robustness tests
-----------------
+If a page is not translated yet, the "translated" version of it
+displays wikilinks to other, existing (but not yet translated?)
+pages as edit links, as if those pages do not exist.
-### Enabling/disabling the plugin
+That's really confusing, especially as clicking such a link
+brings up an edit form to create a new, english page.
-* 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**
+This is with po_link_to=current or negotiated. With default, it doesn't
+happen..
-### Changing the plugin config
+Also, this may only happen if the page being linked to is coming from an
+underlay, and the underlays lack translation to a given language.
+--[[Joey]]
-* 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)
+> Any simple testcase to reproduce it, please? I've never seen this
+> happen yet. --[[intrigeri]]
-### Creating/deleting/renaming pages
+Double commits of po files
+--------------------------
-All cases of master/slave page creation/deletion/rename, both via RCS
-and via CGI, have been tested.
+When adding a new english page, the po files are created, committed,
+and then committed again. The second commit makes this change:
+
+ -"Content-Type: text/plain; charset=utf-8\n"
+ -"Content-Transfer-Encoding: ENCODING"
+ +"Content-Type: text/plain; charset=UTF-8\n"
+ +"Content-Transfer-Encoding: ENCODING\n"
+
+Same thing happens when a change to an existing page triggers a po file
+update. --[[Joey]]
+
+> * The s/utf-8/UTF-8 part is fixed in my po branch.
+> * The ENCODING\n part is due to an inconsistency in po4a, which
+> I've just send a patch for. --[[intrigeri]]
+
+Ugly messages with empty files
+------------------------------
+
+If there are empty .mdwn files, the po plugin displays some ugly messages.
+
+> This is due to a bug in po4a (not checking definedness of a
+> variable). One-liner patch sent. --[[intrigeri]]
+
+Translation of directives
+-------------------------
-### Misc
+If a translated page contains a directive, it may expand to some english
+text, or text in whatever single language ikiwiki is configured to "speak".
-* 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**
+Maybe there could be a way to switch ikiwiki to speaking another language
+when building a non-english page? Then the directives would get translated.
-Misc. bugs
-----------
+(We also will need this in order to use translated templates, when they are
+available.)
Documentation
-------------
projects / ikiwiki.git / blobdiff