Panduan Menambahkan Bahasa Baru

Pengantar: Arsitektur Dua Berkas

WikiNusa didedikasikan untuk pelestarian bahasa dan penyebaran pengetahuan bebas dalam bahasa-bahasa daerah di Indonesia dan sekitarnya. Untuk memudahkan siapa pun berkontribusi tanpa latar belakang teknis yang rumit, WikiNusa mengadopsi arsitektur modular dua berkas.

Anda tidak perlu menyunting kode pemrograman Dart maupun Flutter sama sekali. Setiap bahasa hanya dikelola melalui dua berkas JSON independen:

• assets/communities/<kode_bahasa>.json — Berkas konfigurasi proyek, portal, pintasan, sakelar modul, dan aturan tampilan wiki.
• assets/translations/<kode_bahasa>.json — Berkas pelokalan string teks antarmuka (UI).

Menentukan Kode Bahasa

Tentukan kode bahasa standar resmi (ISO 639-1, 639-2, atau 639-3) yang sesuai dengan sub-domain Wikimedia bahasa Anda.

Beberapa contoh kode bahasa daerah yang telah atau sedang didukung:

• ban — Bahasa Bali (Basa Bali)
• ace — Bahasa Aceh (Bahsa Acèh)
• mak — Bahasa Makassar (Basa Mangkasara')
• min — Bahasa Minangkabau (Baso Minang)
• jv — Bahasa Jawa (Basa Jawa)
• su — Bahasa Sunda (Basa Sunda)
• nia — Bahasa Nias (Li Niha)
• bbc — Bahasa Batak Toba
• btm — Bahasa Batak Mandailing

Menyiapkan Berkas Komunitas

Buat berkas baru di dalam folder assets/communities/ dengan nama <kode>.json (contoh: assets/communities/ban.json).

Berikut adalah templat lengkap yang dapat Anda salin dan sesuaikan:

{
  "code": "ban",
  "name": "Balinese",
  "nativeName": "Basa Bali",
  "direction": "ltr",
  "experimental": false,
  "defaultProject": "wikipedia",
  "projects": {
    "wikipedia": {
      "name": "Wikipédia",
      "articlePath": "https://ban.wikipedia.org/wiki/$1",
      "apiEndpoint": "https://ban.wikipedia.org/w/api.php",
      "mobileUrl": "https://ban.m.wikipedia.org",
      "isIncubator": false,
      "homePageSections": {
        "featuredArticle": "mp-tfa",
        "featuredImage": "mp-tfp",
        "doYouKnow": "mp-dyk",
        "onThisDay": "mp-otd"
      },
      "shortcuts": [
        "Portal:Komunitas",
        "Istimewa:Perubahan_terbaru",
        "Wikipédia:Pitulung"
      ],
      "portals": [
        {
          "title": "Budaya",
          "page": "Portal:Budaya"
        }
      ],
      "modules": {
        "chat": true,
        "newsletter": false,
        "crosswords": false,
        "language_course": false,
        "gallery": false
      }
    },
    "wiktionary": {
      "name": "Wikikamus",
      "articlePath": "https://ban.wiktionary.org/wiki/$1",
      "apiEndpoint": "https://ban.wiktionary.org/w/api.php",
      "mobileUrl": "https://ban.m.wiktionary.org",
      "isIncubator": false,
      "homePageSections": {
        "featuredWord": "mp-word-day-body",
        "newWords": "mp-new-words-body"
      },
      "shortcuts": [
        "Wikikamus:Pitulung"
      ]
    }
  }
}

Tabel Referensi Parameter

Pengaturan Proyek Wikimedia

• name: Judul lokal proyek (misal: "Wikipédia").
• articlePath: Format URL dengan placeholder $1 untuk judul artikel.
• apiEndpoint: URL Action API MediaWiki (misal: https://ban.wikipedia.org/w/api.php).
• mobileUrl: URL versi seluler situs web.
• isIncubator: Setel true jika bahasa Anda masih dalam Wikimedia Incubator, lalu tambahkan incubatorPrefix (misal: "Wp/btm/").
• homePageSections: Pemetaan selektor untuk mengekstrak dan menampilkan seksi halaman utama dalam format kartu ponsel yang rapi (bukan tampilan desktop mentah).
• shortcuts: Daftar judul halaman wiki yang akan muncul pada menu pintasan cepat di laci samping.
• portals: Daftar kartu portal bertopik khusus untuk ditampilkan di halaman beranda.
• modules: Sakelar modul pendukung seperti ruang obrolan (chat), buletin (newsletter), teka-teki silang (crosswords), kursus bahasa (language_course), atau galeri (gallery).

Konfigurasi Seksi Beranda (homePageSections)

WikiNusa memproses Halaman Utama wiki (seperti Halaman_Utama, Main_Page, atau Wikipédia:Pendhapa) dan mengubah setiap bagian konten menjadi kartu interaktif native di beranda aplikasi.

Kunci Seksi yang Didukung

Format Penulisan Selektor

Setiap seksi dapat diatur menggunakan String Sederhana atau Objek Terperinci:

1. Format String Sederhana (ID atau Kelas CSS)

"homePageSections": {
  "featuredArticle": "mp-tfa",
  "featuredImage": "mp-tfp",
  "doYouKnow": "mp-dyk",
  "onThisDay": "mp-otd"
}

2. Format Objek Terperinci (Ekstraksi Presisi)

Gunakan format ini jika kotak templat di wiki Anda memiliki pranala navigasi arsip, tombol sunting, atau tabel yang perlu dirapikan:

"homePageSections": {
  "featuredArticle": {
    "selector": "mf-artikelpilihan",
    "keep": "p",
    "firstOnly": true
  },
  "doYouKnow": {
    "selector": "mf-tahukahanda",
    "keep": "ul",
    "firstOnly": true
  }
}

• selector (String, Wajib): Selektor CSS dari elemen pembungkus konten di Halaman Utama.
• keep (String atau Array of Strings, Opsional): Tag HTML tertentu yang ingin dipertahankan (misal "p" agar hanya mengambil paragraf ringkasan, atau ["p", "ul"]).
• firstOnly (Boolean, Opsional): Bila bernilai true, hanya mengambil elemen pertama yang cocok dan membuang pranala arsip tambahan di bawahnya.

Penyesuaian Aturan Tampilan & Keep

Secara default, aplikasi menerapkan aturan global dari assets/communities/_global.json untuk menghapus kotak navigasi desktop dan elemen yang mengganggu tampilan mobile.

Namun, jika komunitas bahasa Anda ingin mempertahankan elemen tertentu yang dihapus oleh aturan global (misalnya kotak info atau kelas tertentu), gunakan kunci keep:

"projects": {
  "wikipedia": {
    "name": "Wikipédia",
    "articlePath": "https://ban.wikipedia.org/wiki/$1",
    "apiEndpoint": "https://ban.wikipedia.org/w/api.php",
    "keep": [".infobox", ".nomobile"],
    "remove": [".reflist"]
  }
}

• keep: Selektor CSS yang tidak boleh dibuang untuk bahasa ini, meskipun aturan global menyuruh menghapusnya.
• remove: Selektor CSS tambahan yang ingin dihapus khusus untuk artikel proyek ini.
• hide: Selektor CSS tambahan yang ingin disembunyikan menggunakan styling CSS.

Menyiapkan Berkas Terjemahan

Salin berkas assets/translations/id.json atau assets/translations/en.json, lalu simpan sebagai assets/translations/<kode>.json (misal: assets/translations/ban.json).

Buka berkas tersebut dan terjemahkan nilai teks di sisi kanan tanda titik dua (:):

{
  "app_name": "WikiNusa",
  "home": "Kaca Utama",
  "shortcuts": "Pintasan",
  "random": "Acak",
  "bookmarks": "Tanda Buku",
  "search_hint": "Rereh ring WikiNusa...",
  "share": "Bagikan",
  "edit": "Uwah",
  "view_in_browser": "Cingak ring Browser",
  "table_of_contents": "Daftar Isi",
  "drawer_modules": "Modul Komunitas",
  "drawer_language": "Basa",
  "drawer_appearance": "Tampilan",
  "drawer_font_size": "Ukuran Aksara",
  "drawer_about": "Indik Aplikasi"
}

Validasi Berkas JSON

Sebelum mengirimkan kontribusi Anda, pastikan kedua berkas JSON memiliki sintaksis yang valid:

1. Pastikan semua tanda kurung kurawal {} dan kurung siku [] tertutup sempurna.
2. Pastikan tidak ada koma berlebih di akhir (trailing comma) setelah elemen terakhir dalam array atau objek.
3. Gunakan validator JSON online di jsonlint.com atau perintah jq di terminal:

jq . assets/communities/ban.json
jq . assets/translations/ban.json

Uji Coba Aplikasi (Opsional)

Jika Anda memiliki lingkungan pengembangan Flutter di komputer Anda:

1. Jalankan verifikasi pengujian otomatis:

   flutter test

2. Jalankan aplikasi di perangkat atau emulator:

   flutter run

3. Buka laci samping → Basa → aktifkan bahasa baru Anda. Bahasa Anda akan langsung siap digunakan!

Mengirimkan Kontribusi via Pull Request

Kirimkan perubahan Anda ke repositori utama melalui GitHub:

1. Fork repositori WikiNusa di GitHub: github.com/sslaia/wikinusa.
2. Buat branch baru di komputer Anda:

   git checkout -b feat/tambah-bahasa-bali

3. Tambahkan kedua berkas JSON baru:

   git add assets/communities/ban.json assets/translations/ban.json
   git commit -m "feat(community): tambah konfigurasi dan terjemahan bahasa Bali (ban)"

4. Unggah ke repositori fork Anda:

   git push origin feat/tambah-bahasa-bali

5. Buka Pull Request (PR) di GitHub. Tim pengelola WikiNusa akan dengan senang hati meninjau dan menggabungkannya ke dalam rilis aplikasi berikutnya!