example

[ikiwiki.git] / doc / plugins / po.mdwn

diff --git a/doc/plugins/po.mdwn b/doc/plugins/po.mdwn
index 235674f3167229be19c0deaa99d70f34b8461929..2e16cc7c457ae6f802938748da4edac628b4453c 100644 (file)
--- 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',
 languages, such as:
 
         po_slave_languages => { 'fr' => 'Français',

-                                'es' => 'Castellano',
+                                'es' => 'Español',

                                 'de' => 'Deutsch',
         }
 
                                 'de' => 'Deutsch',
         }
 


@@ -114,7 +114,8 @@ Apache
 
 Using Apache `mod_negotiation` makes it really easy to have Apache
 serve any page in the client's preferred language, if available.
 
 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.
 
 When `usedirs` is enabled, one has to set `DirectoryIndex index` for
 the wiki context.


@@ -123,14 +124,17 @@ Setting `DefaultLanguage LL` (replace `LL` with your default MIME
 language code) for the wiki context can help to ensure
 `bla/page/index.en.html` is served as `Content-Language: LL`.
 
 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
 --------
 

-lighttpd unfortunately does not support content negotiation.
+Recent versions of lighttpd should be able to use
+`$HTTP["language"]` to configure the translatted 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
 =====
 
 Usage
 =====


@@ -224,7 +228,7 @@ correctly on the slave pages:
 Security
 ========
 
 Security
 ========
 

-[[po/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
 and its dependencies.
 
 When using po4a older than 0.35, it is recommended to uninstall


@@ -248,43 +252,93 @@ ea753782b222bf4ba2fb4683b6363afdd9055b64, which should be reverted
 once [[intrigeri]]'s `meta` branch is merged.
 
 An integration branch, called `meta-po`, merges [[intrigeri]]'s `po`
 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.
+
+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]] 
+
+> Done in my po branch, preserving backward compatibility. Please
+> review :) --[[intrigeri]]
+
+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
+>> Sure, go here <http://l10n.ikiwiki.info/smiley/smileys/index.sv.html>
+>> (Currently 0% translateed) and see the 'WikiLink' link at the bottom,
+>> which goes to <http://l10n.ikiwiki.info/ikiwiki.cgi?page=ikiwiki/wikilink&from=smiley/smileys&do=create>
+>> Compare with eg, the 100% translated Dansk version, where
+>> the WikiLink link links to the English WikiLink page. --[[Joey]] 

 
 

-All cases of master/slave page creation/deletion/rename, both via RCS
-and via CGI, have been tested.
+Double commits of po files
+--------------------------
+
+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
 -------------
 
 Documentation
 -------------