Skip to main content

Laravel i18n: Eksiksiz uluslararasılaştırma ve yerelleştirme rehberi

İlk yerel ayar dosyasından üretime kadar Laravel'in çeviri sistemini yapılandırın, çoğullaştırmayı yönetin, JSON geri dönüşü hatasını giderin ve bölgesel varyantlar için akıllı yerel ayar geri dönüş zincirleri ekleyin.

1

Laravel'in çeviri sistemini anlayın

Laravel, iki dosya biçimini destekleyen yerleşik bir çeviri sistemiyle gelir: PHP dizileri ve JSON. PHP dosyaları, özelliğe göre düzenlenmiş iç içe anahtarlar kullanır (auth.failed, validation.required). JSON dosyaları kaynak dizeyi anahtar olarak kullanır; bu daha basittir ancak iç içe yerleşimi desteklemez.

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
Laravel'in çeviri sistemi lang/ klasöründe (Laravel 9+) veya resources/lang/ klasöründe (Laravel 8 ve önceki sürümler) bulunur. Çerçeve klasörü otomatik olarak algılar. Her ikisi de varsa lang/ önceliklidir.
2

Yerel ayarları yapılandırın

Uygulamanızın varsayılan yerel ayarını ve geri dönüş yerel ayarını config/app.php dosyasında belirleyin. Etkin yerel ayarda bir çeviri anahtarı eksik olduğunda geri dönüş yerel ayarı kullanılır. Uygulamanızın desteklediği yerel ayarları yapılandırın ve kullanıcının tercih ettiği yerel ayarı algılayıp ayarlamak için ara yazılım ekleyin.

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

Çeviri işlevlerini kullanın

Laravel, dizeleri çevirmek için üç yöntem sunar: __() yardımcı işlevi (önerilir), trans() işlevi ve @lang Blade yönergesi. Üçü de çeviri anahtarını ve isteğe bağlı değiştirme parametrelerini kabul eder. PHP kodunda ve Blade şablonlarında __(), HTML'den kaçış yapmanız gerekmediğinde ise Blade'de @lang kullanın.

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',
    ],
];
Yeni kodlarda trans() yerine __() işlevini tercih edin. __() hem PHP hem de JSON çeviri dosyalarıyla çalışırken trans() yalnızca PHP dosyalarıyla çalışır. @lang yönergesi, Blade şablonlarında {'{ __() }'} ile eşdeğerdir ancak söz dizimi biraz daha sadedir.
4

Çoğullaştırmayı yönetin

Laravel, çoğul biçimler için dikey çizgiyle ayrılmış bir söz dizimi kullanır. En basit biçim 'apples' => 'Bir elma var|Birçok elma var' şeklindedir. Açık aralıklar için 'apples' => '{0} Elma yok|{1} Bir elma|[2,*] :count elma' kullanın. trans_choice() yardımcı işlevi veya Str::plural(), sayıya göre doğru biçimi seçer.

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"
}
Laravel'in yerleşik çoğullaştırması, çoğu dil için yalnızca basit one/other kurallarını doğru işler. Karmaşık çoğul biçimleri olan dillerde (Arapçada 6, Rusçada 4, Lehçede 3 biçim vardır) gerekli tüm CLDR çoğul kategorilerini tanımlamanız gerekir. Bunlar tanımlanmazsa kullanıcılar dil bilgisi açısından yanlış metinler görür.
5

Yerel ayar geri dönüş zincirleri ekleyin

Laravel'in yerleşik geri dönüşü yalnızca etkin yerel ayardan fallback_locale değerine gider; arada başka bir adım yoktur. Eksik anahtarı olan pt-BR yerel ayarındaki bir kullanıcı, kullanılabilir durumdaki pt-PT çevirisi yerine İngilizce görür. laravel-locale-chain, yapılandırılabilir geri dönüş zincirindeki çevirileri yükleme sırasında derinlemesine birleştirerek bu sorunu giderir.

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

Çevirileri otomatikleştirin

Laravel i18n kurulumunuz tamamlandıktan sonra yerel ayar dosyalarınızı yapay zeka ile çevirin. Yapay zeka yardımcınıza kaynak yerel ayar dosyasını gösterin veya CI/CD işlem hattınızda i18n Agent CLI'ı kullanın. Hem PHP hem de JSON çeviri dosyaları desteklenir.

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
Artımlı çeviri yapın; yeni anahtarlar eklediğinizde tüm dosyaları yeniden oluşturmak yerine yalnızca farkı çevirin. Böylece insanlar tarafından gözden geçirilmiş çeviriler korunur ve gereksiz değişiklikler önlenir.

Yaygın hatalar

Doğrudan kodlanmış tekil/çoğul mantığı

trans_choice() kullanmak yerine $count == 1 ? 'öğe' : 'öğeler' yazmak; 0'ın tekil olduğu dillerde (Fransızca), 3+ çoğul biçimi olan dillerde (Rusça, Lehçe) veya 6 biçimi olan dillerde (Arapça) sorun çıkarır. Her zaman Laravel'in çoğul söz dizimini kullanın ve gerekli tüm biçimleri tanımlayın.

JSON çevirilerinin geri dönüş yapmaması

Laravel'in fallback_locale ayarı yalnızca PHP çeviri dosyalarında çalışır. JSON çevirileri kaynak dizeyi anahtar olarak kullandığından eksik bir çeviri, geri dönüş yerel ayarında arama yapmak yerine anahtarın kendisini (İngilizce metni) döndürür. Bu nedenle JSON çevirilerinin gerçek bir yerel ayar geri dönüşü yoktur. Sorunu gidermek için laravel-locale-chain kullanın.

Önceliği anlamadan PHP ve JSON biçimlerini karıştırmak

Aynı anahtar hem PHP hem de JSON dosyalarında bulunduğunda PHP önceliklidir. PHP dosyası JSON dosyasını gölgelediği için JSON dosyasını güncellemenin hiçbir etkisinin olmadığı kafa karıştırıcı durumlar oluşabilir. Her özellik ad alanı için tek bir biçim seçin ve onu kullanmayı sürdürün.

i18n Agent'ı şimdi deneyin

Çeviri dosyanızı buraya bırakın

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

veya göz atmak için tıklayın

Hedef diller

Kayıt gerekmezAnında fiyat tahmini

Laravel i18n hakkında sık sorulan sorular