[[PageOutline(2-5,Contents,pullout)]]

= Content negotiation plugin for Trac wiki

== Description

This plugin provides content negotiation mechanism for Trac wiki pages. With this plugin, your Trac site can provide localized pages for users.

== Bugs/Feature Requests

Existing bugs and feature requests for TracWikiNegotiatorPlugin are 
[report:9?COMPONENT=TracWikiNegotiatorPlugin here].

If you have any issues, create a 
[/newticket?component=TracWikiNegotiatorPlugin new ticket].

[[TicketQuery(component=TracWikiNegotiatorPlugin&group=type,format=progress)]]

== Download

Download the zipped source from [download:tracwikinegotiatorplugin here].

== Source

You can check out TracWikiNegotiatorPlugin from [http://trac-hacks.org/svn/tracwikinegotiatorplugin here] using Subversion, or [source:tracwikinegotiatorplugin browse the source] with Trac.

== Installation

Build the egg file and place it in the plugins directory of your Trac environment.

If you want to install as a system wide plugin:
{{{#!sh
$ python setup.py install
}}}

If you want to build the plugin's egg file and use it in your projects, build the egg file and copy it into the `plugins` directory under the Trac environment directory:
{{{#!sh
$ python setup.py bdist_egg
...
$ cp dist/*.egg /your/trac/project/plugins
}}}

== Configuration

On using this plugin, do not forget the enable the plugin `WikiNegotiator` in `trac.ini` or via `WebAdmin` page:
{{{#!ini
[components]
wikinegotiator.* = enabled
...
[wiki]
default_lang = en
}}}

Note that `TitleIndex` macro and `TOC` macro (by tractoc plugin) is overridden by enabling this plugin. To use original macro, you should
disable the new macro explicitly, see [#BonusMacro Bonus Macro] for more detail.

== Usage

Using the negotiation feature is simply providing suffixed page like 'Foo.ja' for Japanese, 'Foo.fr' for French, so on. When Japanese user
(with Japanese setting in browser) access to the page 'Foo', he will see the content of `Foo.ja` instead of `Foo`. Likewise, French user will see the content of `Foo.fr`. So what you should do is creating localized page content in the usual way. Note that suffix like '.ja' and '.fr' is to be a standard language code.

Non-suffixed page `Foo` is also usable for default content when no suffixed page is matched to user's request.

To see the page for your language, nothing to do to view localized page. To see the page for other language, specify the appropriate suffix for
wiki page name in the url explicitly, or add query parameter like "?lang=xx".

To edit the page, you can edit the page now you are seeing by simply press "Edit" button.
To edit the page for another language, first visit the desired page with a way described above, then press "Edit" button.

== Language Menu

By using this plugin, you can see new language menu bar above the wiki context navigation menu. It displays available languages on this site automatically by finding language suffixes of wiki pages.

'''Note:''' Users who installed earlier version (before r4974) on Trac 0.11 may need enabling `WikiNegotiatorMenuBar` component to display language menu.

You can select language via this menu. Because it is held in the session information, you can run with the language without re-selection.

The selected language are displayed underlined and bolded on the menu. If the specific language content is not availabe, the language item in the menu is greyed out.

There are 5 kind of display styles:

 `simple`::
   Solid menu bar above the wiki context navigation menu.
   This is default style.
 `ctxnav`::
   Like `simple` but displayed on the right of the wiki context menu.
   It looks like a one of the context menu item.
 `button`::
   Button faced selection menu.
 `tab`::
   Tabbed page style of selector.
 `none`::
   Hide language menu.

The style of language menu can be changed by `menu_style` option:
{{{#!ini
[wiki-negotiator]
menu_style = ctxnav
}}}

==  Bonus Macro

For bonus, this plugin contains two new macro: `MultiLangTitleIndex` and `NTOC`.
The former is an alternative macro of `TitleIndex`.
The later is an alternative of `TOC` macro, see [th:wiki:tocmacro tocmacro] in Trac-Hacs for more detail.

And this plugin has the definitions to override original `TitleIndexMacro` and `TOCMacro` automatically. 
'''So you do not need to edit wiki pages to use both two new macros'''.

If you want to disable new feature and use original, disable new macros explicitly in `trac.ini` like this:
{{{#!ini
[components]
wikinegotiator.macros.titleindexmacro = disabled
wikinegotiator.macros.tocmacro = disabled
}}}

=== `MultiLangTitleIndex`

The differences against `TitleIndex` are:
 * Display in one line for variants like: "* !WikiStart (ja, en, other)".
 * List pages in two columns: one is for user's pages, one is for system provided pages. System pages are the pages made by Trac.
   `WikiStart` and `SandBox` are exception by default because it is a page to be edited by user.

It is useful for the site having many localized pages.

'''This feature is automatically enabled''' by overriding `TitleIndexMacro` when this plugin is enabled.

=== `NTOC`

`NTOC` macro delives `TOC` macro, so all the features in `TOC` macro are available except handling lang suffixed pages.
If you specify normal page name without explicit lang suffix (i.e. `WikiStart`), `NTOC` look up localized page for language same to 
parent page the macro is put on. If not exist, look up localized page for preferred langs. If not found, use specified name as is.
So, it is easy to get localized TOC by simply specifying base page names in argument.

`NTOC` also handles wildcard page argument by expanding and removing suffixed pages.

'''This feature is automatically enabled''' by overriding `TOCMacro`  if available when this plugin is enabled.

== Recent Changes

[[ChangeLog(tracwikinegotiatorplugin, 3)]]

== Author/Contributors

'''Author:''' [wiki:gotoh] [[BR]]
'''Maintainer:''' [[Maintainer]] [[BR]]
'''Contributors:'''