Skip to main content

Laravel i18n: Kumpletong Gabay sa Internationalization at Localization

Mula unang locale file hanggang production: i-configure ang translation system ng Laravel, pangasiwaan ang pluralization, ayusin ang JSON fallback bug, at magdagdag ng smart locale fallback chains para sa mga regional variant.

1

Unawain ang Translation System ng Laravel

Nagshi-ship ang Laravel na may built-in na translation system na sumusuporta sa dalawang file format: PHP array at JSON. Gumagamit ang PHP file ng nested key na nakaayos ayon sa feature (auth.failed, validation.required). Gumagamit ang JSON file ng source string bilang key, na mas simple ngunit hindi sumusuporta sa nesting.

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
Nasa lang/ directory (Laravel 9+) o resources/lang/ (Laravel 8 at mas maaga) ang translation system ng Laravel. Awtomatikong dini-detect ng framework ang directory. Kapag pareho itong umiiral, mas inuuna ang lang/.
2

I-configure ang Locale Settings

Itakda ang default locale at fallback locale ng inyong application sa config/app.php. Ginagamit ang fallback locale kapag nawawala ang translation key sa aktibong locale. I-configure ang mga sinusuportahang locale para sa inyong application at magdagdag ng middleware upang matukoy at maitakda ang preferred locale ng user.

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

Gumamit ng Mga Function sa Pagsasalin

Nagbibigay ang Laravel ng tatlong paraan para isalin ang mga string: ang __() helper function (inirerekomenda), ang trans() function, at ang @lang Blade directive. Lahat ng tatlo ay tumatanggap ng translation key at mga opsyonal na replacement parameter. Gamitin ang __() sa PHP code at Blade template, at @lang sa Blade kapag hindi ninyo kailangang i-escape ang 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',
    ],
];
Mas piliin ang __() kaysa trans() sa bagong code. Gumagana ang __() sa parehong PHP at JSON translation file, habang ang trans() ay gumagana lamang sa PHP file. Katumbas ng {'{ __() }'} sa Blade template ang @lang directive, ngunit may bahagyang mas malinis na syntax.
4

Pangasiwaan ang Pluralization

Gumagamit ang Laravel ng pipe-separated na syntax para sa mga plural form. Ang pinakasimpleng anyo ay 'apples' => 'There is one apple|There are many apples'. Para sa mga tahasang range, gamitin 'apples' => '{0} No apples|{1} One apple|[2,*] :count apples'. Pinipili ng trans_choice() helper o ng Str::plural() ang tamang anyo batay sa bilang.

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"
}
Tama lamang na nahahawakan ng built-in na pluralization ng Laravel ang mga simpleng one/other na patakaran para sa karamihan ng mga wika. Para sa mga wikang may kumplikadong plural form (may 6 ang Arabic, 4 ang Russian, 3 ang Polish), kailangan ninyong idefine ang lahat ng kinakailangang CLDR plural category. Kung wala ang mga iyon, makakakita ang mga gumagamit ng tekstong hindi tama sa gramatika.
5

Magdagdag ng Locale Fallback Chain

Ang built-in na fallback ng Laravel ay lumilipat lamang mula sa aktibong locale papunta sa fallback_locale — walang intermediate na hakbang. Ang pt-BR na user na may nawawalang key ay makakakita ng English sa halip na ang maayos na pt-PT na pagsasalin. Inaayos ito ng laravel-locale-chain sa pamamagitan ng deep-merge ng mga pagsasalin mula sa isang nako-configure na fallback chain sa oras ng pag-load.

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

I-automate ang Mga Pagsasalin

Kapag kumpleto na ang inyong Laravel i18n setup, isalin ang inyong mga locale file gamit ang AI. Ituro ang inyong AI assistant sa source locale file, o gamitin ang i18n Agent CLI sa inyong CI/CD pipeline. Sinusuportahan ang parehong PHP at JSON translation file.

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
Isalin nang paunti-unti — kapag nagdagdag kayo ng bagong key, isalin lamang ang diff sa halip na muling i-generate ang lahat ng file. Pinapanatili nito ang mga pagsasaling na-review na ng tao at iniiwasan ang hindi kailangang churn.

Mga Karaniwang Pagkakamali

Hardcoded na Lohika para sa Isahan/Maramihan

Ang pagsusulat ng $count == 1 ? 'item' : 'items' sa halip na gamitin ang trans_choice() ay bumibigay sa mga wikang kung saan isahan ang 0 (French), kung saan may 3+ plural form (Russian, Polish), o kung saan may 6 na anyo (Arabic). Laging gamitin ang plural syntax ng Laravel at ideklara ang lahat ng kinakailangang anyo.

Hindi Nagfa-fallback ang JSON Translation

Gumagana lang ang fallback_locale ng Laravel para sa PHP translation file. Ginagamit ng JSON translation ang source string bilang key, kaya kapag nawawala ang pagsasalin, ibinabalik nito ang mismong key (ang English text) sa halip na tumingin sa fallback locale. Ibig sabihin, walang tunay na locale fallback ang JSON translation. Gamitin ang laravel-locale-chain para ayusin ito.

Paghahalo ng PHP at JSON nang Hindi Nauunawaan ang Precedence

Kapag umiiral ang parehong key sa PHP at JSON file, mas inuuna ang PHP. Maaari itong magdulot ng nakalilitong behavior kung saan walang epekto ang pag-update ng JSON file dahil natatakpan ito ng PHP file. Pumili ng isang format kada feature namespace at manatili rito.

Subukan ang i18n Agent Ngayon

I-drop dito ang inyong translation file

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

o i-click para mag-browse

Mga target language

Hindi kailangan ang signupInstant na estimate

FAQ sa Laravel i18n