Extension:Transliterator

An extension to allow transliteration based on ad-hoc schemes stored in the wiki's MediaWiki space (by default under the [ [Mediawiki:Transliterator:]] pseudo-namespace).

Usage on pages
Most people will want to use this

Which will generate the transliteration of based on the map found in [ [MediaWiki:Transliterator:&lt;mapchina>]].

Formatting output
The extension supports several extra parameters to help template-authors integrate this easily into their code. At a basic level, it allows customisation of the output using the third parameter. Will output nothing if there is no page at [ [MediaWiki:Transliterator:&lt;mapname>]], or " " if the map exists. This should allow template-authors to avoid doing some form of {{#if: statement to see whether a transliteration can be created.

User-supplied transliterations
The fourth parameter allows you to set a user-override on the output of a transliteration. This has two uses, one where the transliteration that is generated is incorrect, and two, where the map does not yet exist for a language. Will output if } is not blank. If is blank and [ [MediaWiki:Transliterator:&lt;mapname>]] exists, it will output  as before. And if is blank, and [ [MediaWiki:Transliterator:&lt;mapname>]] does not exist, it will output nothing.

Simple Overview
Every line of the map file should contain a rule like  or , the longer the rule, the higher its priority. The special characters ^ and $ can be used to match only at the start and end of a word, so  or. Most of the time the rules are case-insensitive, so if you include, you don't need to include  , however for multiple-character-rules you may need to duplicate them, i.e.   and   are both needed, as the   provides the automatic rule of. Lines that start with a  are ignored, and the first line can be   to use NFD instead of matching letters. CAVEAT: This assumes a word is one or more Unicode characters, and uses the Unicode case-mappings which may not be perfect for all languages.

Syntax
Blank lines and lines that start with  are ignored. Other lines should be a rule in the form, with the exception of the first one that may contain flags instead of a rule. Whitespace is removed from the beginning and end of lines, and before and after the  symbol, so   is exactly equivalent to.

Transliteration process
Rules are applied one-by-one and the next rule starts matching at the character after the previous rule. The rules are matched in length order, so the longest possible rule is used.
 * If the match starts on the start of a word (the previous character wasn't a letter, but this one is) then the rule  will match, and take priority over.
 * If the match ends at the end of a word (this character is a letter, the next one isn't) then the rule  will match and take priority over.
 * If no match is possible, and the first character is upper-case, then it is converted to lower-case, and the longest applicable rule is used.
 * If no rules have matched, and there is no default rule, then one character is passed through unchanged.

Flags
The first line of a map can contain:
 * Divides strings into sections using the Unicode form NFD instead of the default letter-based form. This is particularly useful for languages such as Korean, or for situations in which the diacritics in the transliterated form match exactly the diacritics in the original. NOTE: the letter form is not quite NFC as combining diacritics are never split from their base even when there is no pre-combined character for them.
 * Divides strings into sections using the Unicode form NFD instead of the default letter-based form. This is particularly useful for languages such as Korean, or for situations in which the diacritics in the transliterated form match exactly the diacritics in the original. NOTE: the letter form is not quite NFC as combining diacritics are never split from their base even when there is no pre-combined character for them.

HTML entities
The right-hand-side and left-hand-side of rules have HTML entities decoded, this allows for diacritics to be entered in a form that is easy to edit, and for the characters that make up the syntax of the maps to be escaped in the rare cases that you will want to use them. As the HTML entities are also decoded by your web-browser, you will not see a difference unless you edit the page. For example, the HTML entities for " ", " ", " " and " " are,  ,   and   (note that the common   is not a normal space).

Possible errors
All of these error messages appear at the place which is invoked. The maps are not parsed when they are saved.


 * Ambiguous rule  in [ [MediaWiki:Transliterator: &lt;mapname>]]
 * This is caused when a map contains two rules with the same content on the left of the =>. This can never be correct, as it would leave the Transliterator to make an impossible decision as to which right-hand-side to replace the left-hand-side with.


 * Invalid syntax  in [ [MediaWiki:Transliterator: &lt;mapname>]]
 * This is caused by a line that contains no "=>" and that does not start with a "#", The parser cannot decide whether you meant it to be a comment, but forgot to say, or whether you meant it to be a rule and got it wrong, so it asks for confirmation.


 * More than  rules in [ [MediaWiki:Transliterator: &lt;mapname>]]
 * In order that this extension doesn't create massive maps that could potentially consume the server's memory, it limits itself in size. The limit in number of rules is configurable as below. There is no real solution to this problem, unless you work out a better set of rules (with some multi-character sequences there are ways of using the longest-first property to leave out some repetitious rules).


 * Rule  has more than   characters on the left in [ [MediaWiki:Transliterator: &lt;mapname>]]
 * Due to the algorithm used to transliterate, having long rules on the left both increases the size of the map, and increases the maximum time that may be taken in transliteration. If you find yourself wanting to break this limit, the chances are that your language cannot be transliterated automatically.

Advanced customisation
The namespace in which maps are put is set by the magic word 'tr_prefix', in English it is 'Transliterator:', but locales may customise this.

The global variable, by default 255, specifies the maximum number of entries in a mapping; while  , by default 10, specifies the maximum length of the left hand side of the rule. These are totally arbitrary limits, and it may be the case that different bounds work better for you. You should set the configuration variables after requiring extensions/Transliterator/Transliterator.php as otherwise they will be overwritten by the defaults.