Skip to main content

Laravel i18n: Panduan Lengkap Pengantarabangsaan & Penyetempatan

Daripada fail lokal pertama hingga pengeluaran: konfigurasikan sistem terjemahan Laravel, kendalikan bentuk jamak, baiki pepijat sandaran JSON, dan tambahkan rantaian sandaran lokal pintar untuk varian serantau.

1

Fahami Sistem Terjemahan Laravel

Laravel dilengkapi sistem terjemahan terbina dalam yang menyokong dua format fail: tatasusunan PHP dan JSON. Fail PHP menggunakan kekunci bersarang yang disusun mengikut ciri (auth.failed, validation.required). Fail JSON menggunakan rentetan sumber sebagai kekunci, yang lebih mudah tetapi tidak menyokong 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 dalam direktori lang/ (Laravel 9+) atau resources/lang/ (Laravel 8 dan sebelumnya). Rangka kerja mengesan direktori secara automatik. Jika kedua-duanya wujud, lang/ diberi keutamaan.
2

Konfigurasikan Tetapan Lokal

Tetapkan lokal lalai dan lokal sandaran aplikasi anda dalam config/app.php. Lokal sandaran digunakan apabila kekunci terjemahan tiada dalam lokal aktif. Konfigurasikan lokal yang disokong oleh aplikasi dan tambahkan perisian tengah untuk mengesan serta menetapkan lokal 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 menterjemahkan rentetan: fungsi pembantu __() (disyorkan), fungsi trans(), dan arahan Blade @lang. Ketiga-tiganya menerima kekunci terjemahan dan parameter pengganti pilihan. Gunakan __() dalam kod PHP dan templat Blade, serta @lang dalam Blade apabila anda tidak perlu melepaskan 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 __() berbanding trans() dalam kod baharu. __() berfungsi dengan fail terjemahan PHP dan JSON, manakala trans() hanya berfungsi dengan fail PHP. Arahan @lang setara dengan {'{ __() }'} dalam templat Blade, tetapi sintaksnya sedikit lebih ringkas.
4

Kendalikan Bentuk Jamak

Laravel menggunakan sintaks yang dipisahkan tanda paip untuk bentuk jamak. Bentuk paling mudah ialah 'apples' => 'There is one apple|There are many apples'. Untuk julat jelas, gunakan 'apples' => '{0} No apples|{1} One apple|[2,*] :count apples'. Pembantu trans_choice() atau Str::plural() memilih bentuk yang betul berdasarkan bilangan.

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 terbina dalam Laravel hanya mengendalikan peraturan one/other mudah dengan tepat untuk kebanyakan bahasa. Untuk bahasa dengan bentuk jamak kompleks (Arab mempunyai 6, Rusia 4, Poland 3), anda perlu mentakrifkan semua kategori bentuk jamak CLDR yang diperlukan. Tanpanya, pengguna melihat teks yang salah dari segi tatabahasa.
5

Tambahkan Rantaian Sandaran Lokal

Sandaran terbina dalam Laravel hanya beralih daripada lokal aktif kepada fallback_locale — tiada langkah perantara. Pengguna pt-BR dengan kekunci yang tiada melihat bahasa Inggeris dan bukannya terjemahan pt-PT yang sebenarnya sesuai. laravel-locale-chain membaikinya dengan menggabungkan terjemahan secara mendalam daripada rantaian sandaran boleh dikonfigurasikan semasa 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

Automatikkan Terjemahan

Selepas persediaan i18n Laravel selesai, terjemahkan fail lokal anda menggunakan AI. Halakan pembantu AI kepada fail lokal sumber, atau gunakan CLI i18n Agent dalam saluran CI/CD anda. Fail terjemahan PHP dan JSON disokong.

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 berperingkat — apabila anda menambahkan kekunci baharu, terjemahkan hanya perbezaannya dan bukannya menjana semula semua fail. Cara ini mengekalkan terjemahan yang telah disemak manusia dan mengelakkan perubahan yang tidak perlu.

Kesilapan Umum

Logik Tunggal/Jamak yang Dikod Keras

Menulis $count == 1 ? 'item' : 'items' dan bukannya menggunakan trans_choice() akan gagal untuk bahasa yang menganggap 0 sebagai bentuk tunggal (Perancis), mempunyai lebih daripada 3 bentuk jamak (Rusia, Poland), atau mempunyai 6 bentuk (Arab). Sentiasa gunakan sintaks bentuk jamak Laravel dan takrifkan semua bentuk yang diperlukan.

Terjemahan JSON Tidak Bersandar

fallback_locale Laravel hanya berfungsi untuk fail terjemahan PHP. Terjemahan JSON menggunakan rentetan sumber sebagai kekunci, maka terjemahan yang tiada mengembalikan kekunci itu sendiri (teks bahasa Inggeris) dan bukannya mencari dalam lokal sandaran. Ini bermakna terjemahan JSON tidak mempunyai sandaran lokal sebenar. Gunakan laravel-locale-chain untuk membaikinya.

Mencampurkan PHP dan JSON Tanpa Memahami Keutamaan

Apabila kekunci yang sama wujud dalam fail PHP dan JSON, PHP diberi keutamaan. Hal ini boleh menyebabkan tingkah laku mengelirukan apabila pengemaskinian fail JSON tidak berkesan kerana fail PHP menutupinya. Pilih satu format bagi setiap ruang nama ciri dan gunakannya secara konsisten.

Cuba i18n Agent Sekarang

Lepaskan fail terjemahan anda di sini

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

atau klik untuk semak imbas

Bahasa sasaran

Tidak perlu mendaftarAnggaran serta-merta

Soalan Lazim i18n Laravel