Skip to main content

Laravel i18n: Panduan Lengkap Internasionalisasi & Lokalisasi

Dari file locale pertama hingga produksi: konfigurasikan sistem terjemahan Laravel, tangani bentuk jamak, perbaiki bug fallback JSON, dan tambahkan rantai fallback locale cerdas untuk varian regional.

1

Pahami Sistem Terjemahan Laravel

Laravel dilengkapi sistem terjemahan bawaan yang mendukung dua format file: array PHP dan JSON. File PHP menggunakan kunci bersarang yang diatur berdasarkan fitur (auth.failed, validation.required). File JSON menggunakan string sumber sebagai kunci, yang lebih sederhana tetapi tidak mendukung struktur bersarang.

Terminal
composer create-project laravel/laravel my-app
cd my-app

# Laravel includes i18n out of the box
# No extra packages needed for basic usage
Sistem terjemahan Laravel berada di direktori lang/ (Laravel 9+) atau resources/lang/ (Laravel 8 dan sebelumnya). Framework mendeteksi direktori secara otomatis. Jika keduanya ada, lang/ diprioritaskan.
2

Konfigurasikan Pengaturan Locale

Atur locale default dan locale fallback aplikasi Anda dalam config/app.php. Locale fallback digunakan ketika kunci terjemahan tidak tersedia dalam locale aktif. Konfigurasikan locale yang didukung aplikasi dan tambahkan middleware untuk mendeteksi serta menetapkan locale pilihan pengguna.

config/app.php
// config/app.php
return [
    'locale' => 'en',            // Default locale
    'fallback_locale' => 'en',   // Fallback when key is missing
    'faker_locale' => 'en_US',

    // Available locales (for your language switcher)
    'available_locales' => ['en', 'de', 'ja', 'es', 'fr', 'pt-BR'],
];
app/Http/Middleware/SetLocale.php
// app/Http/Middleware/SetLocale.php
namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;

class SetLocale
{
    public function handle(Request $request, Closure $next)
    {
        $locale = $request->segment(1); // e.g. /de/about

        if (in_array($locale, config('app.available_locales'))) {
            app()->setLocale($locale);
        }

        return $next($request);
    }
}
3

Gunakan Fungsi Terjemahan

Laravel menyediakan tiga cara untuk menerjemahkan string: fungsi pembantu __() (direkomendasikan), fungsi trans(), dan directive Blade @lang. Ketiganya menerima kunci terjemahan dan parameter pengganti opsional. Gunakan __() dalam kode PHP dan template Blade, serta @lang dalam Blade ketika Anda tidak perlu meng-escape HTML.

lang/en/messages.php
// lang/en/messages.php
return [
    'welcome' => 'Welcome to our application',
    'greeting' => 'Hello, :name!',
    'nav' => [
        'home' => 'Home',
        'about' => 'About',
        'settings' => 'Settings',
    ],
];

// lang/de/messages.php
return [
    'welcome' => 'Willkommen in unserer Anwendung',
    'greeting' => 'Hallo, :name!',
    'nav' => [
        'home' => 'Startseite',
        'about' => 'Über uns',
        'settings' => 'Einstellungen',
    ],
];
Utamakan __() daripada trans() dalam kode baru. __() berfungsi dengan file terjemahan PHP dan JSON, sedangkan trans() hanya berfungsi dengan file PHP. Directive @lang setara dengan {'{ __() }'} dalam template Blade, tetapi sintaksnya sedikit lebih ringkas.
4

Tangani Bentuk Jamak

Laravel menggunakan sintaks yang dipisahkan tanda pipa untuk bentuk jamak. Bentuk paling sederhana adalah 'apples' => 'There is one apple|There are many apples'. Untuk rentang eksplisit, gunakan 'apples' => '{0} No apples|{1} One apple|[2,*] :count apples'. Pembantu trans_choice() atau Str::plural() memilih bentuk yang benar berdasarkan jumlah.

lang/en.json
// lang/en.json
{
    "Welcome back!": "Welcome back!",
    "You have :count new notifications": "You have :count new notifications",
    "Copyright :year :company": "Copyright :year :company"
}

