Ringkasan Proyek

DAFTAR API LOKAL INDONESIA adalah kumpulan API tentang data dan informasi di Indonesia (README.md:3-5¹). Berkas README versi Inggris menyebut dirinya sebagai terjemahan dari berkas asli Bahasa Indonesia (README.en.md:3-7²). Isi repository karena itu bukan aplikasi yang dijalankan, melainkan katalog API yang disimpan sebagai berkas JSON per kategori, lalu dirender menjadi satu README untuk tiap bahasa. Tidak ada server yang hidup terus; seluruh proses berjalan sebagai skrip Bun sekali jalan.

Dua berkas hasil render

Setiap bahasa punya satu README dengan judul H1 sendiri. Keduanya memakai penanda yang sama sebagai titik sisip: daftar isi di antara TOC START dan TOC END, serta tabel API di antara API START dan API END (README.md:13-42³).

Baris pertama tabel disandarkan pada penanda API START yang langsung diikuti ### Agama Islam (README.md:44-48⁴); baris kedua pada penanda yang sama di berkas Inggris (README.en.md:46-56⁵). Blok tabel pada kedua berkas ditutup oleh API END (README.md:302⁶).

Header tabel yang diterjemahkan

markdownBuilder tidak menulis header secara harfiah. Ia memanggil translate untuk tiap kolom (src/utils/markdown.ts:8-33⁷), dan kamus istilahnya hanya memuat dua bahasa, id dan en (src/data/vocabularies.json:1-18⁸).

Alur dari data/ ke README.md

src/build.ts adalah skrip yang menghubungkan data dengan README. Ia mengumpulkan seluruh berkas .json di bawah data/ lewat getFiles (src/utils/index.ts:13-33⁹). Direktori itu ditentukan oleh resolve, yang selalu menunjuk ke data di akar repository (src/utils/index.ts:5-7¹⁰). Kode bahasa diambil dari nama berkas tanpa ekstensi lewat getLanguage, sehingga id.json menjadi id (src/utils/index.ts:9-11¹¹).

graph TD
  ID["data/*/id.json"] --> GF["getFiles()"]
  EN["data/*/en.json"] --> GF
  GF --> GL["getLanguage()"]
  GL --> SORT["sort apis by apiName"]
  SORT --> RW{"--rewrite ?"}
  RW -->|ya| FETCH["fetch documentationUrl"]
  FETCH --> BACK["Bun.write JSON"]
  RW -->|tidak| GROUP["group per bahasa"]
  BACK --> GROUP
  GROUP --> MB["markdownBuilder()"]
  GROUP --> TOC["generateToc()"]
  MB --> REP["replace apiRegex"]
  TOC --> REP2["replace tocRegex"]
  REP --> W["Bun.write README"]
  REP2 --> W
  W --> FMT["Bun.spawn bun format"]
  style ID fill:#336791,color:#fff
  style EN fill:#336791,color:#fff
  style RW fill:#f59e0b,color:#000
  style MB fill:#8b5cf6,color:#fff
  style TOC fill:#8b5cf6,color:#fff
  style W fill:#2d7d46,color:#fff
%% fig: Alur data dari berkas kategori ke README
%% desc: Berkas JSON per kategori dibaca dan diurutkan, dirender menjadi tabel serta daftar isi, lalu ditulis ke README per bahasa.

Setelah pembacaan, setiap kategori diurutkan berdasarkan apiName lalu berkas JSON-nya ditulis kembali (src/build.ts:13-18¹²). Penulisan ulang itu terjadi di Bun.write pada akhir loop pertama (src/build.ts:77¹³). Opsi --rewrite hanya menambah satu tahap sebelum penulisan tersebut (src/build.ts:20¹⁴); perilakunya dibahas di Mode Rewrite dan Status API.

Tahap kedua bekerja per bahasa. Kategori diurutkan berdasarkan categoryName, lalu nama berkas disusun: id memakai README.md, bahasa lain memakai README.<bahasa>.md (src/build.ts:87-91¹⁵). Tabel dibangun markdownBuilder (src/utils/markdown.ts:8-33⁷) dan disisipkan dengan apiRegex (src/build.ts:96-98). Daftar isi dibangun generateToc (src/utils/markdown.ts:35-57) dan disisipkan dengan tocRegex (src/build.ts:101-103). Hasil akhir ditulis (src/build.ts:105), lalu bun format dijalankan lewat Bun.spawn (src/build.ts:109). Rincian tiap helper ada di Helper Markdown dan Daftar Isi dan Helper Berkas dan Filter Blacklist.

Skrip yang tersedia

Ketiganya didefinisikan di blok scripts (package.json:36-42²¹). Pemeriksaan di check.ts dijelaskan di Validator Data lewat check.ts, sedangkan langkah menjalankannya ada di Menjalankan Proyek di Lokal.

⚠️ Field module di package.json menunjuk src/builder.ts, berkas yang tidak ada di repository (package.json:8²²). Entry point yang benar adalah src/build.ts, dan itulah yang dipanggil script start (package.json:36-42²¹).

Nama kategori berbeda antar bahasa

categoryName disimpan di dalam tiap berkas JSON, bukan di dalam kode. Karena itu terjemahan nama kategori cukup dilakukan dengan mengubah nilainya.

Nilai tersebut dibaca apa adanya: kategori Islam memakai nama berbeda per bahasa (data/islamic/id.json:1-3²³, data/islamic/en.json:1-3²⁴), Berita menjadi News (data/news/id.json:2, data/news/en.json:2), Cuaca menjadi Weather (data/weather/id.json:2, data/weather/en.json:2), sementara E-Commerce tetap sama di kedua bahasa (data/e-commerce/id.json:1-3). Mekanisme lengkapnya ada di Dukungan Multi-Bahasa.

Membaca tanpa build

Untuk dibaca di browser, index.html memuat docsify dengan relativePath: true dan plugin search, sehingga README yang sama ditampilkan tanpa build tambahan (index.html:19-26³⁰). Panduan kontribusi ditautkan dari README ke CONTRIBUTING.md (README.md:304-306³¹) dan diuraikan di Alur Kontribusi API Baru, termasuk otomasi pemeriksaannya di Otomasi GitHub Actions.

Bentuk setiap berkas kategori mengikuti CategoryType dan ListType yang dipakai semua skrip di atas; keduanya dijelaskan di Skema Data Kategori, sedangkan susunan berkas di dalam src/ ada di Arsitektur Modul.