# Трансліт — API транслітерації

Українська транслітерація імен і назв: японська за системою Коваленка, китайська за Кірносовою–Цісар, корейська за системою Hikka, західні — за правописом 2019. Без ключа, без реєстрації.

База: `https://api.mikai.me/public/v1`

## Запит

Ключ і реєстрація не потрібні. Ендпоінт читальний, відповідь — JSON у конверті `{ "ok": true, "result": … }`. Один рядок тексту — один рядок відповіді; розділові знаки, порожні рядки й порядок слів зберігаються.

```
curl "https://api.mikai.me/public/v1/translit?lang=ja&text=Gojou%20Satoru"
```

```
{
  "ok": true,
  "result": {
    "lang": "ja",
    "system": "Система Коваленка",
    "text": "Ґоджьо Сатору",
    "lines": [
      { "source": "Gojou Satoru", "result": "Ґоджьо Сатору" }
    ]
  }
}
```

## Мови

| lang | Система і що приймає |
| --- | --- |
| ja | Система Коваленка — ромаджі (Гепберн) або кана: Gojou, ゾロ |
| zh | Система Кірносової–Цісар — піньїнь: Xie Wanqian |
| ko | Система Hikka — ханґиль: 박 은지 |
| en | Український правопис 2019 — латинка: Harrison Ford |

Слово, яке система не може прочитати (ієрогліфи, латинка в корейському режимі), повертається без змін і перелічується в `unresolved` відповідного рядка.

Для китайської є другий, необовʼязковий варіант — `system=academic`: академічна система, затверджена НАН 2019 року (цзі, чжа, -ун). Типово працює `system=ukt`, тобто Кірносової–Цісар, як вимагають правила Hikka.

Для корейської друга система — `system=shchegel`: академічна система Щегеля, яка читає кожен склад окремо. Типово працює `system=hikka`, «Корейсько-українська система транслітерації», написана для Hikka: вона читає слово так, як воно звучить (одзвінчення, нейтралізація кінцевих, перенесення складу).

Для японської друга система — `system=gojuon`: система, ухвалена 2011 року на семінарі японістів Київського університету. Вона читає склади так само, як типова `system=kovalenko`; різниця лише в голосній на межі складів. Для західних імен параметр `system` не діє.

Рядок можна прочитати як особове імʼя: `mode=name` бере перше слово за прізвище, решту — за імʼя, і застосовує правила групи (`mode=text` навпаки, ніколи не читає слово як імʼя). Типово `auto`. Які системи це вміють, видно з поля `nameMode` у `/translit/systems`.

```
curl "https://api.mikai.me/public/v1/translit?lang=ko&text=%EB%B0%95%20%EC%9D%80%EC%A7%80&mode=name"                    # → Пак Инджі
curl "https://api.mikai.me/public/v1/translit?lang=ko&text=%EB%B0%95%20%EC%9D%80%EC%A7%80&system=shchegel&mode=name"  # система Щегеля
```

```
curl "https://api.mikai.me/public/v1/translit?lang=zh&text=Mao%20Zedong"            # → Мао Дзедон
curl "https://api.mikai.me/public/v1/translit?lang=zh&system=academic&text=Mao%20Zedong" # → Мао Цзедун
```

## Список

Той самий ендпоінт приймає POST: `text` з переносами рядків або масив `items`. Максимум — 32 КБ тексту на запит.

```
curl -X POST "https://api.mikai.me/public/v1/translit" \
  -H "Content-Type: application/json" \
  -d '{"lang":"zh","items":["Xie Wanqian","Mao Zedong"]}'
```

## Правила та джерела

Правила, приклади, типові русифіковані варіанти й посилання на джерела віддаються як дані — саме з них зібрана головна сторінка.

```
curl "https://api.mikai.me/public/v1/translit/systems"
```

## Телеграм-бот

Той самий транслітератор живе в [@translitua_bot](https://t.me/translitua_bot): надішліть текст — отримаєте читання, яке копіюється одним дотиком, і кнопки, щоб перечитати іншою мовою. Кану й ханґиль бот упізнає сам.

## Ліміти й стабільність

Без ключа — 60 запитів за хвилину з IP; ключ mikai.me підіймає ліміт до 300. Відповіді не кешуються: виправлене читання діє одразу для всіх. Нові поля можуть додаватися будь-коли, тож ігноруйте незнайомі; видалення чи зміна типу — тільки в новій версії шляху.

Транслітерація може уточнюватися: ми виправляємо її в одному місці, і виправлення одразу діє і на сайті, і в API. Якщо помітили хибне читання — напишіть нам.