// lang/de.json
{
    "Welcome back!": "Willkommen zurück!",
    "You have :count new notifications": "Sie haben :count neue Benachrichtigungen",
    "Copyright :year :company": "Copyright :year :company"
}
Bentuk jamak bawaan Laravel hanya menangani aturan one/other sederhana secara tepat untuk sebagian besar bahasa. Untuk bahasa dengan bentuk jamak kompleks (Arab memiliki 6, Rusia 4, Polandia 3), Anda perlu mendefinisikan semua kategori bentuk jamak CLDR yang diperlukan. Tanpanya, pengguna melihat teks yang salah secara tata bahasa.
5

Tambahkan Rantai Fallback Locale

Fallback bawaan Laravel hanya beralih dari locale aktif ke fallback_locale — tidak ada langkah perantara. Pengguna pt-BR dengan kunci yang tidak tersedia melihat bahasa Inggris alih-alih terjemahan pt-PT yang sebenarnya sesuai. laravel-locale-chain memperbaikinya dengan menggabungkan terjemahan secara mendalam dari rantai fallback yang dapat dikonfigurasi saat pemuatan.

resources/views/example.blade.php
{{-- Simple translation --}}
<h1>{{ __('messages.welcome') }}</h1>

{{-- With variables --}}
<p>{{ __('messages.greeting', ['name' => $user->name]) }}</p>

{{-- Using @lang directive --}}
<h2>@lang('messages.nav.home')</h2>

{{-- JSON translations (use the string itself as key) --}}
<p>{{ __('Welcome back!') }}</p>

{{-- Pluralization --}}
{{ trans_choice('{0} No items|{1} One item|[2,*] :count items', $count) }}

{{-- Inside Blade components --}}
<x-button>{{ __('messages.nav.settings') }}</x-button>
6

Otomatiskan Penerjemahan

Setelah penyiapan i18n Laravel selesai, terjemahkan file locale Anda menggunakan AI. Arahkan asisten AI ke file locale sumber, atau gunakan CLI i18n Agent dalam pipeline CI/CD Anda. File terjemahan PHP dan JSON didukung.

config/locale-chain.php
// Install locale chain package
composer require i18n-agent/laravel-locale-chain

// config/locale-chain.php
return [
    'chains' => [
        'pt-BR' => ['pt-BR', 'pt', 'en'],
        'zh-Hant-TW' => ['zh-Hant-TW', 'zh-Hant', 'zh', 'en'],
        'es-419' => ['es-419', 'es', 'en'],
    ],
];

// In AppServiceProvider::boot()
use I18nAgent\LocaleChain\LocaleChainServiceProvider;

// The package automatically deep-merges translations
// across the chain: pt-BR -> pt -> en
Terjemahkan secara bertahap — ketika Anda menambahkan kunci baru, terjemahkan hanya perbedaannya alih-alih membuat ulang semua file. Cara ini mempertahankan terjemahan yang telah ditinjau manusia dan menghindari perubahan yang tidak perlu.

Kesalahan Umum

Logika Tunggal/Jamak yang Di-hardcode

Menulis $count == 1 ? 'item' : 'items' alih-alih menggunakan trans_choice() akan gagal untuk bahasa yang memperlakukan 0 sebagai bentuk tunggal (Prancis), memiliki lebih dari 3 bentuk jamak (Rusia, Polandia), atau memiliki 6 bentuk (Arab). Selalu gunakan sintaks bentuk jamak Laravel dan tentukan semua bentuk yang diperlukan.

Terjemahan JSON Tidak Melakukan Fallback

fallback_locale Laravel hanya berfungsi untuk file terjemahan PHP. Terjemahan JSON menggunakan string sumber sebagai kunci, sehingga terjemahan yang tidak tersedia mengembalikan kunci itu sendiri (teks bahasa Inggris) alih-alih mencari dalam locale fallback. Artinya, terjemahan JSON tidak memiliki fallback locale yang sebenarnya. Gunakan laravel-locale-chain untuk memperbaikinya.

Mencampurkan PHP dan JSON Tanpa Memahami Prioritas

Ketika kunci yang sama ada dalam file PHP dan JSON, PHP diprioritaskan. Hal ini dapat menyebabkan perilaku membingungkan ketika pembaruan file JSON tidak berpengaruh karena file PHP menutupinya. Pilih satu format per namespace fitur dan gunakan secara konsisten.

Coba i18n Agent Sekarang

Lepaskan file terjemahan Anda di sini

JSON, YAML, PO, XML, CSV, Markdown, Properties

atau klik untuk menjelajahi

Bahasa target

Tidak perlu mendaftarEstimasi instan

Tanya Jawab i18n Laravel