# Трансліт — імена й назви українською

> Транслітерація японських, китайських, корейських і західних імен та назв українською мовою: сайт https://trans.mikai.me, публічний API без ключа й реєстрації та телеграм-бот. Це не перекладач: текст не перекладається, а передається українськими літерами за правилами конкретної системи. Зворотного напрямку (з української) немає.

## Мови та системи

Кожна мова має основну систему; у трьох із чотирьох є друга, необовʼязкова — вона вмикається параметром `system` в API і окремою адресою на сайті.

- `ja` японська — основна «Система Коваленка»; друга `system=gojuon` («Система Ґоджюон», семінар КНУ 2011). Приймає ромаджі (Гепберн) або кану: `Gojou Satoru`, `しんいち`, `ロロノア・ゾロ`.
- `zh` китайська — основна «Система Кірносової–Цісар (УКТ)», з дж і дз замість палладієвих цз і чж; друга `system=academic` («Академічна система 2019» НАН: цзі, чжа, -ун). Приймає піньїнь: `Xie Wanqian`.
- `ko` корейська — основна «Система Hikka» (читає слово так, як воно звучить: одзвінчення, нейтралізація кінцевих, перенесення складу); друга `system=shchegel` («Система Щегеля», склад за складом). Приймає ханґиль: `박 은지`.
- `en` західні — «Український правопис 2019, §§ 122–137» (h → г, g → ґ, і замість и). Приймає латинку: `Harrison Ford`. Другої системи немає, параметр `system` для неї — помилка.

Усталені й неанглійські написання (Бетговен, Хосе, Мюллер) правила не знають — їх треба звіряти вручну.

## Режим імені

Параметр `mode` каже, чи читати рядок як особове імʼя: `name` — перше слово прізвище, решта імʼя, з правилами групи; `text` — ніколи не як імʼя; типово `auto`, коли вирішує форма слова. Які системи це вміють, видно з поля `nameMode` у `/translit/systems`. На сайті це перемикач «Це імʼя та прізвище», увімкнений типово.

## API

Без ключа й реєстрації, CORS відкритий. Відповідь — JSON у конверті `{ "ok": true, "result": … }`; помилка — `{ "ok": false, … }` зі статусом 422 і кодом.

- `GET https://api.mikai.me/public/v1/translit?lang=ja&text=Gojou+Satoru` — параметри `lang` (обовʼязковий: ja, zh, ko, en; приймаються й аліаси jp, cn, kr), `text` (або `q`), `system`, `mode`.
- `POST https://api.mikai.me/public/v1/translit` — те саме тіло у JSON: `lang`, `system`, `mode` і `text` з переносами рядків або масив `items`. Максимум 32 КБ тексту на запит.
- `GET https://api.mikai.me/public/v1/translit/systems` — усі системи як дані: правила з прикладами, типові русифіковані варіанти, обмеження, джерела, зразки тексту, вкладена `alt`. Саме з цієї відповіді зібрані сторінки сайту.

`result` транслітерації: `lang`, `system` (назва системи, яка читала), `text` (увесь результат) і `lines` — по рядку на рядок вхідного тексту з полями `source`, `result`, `unresolved` (слова, які система не змогла прочитати — вони повертаються без змін), `from: "catalog"` і `rules`, коли відповідь узята з каталогу mikai, а не з правил. Якщо текст насправді належить іншій мові, зʼявляється `suggest` із її кодом, назвою системи та готовим читанням.

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

### Ліміти

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

## Сторінки

- [Японська](https://trans.mikai.me/) — і [Система Ґоджюон](https://trans.mikai.me/?system=gojuon)
- [Китайська](https://trans.mikai.me/chinese) — і [Академічна система 2019](https://trans.mikai.me/chinese?system=academic)
- [Корейська](https://trans.mikai.me/korean) — і [Система Щегеля](https://trans.mikai.me/korean?system=shchegel)
- [Англійська та західні](https://trans.mikai.me/english)
- [Сторінка API](https://trans.mikai.me/api)

На кожній сторінці — сам транслітератор (читає, поки пишете), перемикач систем, режим імені, а під ним правила системи з прикладами, типові хибні варіанти й посилання на джерела.

## Телеграм

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

## Docs

- [Повний опис API (Markdown)](https://trans.mikai.me/api.md)
- [Документація публічного API mikai](https://api.mikai.me/public/docs#translit)
- [llms.txt публічного API mikai](https://api.mikai.me/public/llms.txt)