# Merajut Indonesia Auto Transliteration SDK v1.2.0

Plugin **transliterasi Latin ke aksara Nusantara** untuk seluruh teks tampak pada website (DOM). Tidak mengubah konten database; konten asli disimpan hanya dalam memori halaman untuk memungkinkan kembali ke Latin. Aturan transliterasi dan Unicode dikemas dari sumber `assets/js/transliteration/` Merajut Indonesia; tidak mengunduh JSON dan tidak memerlukan MySQL, API, atau CodeIgniter pada website integrator.

> **Bukan penerjemah bahasa**, dan hasil transliterasi bersifat praktis/edukatif. Konversi terutama untuk teks bahasa Indonesia, tidak menjamin akurasi seluruh kata atau tata tulis sembilan aksara. Tinjau hasil untuk publikasi resmi. Font Unicode spesifik aksara mungkin dibutuhkan agar glyph tampil.

## Instalasi di server Merajut Indonesia

1. Upload file `patch-merajut-auto-sdk-v1.php` ke folder **public_html** Merajut Indonesia, sejajar `index.php`.
2. Buka `https://DOMAIN-MERAJUT/patch-merajut-auto-sdk-v1.php` dan masukkan `PATCH_ACCESS_KEY` yang ada di file PHP. Lihat pratinjau lalu klik **Pasang SDK**.
3. Setelah berhasil, buka `https://DOMAIN-MERAJUT/sdk/v3/dokumentasi.html` atau `https://DOMAIN-MERAJUT/sdk/v3/examples/demo.html`.
4. Hapus `patch-merajut-auto-sdk-v1.php` dari `public_html` setelah pemasangan.

CLI: `php patch-merajut-auto-sdk-v1.php --preview` lalu `php patch-merajut-auto-sdk-v1.php --install`. File SDK lama di `/sdk/v1` dan `/sdk/v2` tidak disentuh. Saat upgrade berkas SDK v3 yang sudah ada akan dicadangkan di `../merajut-auto-backups/` (di luar webroot).

## 1. Satu aksara (switch Latin / Lontara Bugis)

Taruh **sebelum tag `</body>`** pada setiap halaman website integrator:

```html
<script src="https://DOMAIN-MERAJUT/sdk/v3/merajut-auto-transliteration.js?v=1.0.0"
        data-scripts="bugis"
        data-default="latin"
        data-position="bottom-right"
        data-switcher="true"
        data-persist="true"></script>
```

Nama tampilan "Lontara Bugis", tetapi ID teknis tetap `bugis`. Nama tampilan "Arab Nusantara", dengan ID `pegon`.

## 2. Beberapa aksara

```html
<script src="https://DOMAIN-MERAJUT/sdk/v3/merajut-auto-transliteration.js?v=1.0.0"
        data-scripts="jawa,bali,pegon,bugis"
        data-position="top-left"
        data-default="latin" data-persist="true"></script>
```

Seluruh sembilan aksara: `data-scripts="all"`. Jika `data-scripts` tidak diisi, default-nya `all`.

## 3. Empat posisi otomatis

| `data-position` | Posisi |
| --- | --- |
| `bottom-right` (default) | Kanan bawah |
| `bottom-left` | Kiri bawah |
| `top-right` | Kanan atas |
| `top-left` | Kiri atas |
| `custom` | Tombol developer |

`data-offset="24"` mengatur jarak dari tepi viewport dalam piksel (0–100). `data-z-index="2147483000"` mengatur tumpukan UI.

## 4. Tombol sendiri (custom)

### Custom single: klik untuk toggle Latin/Bali

```html
<button type="button" id="aksara-switch">Alih aksara</button>
<script src="https://DOMAIN-MERAJUT/sdk/v3/merajut-auto-transliteration.js?v=1.0.0"
        data-scripts="bali" data-position="custom" data-target="#aksara-switch"
        data-persist="true"></script>
```

Satu aksara default-nya `data-custom-behavior="toggle"`. Tombol developer tidak dimodifikasi gaya atau teksnya.

### Custom multi: klik untuk membuka menu aksara

```html
<button type="button" id="pilihan-aksara">Pilih aksara</button>
<script src="https://DOMAIN-MERAJUT/sdk/v3/merajut-auto-transliteration.js?v=1.0.0"
        data-scripts="jawa,sunda,bali" data-position="custom"
        data-target="#pilihan-aksara" data-custom-behavior="menu"></script>
```

`data-custom-behavior` juga mendukung `cycle` (berputar Latin → Jawa → Sunda → ...). Untuk hanya API (tanpa tombol), pakai `data-switcher="false"` dan tangani UI sendiri.

## 5. JavaScript API (headless)

```html
<script src="https://DOMAIN-MERAJUT/sdk/v3/merajut-auto-transliteration.js?v=1.0.0"
        data-scripts="jawa,bali" data-switcher="false" data-persist="true"></script>
<script>
  MerajutAutoTransliteration.ready.then(() => {
    MerajutAutoTransliteration.setScript('jawa');
    console.log(MerajutAutoTransliteration.getScript());
  });
  document.addEventListener('merajut:scriptchange', event => {
    console.log('Pengunjung memilih', event.detail.script);
  });
</script>
```

