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
=====
Markup languages support
------------------------
-[[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:
+[[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
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
----------------------
to an array to support this. (If twere done, twere best done quickly.)
--[[Joey]]
-po files in underlay
---------------------
+> Done in my po branch, preserving backward compatibility. Please
+> review :) --[[intrigeri]]
+
+>> Right, well my immediate concern is that using an array to hold
+>> hash-like pairs is not very clear to the user. It will be displayed
+>> in a confusing way by websetup; dumping a setup file will probably
+>> also cause it to be formatted in a confusing way. And the code
+>> seems to assume that the array length is even, and probably blows
+>> up if it is not.. and the value is marked safe so websetup can be
+>> used to modify it and break that way too. --[[Joey]]
+
+>>> I have added a sanity check for the even array problem. This was
+>>> the easy part.
+>>>
+>>> About the hash-like vs. dump and websetup issue,
+>>> I can think of a few solutions:
+>>>
+>>> - keep the current hash-like pairs and unmark this setting as safe
+>>> for websetup: this does not solve the dump setup issue, though;
+>>> - replace the array of pairs with an array of
+>>> "LANGUAGECODE|LANGUAGENAME" elements, using a pipe or whatever
+>>> separator seems adequate;
+>>> - add support for ordered hashes to `$config`, websetup and
+>>> dumpsetup, using Tie-IxHash or any similar module;
+>>> - replace the array of hash-like pairs with an array of real
+>>> pairs, such as `[ ['de', 'Deutsch'], ['fr', 'Français'] ]`; this
+>>> brings once again the need for `$config` to support arrays of
+>>> arrays, which I have already implemented in my mirrorlist branch
+>>> (see [[todo/mirrorlist_with_per-mirror_usedirs_settings]] for
+>>> details).
+>>>
+>>> Joey, which of these solutions do you prefer? Or another one?
+>>> I tend to prefer the last one. --[[intrigeri]]
+
+>>>> I prefer the pipe separator, I think. I'm concerned that there is
+>>>> no way to really sanely represent complex data structures in web
+>>>> setup. --[[Joey]]
+
+Pagespecs
+---------
-I think this plugin doesn't yet allow po files to be present in an
-underlay to translate files also from the underlay.
+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]]
-In `istranslatablefile`, it specifically checks that
-the file is present in srcdir.
+Edit links on untranslated pages
+--------------------------------
-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.
+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.
-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.
+That's really confusing, especially as clicking such a link
+brings up an edit form to create a new, english page.
-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.
+This is with po_link_to=current or negotiated. With default, it doesn't
+happen..
-So, we seem to have two cases, in one po files from the underlay should be
-used, in the other not. Hmm. Support both?
+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]]
-Duplicate %links ?
-------------------
+> Any simple testcase to reproduce it, please? I've never seen this
+> happen yet. --[[intrigeri]]
-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]]
+>> 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]]
+
+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]]
+
+New pages not translatable
+--------------------------
+
+Today I added a new English page to l10n.ikiwiki.info. When I saved,
+the page did not have the translation links at the top. I waited until
+the po plugin had, in the background, created the po files, and refreshed;
+still did not see the translation links. Only when I touched the page
+source and refreshed did it finally add the translation links.
+I can reproduce this bug in a test site. --[[Joey]]
+
+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
+-------------------------
+
+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".
+
+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.
+
+(We also will need this in order to use translated templates, when they are
+available.)
Documentation
-------------