Транслит - Документация

Автор: Петко Йотов / Author: Petko Yotov 5ko [snail] 5ko [period] fr

1. Включване на библиотеката

Добавя се <script ...> в шаблона (HTML template) на сайта, преди затварящия маркер </head>:

<head>
  <meta http-equiv='Content-Type' content='text/html; charset=utf-8' />
  ...
  <script src="/path/to/translit.utf8.js"></script>
</head>

Сайтът трябва да е с UTF-8 кодиране. Ако не е, трябва заглавките на сървъра (response headers) да укажат, че translit.utf8.js е с UTF-8 кодиране. Примерно в Apache .htaccess:

<Files "translit.utf8.js">
  AddCharset UTF-8 .js
</Files>

Резюме на функционалността (пищов, cheatsheet)

Видове данни	към кирилица	към латиница
Формуляр - автоматично^1,3,4	<input data-translit="tocyr"> (или) <input class="translit-tocyr">	<input data-translit="tolat"> (или) <input class="translit-tolat">
Низ (`String "..."`)	`var cyrString = latString.toCyr();`	`var latString = cyrString.toLat();`
Масив (`Array [...]`)²	`var cyrArray = latArray.toCyr();`	`var latArray = cyrArray.toLat();`
Обект (`Object {...}`)²	`var cyrObject = latObject.toCyr();`	`var latObject = cyrObject.toLat();`
Елемент от формуляр^3,4	`elem.toCyr();`	`elem.toLat();`
Списък възли (`NodeList`)^3,4	`myNodeList.toCyr();`	`myNodeList.toLat();`
Селектор за полета^4,5	`"#myForm input".toCyr(true);`	`"input,textarea".toLat(true);`

1. Веднъж инсталирано, си превежда автоматично, няма нужда от допълнителен код. 2. Само стойностите, също рекурсивни/смесени. 3. Само INPUT, TEXTAREA и само стойностите (.value), други не се пипат. 4. Добавя атрибут "title" с оригиналния текст. 5. Извиква querySelectorAll().

Забележка: Транслитерацията от латиница не различава между някои букви като "А" и "Ъ" или римски цифри, а от кирилица на чуждестранни имена може да не съвпада с името в оригинал. Резултатите непременно трябва да се проверят от потребител и коригират, ако е нужно.

2. Автоматична транлитерация

На полета от формуляр за транслитериране им се довавят атрибути "class" или "data-translit":

За превод към кирилица:

data-translit="tocyr" или
class="translit-tocyr"

За превод към латиница:

data-translit="tolat" или
class="translit-tolat"

Това ще се преведе на латиница: 
    <input name="t1" data-translit="tolat" value="Текст с кирилица"/>    <br/>

Това ще се преведе на кирилица: 
    <textarea name="a1" data-translit="tocyr">Tekst s latinitsa</textarea>

3. Ръчна транлитерация - елементи от формуляр

Ако трябва потребителят да преведе полета с натискане на бутон, може да се направи следното:

  <input type="button" value="Транслитериране" id="translit_btn" />

  <script> // Това може да е и в отделен файл
    document.getElementById('translit_btn').addEventListener('click', function(e){

      // пример: елементи със селектор към кирилица
      '#name,#adres'.toCyr(true);

      // пример: елемент със селектор към латиница
      '#director'.toLat(true); 

      // пример: всички елементи INPUT, TEXTAREA от формуляр с id="myForm":
      '#myForm input, #myForm textarea'.toLat(true);

      // пример: елемент, ръчно
      var el = document.forms[0].streetname;
      el.toLat(); // към латиница
      // или: el.toCyr(); // към кирилица
    });
  </script>

4. Ръчна транлитерация - превод на низове, масиви и обекти

Ръчен превод на низ (String):

var a = "София, бул. Васил Левски";

var b = a.toLat(); // "Sofia, bul. Vasil Levski"

var c = b.toCyr(); // "София, бул. Васил Левски"

Ръчен превод на масив (Array), също рекурсивно:

var a = ["София", "Пловдив", "Варна", "Бургас"];

var b = a.toLat(); // [ "Sofia", "Plovdiv", "Varna", "Burgas" ]

var c = b.toCyr(); // ["София", "Пловдив", "Варна", "Бургас"];

Ръчен превод на обект (Object), също рекурсивно, само стойностите:

var a = {
  name: "Кауфланд София - Крива река",
  street: 'бул. "Генерал Едуард И. Тотлебен" 36',
  postcode: 1606,
  town: "София"
};

var b = a.toLat();
/* { 
    name: "Kaufland Sofia - Kriva reka", 
    street: "bul. \"General Eduard I. Totleben\" 36",
    postcode: 1606, 
    town: "Sofia"   
   }
*/

var c = b.toCyr();
/* { 
    name: "Кауфланд София - Крива река", 
    street: "бул. \"Генерал Едуард И. Тотлебен\" 36", 
    postcode: 1606,
    town: "София"   
   }
*/