KAL
Menu

Lokalisasi berkas lang dan locale

Berkas terjemahan, pengalihan locale, dan pesan validasi berbahasa Indonesia.

Daftar isi

Aplikasi yang ditujukan bagi pengguna Indonesia lebih tepat menampilkan teksnya dalam bahasa Indonesia, termasuk pesan error validasi yang muncul pada formulir. Laravel menyimpan teks antarmuka pada berkas terjemahan (translation) di direktori lang, dan helper __() mengambil barisnya sesuai locale yang aktif. Topik ini membahas struktur berkas lang, cara mengalihkan locale, dan pemasangan pesan validasi berbahasa Indonesia beserta perilaku fallback-nya.

Berkas terjemahan pada direktori lang#

Berkas terjemahan dikelompokkan per locale pada direktori lang, misalnya lang/en untuk bahasa Inggris dan lang/id untuk bahasa Indonesia. Setiap berkas PHP mengembalikan array berpasangan kunci dan teksnya, sedangkan kunci diakses dengan notasi titik, misalnya pesan.selamat-datang untuk kunci selamat-datang pada berkas pesan.php. Pembacaan dilakukan melalui helper __(), dan trans() adalah sinonimnya yang digunakan pada kode lama.

Proyek bawaan Laravel 11 ke atas tidak menyertakan direktori lang apa pun, dan perintah lang:publish menerbitkan berkas bawaan berbahasa Inggris bagi proyek yang membutuhkannya. Pada contoh ini, dua berkas pesan.php ditulis langsung pada dua locale agar perbedaannya tampak jelas. Placeholder diawali titik dua, dan nilainya dikirim sebagai array pada argumen kedua __().

bash 
# menyiapkan berkas terjemahan pesan pada dua locale
cd ~/aplikasi-catatan
mkdir -p lang/en lang/id
cat > lang/en/pesan.php <<'PHP'
<?php

return [
    'selamat-datang' => 'Welcome to the notes application.',
    'salam' => 'Hello, :nama!',
    'sisa-catatan' => 'You have :jumlah notes remaining.',
];
PHP
cat > lang/id/pesan.php <<'PHP'
<?php

return [
    'selamat-datang' => 'Selamat datang di aplikasi catatan.',
    'salam' => 'Halo, :nama!',
    'sisa-catatan' => 'Tersisa :jumlah catatan.',
];
PHP

Kedua berkas memuat kunci yang sama persis, sehingga pergantian locale tidak mengubah struktur pesan yang tersedia. Placeholder :nama dan :jumlah berada di tengah teks, dan posisinya bebas diatur sesuai tata bahasa tiap locale, sesuatu yang sulit dilakukan dengan penggabungan string biasa. Cara membaca kedua berkas itu dipraktikkan pada bagian berikutnya.

Mengalihkan locale#

Locale aktif ditentukan oleh konfigurasi app.locale, yang nilainya diambil dari variabel lingkungan APP_LOCALE. Metode App::setLocale() mengubahnya selama satu siklus permintaan atau satu proses. Apabila baris yang dicari tidak ada pada locale aktif, Laravel menggunakan locale app.fallback_locale, yang bawaannya juga en.

Tinker dijalankan dari awal pada setiap eksekusi, sehingga contoh berikut membaca locale bawaan lebih dahulu, mengalihkannya ke id, lalu membaca tiga kunci yang sama dengan placeholder yang terisi.

bash 
# membaca berkas terjemahan pada locale bawaan dan setelah dialihkan
cd ~/aplikasi-catatan
php artisan tinker --execute='
use Illuminate\Support\Facades\App;
echo __("pesan.selamat-datang").PHP_EOL;
App::setLocale("id");
echo __("pesan.selamat-datang").PHP_EOL;
echo __("pesan.salam", ["nama" => "Dewi"]).PHP_EOL;
echo __("pesan.sisa-catatan", ["jumlah" => 10]).PHP_EOL;
'
text Keluaran 
Welcome to the notes application.
Selamat datang di aplikasi catatan.
Halo, Dewi!
Tersisa 10 catatan.

Dua baris pertama menunjukkan kunci yang sama menghasilkan teks berbeda setelah locale dialihkan. Dua baris berikutnya menunjukkan placeholder :nama dan :jumlah terisi dari array argumen kedua. Karena locale hanya berlaku selama proses berjalan, aplikasi web yang menyimpan pilihan pengguna biasanya mengatur ulang locale pada middleware, misalnya berdasarkan session atau cookie.

Pesan validasi berbahasa Indonesia#

Pesan error validasi diambil dari berkas validation.php pada locale aktif, dengan kunci berupa nama aturannya. Sebagian aturan memiliki varian per tipe nilai, misalnya max.string untuk teks dan max.numeric untuk angka, sehingga kuncinya bersarang satu tingkat. Peta pada kunci attributes mengganti nama kolom dengan istilah aplikasi untuk seluruh pesan pada locale tersebut, sehingga tidak perlu mengirim array atribut di setiap pemanggilan validator.

