Laravel Yeni ile Hazır Yerelleştirme — Laravel Başlangıç Kitleri (React/Vue/Svelte) için i18n

Laravel’ın resmi Başlangıç Kitleri, şu anda yalnızca Livewire versiyonunda uluslararasılaştırmayı (i18n) desteklemektedir. Inertia tabanlı kitler (React / Vue / Svelte) ise tüm UI metinlerini İngilizce olarak kodlanmış durumda tutmaktadır. Resmi desteğin ne zaman geleceği hakkında tartışmalar devam etmesine rağmen (laravel/maestro#168), ben de resmi destek gelene kadar geçici bir çözüm olarak yerelleştirilmiş fork’lar oluşturdum ve yayınladım.

Bu fork’lar, resmi kitlerden dört açıdan farklıdır:

• Japonca hemen kullanılabilir — ja dil kaynakları dahil edilmiştir. Yapmanız gereken tek şey .env dosyasındaki bir satırı değiştirmektir.
• Tüm UI dizeleri __() ile geçmektedir — İngilizce olarak kodlanmış metinler, çevirilebilir dizelerle değiştirilmiştir.
• Dil eklemek kolaydır — sadece bir JSON dosyası ekleyin ve bir komut çalıştırın (aşağıdaki Fransızca örneğine bakın).
• Ayarlanan yerel oturumda saklanır — seçilen dil, sayfa yeniden yüklendikten sonra devam eder.

Yalnızca her deposunun main dalının eşdeğeri sağlanmaktadır. teams ve WorkOS varyantları mevcut değildir.

Denemek İsteyenler İçin

composer global require laravel/installer # yüklenmediyse
laravel new Your_App --using=https://github.com/catatsumuri/react-starter-kit-i18n
cd Your_App
composer dev

Ardından APP_LOCALE değerini .env dosyasında ja olarak değiştirin ve geliştirme sunucusunu yeniden başlatın. Ayrıntılı kurulum talimatları daha sonra açıklanacaktır, ancak önce bir demo var.

Önce Demo’yu Deneyin

Tamamen yerelleştirilmiş bir Japonca durumu için bir demo, Laravel Cloud’da mevcuttur.

Yerelleştirilmiş giriş ekranı

Aşağıdaki hesapla giriş yapabilirsiniz. Veritabanı salt okunur olduğundan, keşfetmekte özgürsünüz.

• Email: [email protected]
• Şifre: password

Gerçek Kurulum

Gereksinimler

laravel komutuna (Laravel Installer) ve npm‘ye ihtiyacınız var. Eğer yüklenmemişse:

composer global require laravel/installer

% laravel --version
Laravel Installer 5.28.1

(Bu makale Docker tabanlı kurulumları kapsamamaktadır.)

laravel new ile Özel Başlangıç Kitini Belirleme

Yalnızca --using seçeneğine depo URL’sini geçirmeniz yeterlidir. Aşağıdaki örnek React kullanıyor, ancak Vue ve Svelte de aynı prosedürü farklı URL’lerle izler.

# Your_App yerine geçerli bir isim yazın
laravel new Your_App --using=https://github.com/catatsumuri/react-starter-kit-i18n

Yine deponun kendisi şu şekildedir:

Ben genellikle React versiyonunu kullanıyorum. Vue ve Svelte versiyonları aynı mekanizmayı kullanıyor, ancak bazı pürüzler olabilir. Sorunla karşılaşırsanız, bir hata raporu yazarsanız memnun olurum.

Komutu çalıştırdığınızda, etkileşimli moda geçer ve birkaç soru sorar. Varsayılanlar genellikle iyidir.

 ┌ Hangi test çerçevesini tercih edersiniz? ──────────────────────┐
 │ › ● Pest                                                     │
 │   ○ PHPUnit                                                  │
 └──────────────────────────────────────────────────────────────┘

 ┌ Laravel Boost yüklemek ister misiniz? │
 │ ● Evet / ○ Hayır                                               │
 └─────────────────────────────────────────────────────────────────────┘

Sonraki adım, kimlik doğrulama özelliklerini seçmektir.

 ┌ Hangi kimlik doğrulama özelliklerini etkinleştirmek istersiniz? ─────┐
 │ › ◼ Email doğrulaması                                        │
 │   ◼ Kayıt                                                  │
 │   ◼ İki faktörlü kimlik doğrulama                           │
 │   ◼ Parola anahtarları                                        │
 │   ◼ Parola onayı                                           │
 └──────────────────────────────────────────────────────────────┘
  Boşluk tuşunu seçmek, onaylamak için Enter'a basın.

Eğer Kayıt özelliğini etkinleştirirseniz, uygulama herkesin bir hesap oluşturmasına izin verecektir. Seçim yapmadan önce bunun istediğiniz davranışla örtüştüğünden emin olun.

Son olarak, npm çalıştırmak isteyip istemediğiniz sorulacaktır. Genellikle Evet seçmek en güvenli seçenektir.

 ┌ npm install --ignore-scripts çalıştırmak ister misiniz? ┐
 │ ● Evet / ○ Hayır                                                          │
 └───────────────────────────────────────────────────────────────────────┘

Eğer aşağıdakini görüyorsanız, kurulum tamamdır:

 Uygulama hazır işte [Your_App]. Yerel gelişmeye başlayabilirsiniz:

 ➜ cd Your_App
 ➜ composer run dev

 Laravel'a yeni misiniz? Belgelerimize göz atın. Harika bir şey inşa edin!

Başlatmayı Doğrulayın

cd Your_App
composer dev

Geliştirme sunucusunu başlatın ve http://localhost:8000 adresine erişin. İlk açılışta muhtemelen bir veritabanı bağlantı hatası alacaksınız.

Eğer SQLite yeterliyse, diğer bir terminalde şu komutu çalıştırın:

php artisan migrate:fresh --seed --force

Sayfayı yeniden yükleyin ve uygulama çalışmaya başlamalıdır.

Japonca’ya Geçiş

Bu noktada, uygulama hala İngilizce. Ancak, bu fork zaten Kurulum sırasında lang/ dizinine Japonca kaynaklar yükler (diğer dillerin eklenmesi sonraki bölümde açıklanmıştır).

% tree lang
lang
├── en
│   ├── actions.php
│   ├── auth.php
│   ├── http-statuses.php
│   ├── pagination.php
│   ├── passwords.php
│   └── validation.php
├── en.json
├── ja
│   ├── actions.php
│   ├── auth.php
│   ├── http-statuses.php
│   ├── pagination.php
│   ├── passwords.php
│   └── validation.php
├── ja.json
└── vendor-patches
    ├── locales
    │   └── ja.json
    └── source
        └── react.json

Tek yapmanız gereken .env dosyasını değiştirmektir.

#APP_LOCALE=en
APP_LOCALE=ja
APP_FALLBACK_LOCALE=en
APP_FAKER_LOCALE=en_US

Çalıştırılan geliştirme sunucusunu composer dev ile yeniden başlatın ve uygulama Japonca’ya geçecektir.

Yerelleştirilmiş giriş ekranı

Aşağıdaki seeded hesapla giriş yapabilirsiniz: [email protected] / password.

Giriş yaptıktan sonra ekran

Ayarlar sayfası da yerelleştirilmiştir

Çok Dilli Geliştirme için Önerilen İş Akışı

Geliştirme sırasında uluslararasılaşmayı korumak için UI dizelerini __() yardımcı fonksiyonunu kullanarak yazmalısınız. Bu fonksiyonu doğrudan React bileşenleri içinde kullanabilirsiniz (çeviriler, Inertia paylaşılan prop’larıyla sağlanır).

import { lang } from '@erag/lang-sync-inertia/react';
// ...
export default function Login({ status, canResetPassword }: Props) {
    const { __ } = lang();
    // ...
    {__('Yedek Dil (İngilizce)')}

Gerçek kullanım örneği için:

https://github.com/catatsumuri/react-starter-kit-i18n/blob/main/resources/js/pages/auth/login.tsx#L116-L121

Bir anahtar için çeviri yoksa, İngilizce yedek yerel dil görüntülenir, bu yüzden hiçbir şey bozulmaz. Çok dilli destek gerektirmeyen projeler için, yerelleştirilmiş dilde doğrudan geliştirme yapmaya devam etmek tamamen kabul edilebilir.

Başka Bir Dil Ekleme – Fransızca Örneği

Japonca, bir Composer betiği aracılığıyla kurulum sırasında otomatik olarak yüklenir, ancak diğer dilleri eklemek de basittir. Çeviri kaynakları iki katmandan oluşmaktadır:

• Temel çeviriler (doğrulama mesajları, kimlik doğrulama hataları vb.) — birçok dil için Laravel Lang tarafından sağlanmaktadır.
• Bu fork’a özel UI dizeleri (örneğin, 2FA ayarları ekranı) — lang/vendor-patches/locales/{locale}.json içinde saklanır.

Fransızca eklemek için, lang/vendor-patches/locales/ja.json dosyasına dayanarak bir fr.json dosyası oluşturun.

cat lang/vendor-patches/locales/fr.json
{
    "Navigasyon menüsü": "Menu de navigation",
    "Hesabınız silindiğinde, bununla birlikte tüm kaynakları ve verileri de kalıcı olarak silinecektir. Hesabınızın kalıcı olarak silinmesi için lütfen şifrenizi girin.": "Une fois votre compte supprimé, toutes ses ressources et données seront également supprimées définitivement. Veuillez saisir votre mot de passe pour confirmer la suppression définitive de votre compte.",
    "Lütfen dikkatle ilerleyin, bu geri alınamaz.":  "Veuillez procéder avec prudence, cette action est irréversible.",
}

Referans (gerçek bir uygulama locale-switcher dalında bulunmaktadır):

https://github.com/catatsumuri/react-starter-kit-i18n/blob/feature/locale-switcher/lang/vendor-patches/locales/fr.json

Çeviriler eksik olsa bile, eksik anahtarlar İngilizceye geri döner. Dosyayı oluşturduktan sonra yamayı uygulayın ve dil dosyalarını yeniden oluşturun.

composer patch-vendor
php artisan lang:update

% php artisan lang:update

   INFO  Collecting translations...

  LaravelLang\Actions\Plugin ................................. 2.42ms DONE
  LaravelLang\Lang\Plugin ................................... 16.39ms DONE
  LaravelLang\StarterKits\Plugin ............................. 2.52ms DONE

   INFO  Storing changes...

  fr.json ................................................... 10.80ms DONE
  fr/actions.php ............................................. 6.17ms DONE
  fr/auth.php ................................................ 0.29ms DONE
  fr/validation.php ......................................... 14.22ms DONE
  (en / ja da yeniden oluşturulmuştur)

Bu, lang/fr.json ve lang/fr/*.php dosyalarını oluşturur. Ardından, yalnızca .env dosyasını güncelleyin ve geliştirme sunucusunu yeniden başlatın.

#APP_LOCALE=en
#APP_LOCALE=ja
APP_LOCALE=fr
APP_FALLBACK_LOCALE=en
APP_FAKER_LOCALE=en_US

Fransızca’ya geçildi

Bonus: Yerel Değiştirici (Dil Değiştirme UI)

Uygulama içinde dilleri doğrudan değiştirmek için bir UI de, feature/locale-switcher dalında mevcuttur.

Yerel değiştirici demosu

Bu daldan doğrudan yüklemek için, URL’ye #branch-name ekleyin.

laravel new Your_App --using=https://github.com/catatsumuri/react-starter-kit-i18n#feature/locale-switcher

Referans olarak, Laravel Cloud’da nasıl yapılandırıldığını inceleyebilirsiniz.

Kapanış Düşünceleri

Bu başlangıç kitlerinin üst akış değişiklikleri ile mümkün olduğunca uyumlu kalmasını planlıyorum. Ancak, eğer resmi çeviri desteği eklenirse, bu depoları terkedebilirim.

Bunu motive eden sorun:

https://github.com/laravel/maestro/issues/168

Bunun en iyi uygulamasını içten içe tartışıyoruz.

Çeviri Adaptörü Hakkında

Laravel ve ön yüz arasında çeviri senkronizasyonu için bu proje erag/laravel-lang-sync-inertia kullanmaktadır.

https://packagist.org/packages/erag/laravel-lang-sync-inertia

Ayrıca, Er Amit Gupta’ya Svelte adaptörü ve düz anahtar desteği ile ilgili PR’leri birleştirdiği için teşekkür ederim.