po plugin: documentation work

Signed-off-by: intrigeri <intrigeri@boum.org>
master
intrigeri 2008-10-15 02:42:08 +02:00
parent 6add615928
commit f42cf38076
1 changed files with 32 additions and 38 deletions

View File

@ -12,9 +12,9 @@ Introduction
A language is chosen as the "master" one, and any other supported
language is a "slave" one.
A page written in the "master" language is a "master" page, and is
written in any supported format but PO. It does not have to be named
a special way: migration from/to this plugin does not imply heavy
A page written in the "master" language is a "master" page. It can be
of any page type supported by ikiwiki, but PO. It does not have to be
named a special way: migration to this plugin does not imply any page
renaming work.
Example: `bla/page.mdwn` is a "master" Markdown page written in
@ -33,7 +33,10 @@ rendered as `bla/page/index.fr.html`, else as `bla/page.fr.html`
Configuration
=============
`po_master_language` is used to set the master language in
Supported languages
-------------------
`po_master_language` is used to set the "master" language in
`ikiwiki.setup`, such as:
po_master_language => { 'code' => 'en', 'name' => 'English' }
@ -53,23 +56,32 @@ The `po_translatable_pages` setting configures what pages are
translatable. It is a [[ikiwiki/PageSpec]], so you have lots of
control over what kind of pages are translatable.
The `*.LL.po` translations files are anyway not considered as being
translatable, so you don't need to worry about excluding them manually
from this [[ikiwiki/PageSpec]].
The PO translations files are anyway not considered as being
translatable, so you don't need to worry about excluding them
explicitly from this [[ikiwiki/PageSpec]].
Internal links
--------------
One can use the `po_link_to_` option in `ikiwiki.setup` to choose how
The `po_link_to` option in `ikiwiki.setup` is used to decide how
internal links should be generated, depending on web server features
and site-specific preferences.
### Default linking behavior
If `po_link_to` is unset, or set to `default`, ikiwiki's default
linking behavior is preserved: `\[[page]]` links to the master
linking behavior is preserved: `\[[destpage]]` links to the master
language's page.
### Link to current language
If `po_link_to` is set to `current`, `\[[destpage]]` links to the
`destpage`'s version written in the current page's language, if
available, *i.e.*:
- `foo/destpage/index.LL.html` if `usedirs` is enabled
- `foo/destpage.LL.html` if `usedirs` is disabled
### Link to negotiated language
If `po_link_to` is set to `negotiated`, `\[[page]]` links to the
@ -77,20 +89,11 @@ negotiated preferred language, *i.e.* `foo/page/`.
(In)compatibility notes:
- `po_link_to => negotiated` provides no useful behavior if `usedirs`
is disabled; this option combination is neither implemented nor
allowed
- `po_link_to => negotiated` provides no useful behavior if the web
server does not support Content Negotiation
### Link to current language
If `po_link_to` is set to `current` and the destination page is either
a translatable page or a translation, `\[[page]]` links to the current
page's language, *i.e.*:
- `foo/page/index.LL.html` if `usedirs` is enabled
- `foo/page.LL.html` if `usedirs` is disabled
- if `usedirs` is disabled, it does not make sense to set `po_link_to`
to `negotiated`; this option combination is neither implemented
nor allowed.
- if the web server does not support Content Negotiation, setting
`po_link_to` to `negotiated` will produce a unusable website.
Server support
@ -99,17 +102,16 @@ Server support
Apache
------
Using `mod_negotiation` makes it really easy to have Apache serve the
page in the client's preferred language, if available. This is the
default Debian Apache configuration.
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.
When `usedirs` is enabled, one has to set `DirectoryIndex index` for
the wiki context.
Setting `DefaultLanguage LL` (replace `LL` with your default MIME
language) for the wiki context can be needed, to ensure
language code) for the wiki context can help to ensure
`bla/page/index.en.html` is served as `Content-Language: LL`.
**FIXME**: is it still needed with the new `.en.html` naming convention?
lighttpd
--------
@ -205,19 +207,11 @@ has just been declared as being translatable:
checked more thoroughly to prevent any security issue (command
injection, etc.).
UI consistency: rename "Edit" button on slave pages
---------------------------------------------------
It may be surprising to some, after having pressed *Edit* on a wiki
page, to end up editing a strange looking PO file. The *Edit* button
displayed on "slave" pages must therefore be renamed *Improve
translation* .
Translation quality assurance
-----------------------------
Modifying a PO file via the CGI must only be allowed if the new
version is a valid PO file. As a bonus, check that it provides a more
Modifying a PO file via the CGI must be forbidden if the new version
is not a valid PO file. As a bonus, check that it provides a more
complete translation than the existing one.
A new `cansave` type of hook would be needed to implement this.