Berkas validation.php boleh bersifat parsial. Aturan yang tidak didefinisikan pada locale aktif diambil dari locale fallback, dan paket framework menyertakan pesan bawaan berbahasa Inggris sebagai sumber terakhir. Berkat mekanisme itu, penerjemahan dapat dilakukan bertahap untuk aturan yang paling sering muncul lebih dahulu.

bash 
# menyiapkan pesan validasi berbahasa Indonesia untuk sebagian aturan
cd ~/aplikasi-catatan
cat > lang/id/validation.php <<'PHP'
<?php

return [
    'required' => ':attribute wajib diisi.',
    'in' => ':attribute yang dipilih tidak tersedia.',
    'max' => [
        'string' => ':attribute tidak boleh melebihi :max karakter.',
    ],
    'attributes' => [
        'judul' => 'judul catatan',
        'isi' => 'isi catatan',
        'category_id' => 'kategori',
    ],
];
PHP

Pemeriksaan berikut menggunakan empat aturan sekaligus, yaitu required, max, dan in yang sudah diterjemahkan, serta url yang sengaja tidak didefinisikan untuk memperlihatkan fallback.

bash 
# menguji pesan validasi pada locale id
cd ~/aplikasi-catatan
php artisan tinker --execute='
use Illuminate\Support\Facades\App;
use Illuminate\Support\Facades\Validator;
App::setLocale("id");
$validator = Validator::make(
    ["judul" => "", "isi" => str_repeat("A", 30), "category_id" => 9, "tautan" => "bukan-url"],
    ["judul" => ["required", "string", "max:20"],
     "isi" => ["required", "string", "max:20"],
     "category_id" => ["required", "integer", "in:1,2,3"],
     "tautan" => ["nullable", "url"]]
);
foreach ($validator->errors()->all() as $pesan) {
    echo $pesan.PHP_EOL;
}
'
text Keluaran 
judul catatan wajib diisi.
isi catatan tidak boleh melebihi 20 karakter.
kategori yang dipilih tidak tersedia.
The tautan field must be a valid URL.

Tiga pesan pertama tampil berbahasa Indonesia dengan nama atribut dari peta attributes, lengkap dengan nilai :max yang tergantikan. Pesan keempat diambil dari pesan bawaan framework karena aturan url tidak ada pada berkas id, dan teksnya tetap menyebut nama kolom tautan. Menambahkan kunci url pada berkas yang sama sudah cukup untuk menerjemahkan sisanya.

Kesalahan umum#

Kesalahan pertama adalah menulis pesan aturan bervarian sebagai kunci tunggal, misalnya 'max' => '...' dalam bentuk string, padahal validator mencari kunci bersarang seperti max.string. Pesan dengan bentuk datar tidak pernah ditemukan, sehingga pesan yang tampil berubah menjadi bahasa Inggris tanpa tanda peringatan apa pun. Varian yang dicari menyesuaikan tipe nilai, antara lain string, numeric, dan file, sehingga cukup menulis satu varian yang sesuai dengan kebutuhan kolom tersebut.

Kesalahan kedua adalah menganggap App::setLocale() menetap untuk selamanya. Locale kembali ke nilai konfigurasi pada setiap permintaan baru, sehingga teks yang tampak benar di tinker dapat kembali berbahasa Inggris di browser. Pilihan pengguna disimpan pada session atau database, lalu middleware membacanya dan memanggil App::setLocale() pada setiap permintaan.

Kesalahan ketiga adalah kunci yang salah ketik. Helper __() mengembalikan kuncinya sendiri apabila barisnya tidak ditemukan pada locale aktif maupun fallback, sehingga halaman memuat teks seperti pesan.selamat-datang apa adanya. Ciri ini justru membantu pencarian, karena kunci yang tampil utuh langsung menunjukkan baris yang perlu diperbaiki.

Ringkasan#

  • Teks aplikasi disimpan pada berkas PHP di lang/<locale> dan dibaca melalui helper __() dengan notasi titik, termasuk placeholder yang diisi dari argumen keduanya.
  • Metode App::setLocale() mengubah locale selama satu siklus permintaan, nilai APP_LOCALE menentukan bawaannya, dan app.fallback_locale menjadi cadangannya.
  • Pesan validasi berbahasa Indonesia cukup ditulis pada lang/id/validation.php secara parsial, dan aturan yang belum diterjemahkan otomatis diambil dari pesan bawaan berbahasa Inggris.
  • Kunci attributes pada validation.php mengganti nama kolom untuk seluruh pesan validasi pada locale tersebut.

Referensi#