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.
 * Only if a match is possible, then an attempt is made to extend the match using the positional characters. If the word boundaries fall in the correct places, the rules,   and   are attempted, in that order, before using the plain   rule.
 * If no match is possible, and the first untransliterated character is upper-case, then it is converted to lower-case, and the process starts again.
 * If a match is still not possible 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 match is possible and the default rule does not exist, then one character is passed through unchanged.

Positional characters (^ and $)
The characters  (when it is the first character of a rule) and   (when it is the last character of a rule) are treated as special characters. They match the gap between a word and the surrounding space or punctuation (imagine them pointing to the imaginary line between two characters). A  is inserted when the character before its position is not a letter, nor a combining diacritic but the character succeeding it is, a   is inserted when the character preceding its position is a letter or a combining diacritic, and the character succeeding it isn't. In both cases, the first character of the string is assumed to be preceded by whitespace, and the last character of the string to be succeeded by whitespace. It is important to note that the positional rules are only attempted if the non-positional rule exists.

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.

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.