Content negotiation plugin for Trac wiki

Description

This plugin provides a 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 here.

If you have any issues, create a new ticket.

defect	4 / 4
enhancement	4 / 7

Download

Download the zipped source from here.

Source

You can check out TracWikiNegotiatorPlugin from here using Subversion, or 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:

$ 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:

$ 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:

[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 the original macro, you should disable the new macro explicitly, see Bonus Macro for more detail.

Usage

Using the negotiation feature is simply providing a suffixed page like 'Foo.ja' for Japanese, 'Foo.fr' for French, and so on. When a Japanese user with the Japanese setting in the browser accesses the page 'Foo', (s)he will see the content of Foo.ja instead of Foo. Likewise, a 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 a suffix like '.ja' and '.fr' needs to be a ​standard language code.

The non-suffixed page Foo is also usable for default content when no suffixed page is matched to the user's request.

To see the page for your language, there is nothing to do to view the 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 in the way described above, then press the "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 the WikiNegotiatorMenuBar component to display the language menu. You can select the language via this menu. Because it is held in the session information, you can run with the language without re-selection.

The selected languages 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 kinds 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 one of the context menu items.

button

Button faced selection menu.

tab

Tabbed page style of selector.

none

Hide language menu.

The style of the language menu can be changed through the menu_style option:

[wiki-negotiator]
menu_style = ctxnav

Bonus Macro

For bonus, this plugin contains two new macros: MultiLangTitleIndex and NTOC.

• The former is an alternative macro of TitleIndex.
• The latter is an alternative of the TOC macro, see tocmacro for more detail.

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

If you want to disable these new features and use the original instead, disable the new macros explicitly in trac.ini like this:

[components]
wikinegotiator.macros.titleindexmacro = disabled
wikinegotiator.macros.tocmacro = disabled

MultiLangTitleIndex

The differences with 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 generated by Trac. WikiStart and SandBox are exception by default, because it is a page to be edited by the user.

It is useful for a site that has 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

10723 by gotoh on 2011-10-03 11:26:54

Refresh existing languages on adding/deleting/renaming page.

10722 by gotoh on 2011-10-03 11:26:45

Do not remember temporary lang.

10718 by gotoh on 2011-10-03 09:19:52

Ignore invalid lang value for security reason.

We should reject lang value which does not have expected format ("xx"
or "xx-yy").

(more)

Author/Contributors

Author: gotoh
Maintainer: Shun-ichi Goto
Contributors: