Extension:LanguageFunctions

From MediaWiki.org
Jump to: navigation, search
MediaWiki extensions manual
Crystal Clear action run.png
LanguageFunctions

Release status: experimental

Implementation Parser extension, Parser function
Description Adds support for filtering multilingual pages by a known set of languages
Author(s) Leo Hourvitz (leovitchtalk)
Latest version 0.1.2 (27Jun2009)
MediaWiki 1.14.0
License Creative Commons Attribution 3.0 United States License
Download Extensions:LanguageFunctions/v0.1.1/
Parameters

$wgLanguageFunctions_LanguageFilters

Hooks used
LanguageGetMagic

SkinBuildSidebar
BeforePageDisplay
GetCacheVaryCookies

Translate the LanguageFunctions extension if it is available at translatewiki.net

Check usage and version matrix; code metrics

What can this extension do?[edit | edit source]

LanguageFunctions is intended to provide language filters on multilingual content. It's most useful in a bilingual or trilingual environment where the languages are largely fixed.

Background[edit | edit source]

To give a specific example, as well as motivate the plug-in, I currently work at a Japanese company where we have a large number of English-speakers on staff. Most of the documentation of our in-house tools needs to be maintained in a bilingual manner. We have both native-English and native-Japanese speaking developers and senior users (both tend to know a little bit of the other language), plus professional in-house translators who usually handle the actual translation of large amount of text. The also tend to handle proofreading text translated by others. The current MediaWiki methods for handling language all tend to be unsatisfactory at our company:

  • We don't want to run more than one wiki
  • Having sub-pages means the English and Japanese documentation is maintained separately (separate revision history, etc.). This causes several problems:
    • When the translations are maintained separately, any sort of structural update of the documentation (i.e., rearranging sections) becomes very difficult. In particular, it cannot be done by a speaker of only one of the languages.
    • Generally the person doing the work (typically updating an in-house tool) speaks only one of the languages. Yet, we want them to update the documentation in their language, and note where the 'other' language needs to be updated (by the translators).
    • Many large, detail-oriented, important, and frequently-updated parts of the documentation are not translated (e.g., a list of plug-ins, license dates, and supported tool versions). Japanese staff in our industry is very used to, and in fact prefer to, deal with English product names. Forcing all documentation onto two pages results in duplications (which necessarily results in out-of-datedness).

Current Practice
現状の方法
[edit | edit source]

To get around this problem currently, we usually write our doc pages bilingually, intermixing English and Japanese text. When a developer updates part of the page, they delete or mark as obsolete the other language, without trying to update it. The translators then fix it in a few days; the only notice from the developer to the translators is, "Update the page at this URL, please". This paragraph shows a typical example.
現状の手続きとは、大体に書類が二言語に書いて英語のテクストも日本語のテクストもパラグラフ毎に混交します。開発者がページの部分を更新する際は、他の言語のテクストは更新しないと削除、または古いように表示させます。数日後、翻訳者がページを追加または修正します。開発者から翻訳者まで伝える内容は、「そのURLであるページを更新した下さい」しか伝えません。そのパラグラフは例として置いておきました。

As you can probably see from the above, this mixed-language mode leads to readability problems on the page. It does have the merits of maintaining a single set of page structure and allowing monolingual developers to update the page, however.

Use Case[edit | edit source]

I wrote LanguageFunctions to allow viewers of our site to control which language information they see. They can choose to view one language, the other, or both at any time.

  • The page content is marked up with parser functions so that the language of each piece of content is known.
  • The current viewing preferences are held in a cookie
  • The language choices are added to the sidebar
  • The set of choosable languages can be controlled via a wgLanguageFunctions_LanguageFilters variable in LocalSettings.php.

Installation[edit | edit source]

  • Download the 3 files found below, and place them in $IP/extensions/ExtensionName. Note: $IP stands for the root directory of your MediaWiki installation, the same directory that holds LocalSettings.php.
  • Add the following lines to your LocalSettings.php:
$wgEnableParserCache = false;
$wgCachePages = false;
require_once( "$IP/extensions/LanguageFunctions/LanguageFunctions.php" );
  • Finally, you'll probably want to customize the editing bar to make it easier on your bilingual editors. See the source code for some sample JavaScript you might want to put in MediaWiki:Common.js.

Usage[edit | edit source]

Once LanguageFunctions is installed you can embed the following parser functions in your content. You will probably only ever use #iflang.

{{#iflang: langCode | content }}
If the user is currently viewing the language given by langCode, the given wiki content will be shown. Otherwise, it will simply not be emitted into the page.
{{#ifmultlang: content}}
If you really want character-accurate generation, you may need this conditional, which will emit the given content if more than one language is currently selected. If no content is given, it default to a space.

The Sidebar: LanguageFunctions will automatically add a "language filters" sidebar to your site. The default one is configured for English and Japanese, but the idea is that you'll override it in your LocalSettings.php. See the LanguageFunctions.php source code for the format.

Performance note: You see above that LanguageFunctions does not work currently with caching. The ParserCache simply doesn't implement cookie-variant content so there's probably not much chance of that changing. I don't know why it doesn't work with client caching; the extension uses the getCacheVaryingCookies hook and I've verified the header is being generated. In practice it doesn't work in my testing though, so I keep $wgCachePages off.

Example Wikitext[edit | edit source]

Here's a very simple example of the kind of wiki text you can write with LanguageFunctions.

Here's some non-translated text that will show no matter what language setting is used.
 
{{#iflang: ja |
日本語の秘密だ! 
}}
{{#iflang: en | 
Secret stuff for english speakers 
}}
 
Here's a bilingual header.
 
=={{#iflang: en |English heading }}{{#ifmultlang: }}{{#iflang: ja |日本語のヘッディング }}==

Alternative Implementations[edit | edit source]

If you know of better ways to realize this functionality without an extensions, please let me know. I'm just trying to help improve our in-house procedures. In particular, I tend to agree with the comments on the mailing list that Wikitext is hardly the best macro language around. However, none of the folks who deal with maintaining our documentation would want to be doing this in Lua; this problem really does IMHO need a lighter-weight solution.

Code[edit | edit source]

The project is currently hosted at ActiveState's beta Workspace site:

svn checkout https://workspace.activestate.com/svn/mwlanguagefunctions mwlanguagefunctions

The main code (not including images for the edit bar) is also here (be sure to follow the links, do not copy use right mouse klick!):

Extension:LanguageFunctions/v0.1.2/LanguageFunctions.php
Extension:LanguageFunctions/v0.1.1/LanguageFunctions.i18n.php
Extension:LanguageFunctions/v0.1.1/LanguageFunctions.i18n.magic.php