Custom Plugins

This walkthrough describes how to implement a custom transliteration plugin which can be used by Bitig. The instructions may be updated because there are still some features to be added to the base library.

To implement a custom plugin, you should inherit from the abstract TranslitCommand class in BitigBase.dll and override some of its methods. The base library can be found in the executable folder.

As an example, we'll implement a plugin which transliterates a Yanalif text into Zamanalif.

Step 1. Derive a class from the TranslitCommand class.

public class YanalifZamanalif : Bitig.Base.TranslitCommand
{
}

Step 2. Choose methods and properties to override.
The base TranslitCommand class proposes two transliteration strategies.
The first is to override the Transliterate method:

public virtual string Transliterate(string Text)

All you have to do here is to take the Text parameter, convert it into the desirable form, and return the transliterated text back. This gives you the entire control over the transliteration process. However, some useful mechanisms are already implemented in the base class, such as search for exclusions and text parsing. The second strategy uses these handy techniques.
Note: exlusions are words or parts of words that should not be processed by the transliteration algorithm. Instead, they are replaced with some predefined strings.

The second strategy is to transliterate on a word-by-word basis. Here, you rely on the base parsing mechanism and need to specify the parsing patterns.
First, you set the AlphabeticPattern and TranslitPattern properties. Note that you should set the AlphabeticPattern first because it resets the TranslitPattern. AlphabeticPattern includes all symbols that are considered to be the letters of the source alphabet (in our example, the Yanalif alphabet). The pattern is used by the base class to construct a regular expression.

AlphabeticPattern = "'’A-Za-zƏəİıƟɵÜüÇ窺\ua790\ua791";

TranslitPattern specifies which symbols actually need to be transliterated (replaced with other symbols). In our example, these will be letters that differ in Yanalif and Zamanalif (the target alphabet).

TranslitPattern = "’ƏəIıYyƟɵ\ua790\ua791";

Next, override the TranslitWord method.

protected override string TranslitWord(string Word)
        {
            StringBuilder _zamanalifBuilder = new StringBuilder();
            for (int i = 0; i < Word.Length; i++)
            {
                char _yanalifLetter = Word[i];
                if (i + 1 < Word.Length && (_yanalifLetter == 'I' || _yanalifLetter == 'ı') && (Word[i + 1] == 'Y' || Word[i + 1] == 'y'))
                {
                    //replace ıy with í
                    if (_yanalifLetter == 'I') _zamanalifBuilder.Append('Í');
                    else _zamanalifBuilder.Append('í');
                    i++; //skip next letter (y)
                }
                else
                {
                    if (translitTable.ContainsKey(_yanalifLetter)) _zamanalifBuilder.Append(translitTable[_yanalifLetter]);
                    else _zamanalifBuilder.Append(_yanalifLetter);
                }
            }
            return _zamanalifBuilder.ToString();
        }

TranslitTable is a dictionary that defines which letters replace source letters.

translitTable = new Dictionary<char, char>();
            translitTable.Add('Ə', 'Ä');
            translitTable.Add('ə', 'ä');
            translitTable.Add('\ua790', 'Ñ');
            translitTable.Add('\ua791', 'ñ');
            translitTable.Add('Ɵ', 'Ö');
            translitTable.Add('ɵ', 'ö');
            translitTable.Add('’', '\'');

Note that we don't care about exclusions here, because they are handled by the basic implementation of the Transliterate method in the TranslitCommand class. You will only have to override the ExclusionsDictionary property and fill it with values or leave empty. The implementation of the ExclusionsDictionary property may be modified soon.

If you need a greater control over how a word is processed or searched for an exclusion, you may override the TranslitOrFindExclusion method instead of TranslitWord. TranslitOrFindExclusion only gets called when the AlphabeticPattern and TranslitPattern are the same (that is, when all symbols of the source alphabet are to be replaced with other symbols, such as when transliterating from the Cyrillic or Arabic alphabet into a Latin-based one). We use this technique in such classes as CyrillicYanalif or CyrillicRasmalif, since they employ a slightly different exclusion search. By the way, we have some handy methods dealing with exclusions in the TranslitHelper class, such as FindExclusionsInWord or FindExclusionsInText. Also, you can use this helper class to convert a Cyrillic word into a phonetic transcription.

There is one more aspect we should mention. As you may know, some alphabets have non-standard upper/lower symbol pairs. For instance, Yanalif uses İ as the upper i (whereas in language-neutral Unicode, the upper for i is I). Furthermore, some platforms can be unaware of symbols pairs newly introduced to Unicode, such as the 'N with descender' character. If your source or target alphabet includes such pairs, you should specify them by setting the CustomSourceUpLowPairs and CustomTargetUpLowPairs, respectively. By doing this, you enable the exclusion search to ignore the case of the word.

Step 3. Compile and build your library.
Our example library is called CustomYanalifZamanalif.

Step 4. ConfigureBitig to use your library.
Open Bitig, go to the Settings menu, and select Configuration.

On the Configuration form, go to the Directions tab. Click the New button; or, if you want to override an existing transliteration direction, choose that direction and click Edit.

Choose source and target alphabets. (If the alphabets you need do not exist yet, first you have to add them from the Alphabets tab on the Configuration form.) Then select Browse in the Library combo and browse for your assembly.

Once the library is chosen, the program will try to fill the Type Name combo with types derived from TranslitCommand. If for some reason it fails to find your type, type its name, including the namespace, into the Type Name combo. Click OK. Click OK on the Configuration form, too.

Now, if you choose the Yanalif - Zamanalif transliteration direction on the main form and click the Transliterate button, Bitig will use your plugin to transliterate the text.