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;mapname>]].

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.

Failure to transliterate
The final parameter allows for an "error" message to be displayed instead of a blank output in the two cases above. This can be useful where the transliteration is mission-critical, but should be used sparingly.

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 make the rules case-sensitive or   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 rule with a left-hand side matches, then the default rule, with nothing on the left-hand-side,  is used and any occurrences of $1 in the right-hand-side are replaced by the current first character.
 * 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 either or both of:
 * 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.


 * Turns off the automatic lower-casing for the first letter of each rule with no upper-case match, this can be useful when you have very specific requirements and would rather nothing matched "by accident".
 * Turns off the automatic lower-casing for the first letter of each rule with no upper-case match, this can be useful when you have very specific requirements and would rather nothing matched "by accident".

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.


 * [ [MediaWiki: transliterator-prefix]] must be at least  characters long.
 * If the prefix is too short, then there is a high chance that too many pages in the MediaWiki namespace will consider themselves to be maps. This is bad for performance and usability, so the prefix must be at least 3 (by default) characters long.

Advanced customisation
A synonym for the call can be added by editing [ [MediaWiki:transliterator-invoke]], if you customize this message the original  will still work.

The namespace in which maps are put can be customized. By default it is "Transliterator:", but if you'd prefer a different place, edit [ [MediaWiki:transliterator-prefix]]. It is not possible to move the maps outside of MediaWiki (and the chances are that doing so would be a bad idea anyway). NOTE: if you edit this message, all of your maps will need to be moved - so it is likely that once you have started using the extension you don't want to change it.

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.

For the interested: The absolute maximum size of the lookup table created for each map is bounded by O($wgTransliteratorRuleCount^2 * $wgTransliteratorRuleSize + the size of the map page). The absolute maximum number of operations to transliterate something is O($wgTransliteratorRuleSize * input length). These are worst case and unlikely to appear in practice, particularly as most transliteration schemes deal with individual letters or digraphs.