| API | Fungsi |
| --- | --- |
| `ready` | Promise yang selesai setelah elemen DOM diinisialisasi |
| `scripts` | Daftar ID aksara yang boleh dipilih, termasuk `latin` |
| `getScript()` | ID aksara aktif |
| `getAvailableScripts()` | Semua ID aksara yang diizinkan pada website |
| `setScript('jawa')` | Ganti aksara; `false` bila ID tidak diizinkan |
| `toggle()` | Latin ↔ aksara pertama yang diizinkan |
| `cycle()` | Bergantian Latin dan aksara lain |
| `openMenu()` / `closeMenu()` | Kontrol UI pilihan aksara |
| `convert(text, 'bali')` | Transliterasi sebuah teks tanpa mengubah DOM |
| `refresh()` | Proses ulang DOM (misal setelah render framework) |
| `destroy()` | Lepas observer dan kembalikan teks ke Latin |

Event DOM: `merajut:ready`, `merajut:scriptchange`.

## 6. Preferensi pengguna (refresh)

`data-persist="true"` (default) menyimpan ID aksara terpilih di **localStorage** dengan key `merajut:auto-script:v1`. Setelah refresh / pindah halaman pada domain yang sama, preferensi dibaca kembali. Bukan cookie HTTP; tidak dikirim ke server. Jika storage diblokir browser, konversi tetap bekerja tetapi preferensi mungkin tidak tersimpan. Browser atau domain berbeda tidak saling membagikan data. Gunakan `data-storage-key="nama-khusus"` jika ada beberapa konfigurasi berbeda pada situs yang sama.

`data-default="latin"` menetapkan nilai awal jika tidak ada preferensi, atau gunakan `data-default="jawa" data-persist="false" data-switcher="false"` untuk selalu menampilkan aksara Jawa tanpa UI.

## 7. Area yang tidak boleh ditransliterasi

```html
<strong data-merajut-ignore>Nama merek tetap Latin</strong>
<section class="merajut-no-transliterate">Nomor rekening & nama aplikasi</section>
<p translate="no">Token teknis tidak diubah</p>
```

Secara otomatis plugin juga mengabaikan `script`, `style`, `noscript`, `template`, `code`, `pre`, `kbd`, `samp`, `textarea`, `input`, `select`, `option`, `svg`, `math`, `iframe`, `canvas`, dan elemen `contenteditable`. URL, email, dan singkatan kapital seperti PANDI dipertahankan sebisa mungkin. **Ganti ke aksara tanpa mengubah nilai input formulir, tautan, atribut HTML, atau meta SEO.** Jika konten berubah via AJAX/React/Vue, `MutationObserver` akan melakukan transliterasi teks baru (pada halaman besar, pertimbangkan pembatasan area).

Atur cakupan: `data-root="#konten-utama"` untuk hanya memproses wilayah tersebut, bukan seluruh `body`.

## 8. Batasan dan deployment

- Ini transliterasi **teks Latin ke aksara**, bukan terjemahan atau romanisasi sempurna. Profil Bugis dan Makassar tidak dapat mewakili semua konsonan akhir. Pengguna perlu meninjau hasil.
- Entri teks baru saat berada pada mode aksara diasumsikan teks sumber Latin; jika aplikasi pihak ketiga memasukkan aksara langsung pada elemen yang sama, tambahkan `data-merajut-ignore`.
- Agar font tampil konsisten, integrator dapat memasang font Unicode yang mencakup aksara terkait. Untuk Arab Nusantara, perhatikan RTL pada kontainer yang sesuai; SDK **tidak** mengubah arah seluruh halaman.
- Untuk website dengan CSP, izinkan asal JavaScript di `script-src`, dan tinjau aturan `style-src` untuk UI shadow DOM. SDK tidak membuat panggilan jaringan tambahan.
- Jalankan satu instans SDK per halaman. Jika instalasi memakai cache/CDN, ubah query versi setelah memperbarui asset.
- Pada pemuatan pertama browser dapat menampilkan Latin secara singkat sebelum skrip selesai; pasang skrip di `<head>` menggunakan `defer` untuk memperkecil jeda. Mode tanpa kilatan (`flash-free`) belum diimplementasikan pada v1.0.

## Pembaruan v1.2.0: Salin kode, Arab Nusantara, dan font

- Label `pegon` tetap **Arab Nusantara**, identifier teknis tetap `pegon`.
- Latin ke Arab Nusantara menggunakan aproksimasi **Jawi/Arab gundul tanpa harakat**. Contoh: `Selamat datang` menjadi `سلامت داتڠ`. Hasil ini tidak menjamin ketepatan ejaan Jawi setiap kata.
- SDK secara otomatis menerapkan font Unicode yang telah tersedia di server Merajut Indonesia untuk Makassar, Bugis, Batak, Rejang, Kawi, dan Arab Nusantara. Font Jawa, Bali dan Sunda menggunakan layanan Google Fonts jika jaringan dan CSP mengizinkan.
- Font yang dimuat dari server Merajut ke website lain memerlukan CORS. Patch ini mengatur CORS pada direktori font di Apache/cPanel jika mod_headers tersedia.
- Developer dapat mematikan pemuatan font otomatis dengan `data-fonts="false"` apabila telah menyediakan font sendiri.
- Gunakan URL `merajut-auto-transliteration.js?v=1.2.0` untuk menghindari cache browser lama.
- Halaman Developer/Transliterasi sudah memiliki metode salin kode cadangan untuk browser yang memblokir Clipboard API.