- po_slave_languages => { 'fr' => { 'name' => 'Français', },
- 'es' => { 'name' => 'Castellano', },
- 'de' => { 'name' => 'Deutsch', },
- },
+ po_slave_languages => { 'fr' => 'Français',
+ 'es' => 'Castellano',
+ 'de' => 'Deutsch',
+ }
+
+Decide which pages are translatable
+-----------------------------------
+
+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 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
+--------------
+
+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: `\[[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
+negotiated preferred language, *i.e.* `foo/page/`.
+
+(In)compatibility notes:
+
+- 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.