PHPackages                             hakanakgul/laravel-blade-translate - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. hakanakgul/laravel-blade-translate

ActiveLibrary

hakanakgul/laravel-blade-translate
==================================

Laravel 12 blade için otomatik dil çevirici

v1.0.0(1mo ago)117↓100%MITPHPPHP ^8.2

Since Mar 18Pushed 1mo agoCompare

[ Source](https://github.com/hakanakgul/laravel-blade-translate)[ Packagist](https://packagist.org/packages/hakanakgul/laravel-blade-translate)[ RSS](/packages/hakanakgul-laravel-blade-translate/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (1)Versions (2)Used By (0)

Laravel Blade Translate
=======================

[](#laravel-blade-translate)

Laravel projelerinde çok dilli (i18n) yapıyı sıfır sürtünmeyle kuran, Blade ve PHP dosyalarını otomatik tarayan, Google Translate veya OpenAI ile çeviren ve hazır bir dil seçici bileşeni sunan kapsamlı bir Laravel paketidir.

Geliştirici yalnızca kendi ana dilinde yazar. Gerisi pakete aittir.

---

İçindekiler
-----------

[](#i̇çindekiler)

1. [Kurulum](#kurulum)
2. [Zorunlu Yapılandırma](#zorunlu-yap%C4%B1land%C4%B1rma)
3. [Geliştirici Kullanım Kılavuzu](#geli%C5%9Ftirici-kullan%C4%B1m-k%C4%B1lavuzu)
4. [Konsol Komutları](#konsol-komutlar%C4%B1)
5. [Dil Seçici Bileşeni](#dil-se%C3%A7ici-bile%C5%9Feni)
6. [Modüler Mimari Desteği](#mod%C3%BCler-mimari-deste%C4%9Fi)
7. [Sık Karşılaşılan Sorunlar](#s%C4%B1k-kar%C5%9F%C4%B1la%C5%9F%C4%B1lan-sorunlar)
8. [Paket Geliştiricisi İçin](#paket-geli%C5%9Ftiricisi-i%C3%A7in)

---

Kurulum
-------

[](#kurulum)

```
composer require hakanakgul/laravel-blade-translate
```

Güncelleme için:

```
composer update hakanakgul/laravel-blade-translate
```

Kurulumdan sonra önbelleği temizleyin:

```
php artisan optimize:clear
```

---

Zorunlu Yapılandırma
--------------------

[](#zorunlu-yapılandırma)

### 1. `config/app.php` — Ana Dili Türkçe Olarak Ayarla

[](#1-configappphp--ana-dili-türkçe-olarak-ayarla)

Sistem Türkçeyi kaynak dil olarak kullandığından bu değerlerin doğru olması kritiktir:

```
// config/app.php
'locale'          => 'tr',
'fallback_locale' => 'tr',
```

> **Neden önemli?** Paket `fallback_locale` değerini okuyarak hangi dilin kaynak (ana) dil olduğuna karar verir. Bu değer yanlışsa `tr.json` oluşturulmaz ve middleware yanlış dile düşer.

### 2. `config/languages.php` — Desteklenecek Dilleri Belirle

[](#2-configlanguagesphp--desteklenecek-dilleri-belirle)

Ayar dosyasını projeye çıkartın:

```
php artisan vendor:publish --tag=localization-config
```

Bu komut `config/languages.php` dosyasını projenize kopyalar. **Bundan sonra dil eklemek veya çıkarmak için yalnızca bu dosyayı düzenleyin** — paketteki orijinal dosyaya dokunmayın, değişiklikleriniz yok sayılır.

```
// config/languages.php
return [
    'tr' => ['country' => 'Türkiye',       'language' => 'Türkçe',   'flag_url' => 'https://flagcdn.com/w40/tr.png'],
    'en' => ['country' => 'United States', 'language' => 'English',  'flag_url' => 'https://flagcdn.com/w40/us.png'],
    'de' => ['country' => 'Germany',       'language' => 'Deutsch',  'flag_url' => 'https://flagcdn.com/w40/de.png'],
    // diğer diller...
];
```

Değişiklikten sonra önbelleği temizleyin:

```
php artisan optimize:clear
```

> Bu dosya **yalnızca** hangi dillerin sistemde aktif olacağını ve dil seçicide nasıl gösterileceğini tanımlar. Başka bir şey için kullanılmaz.

### 3. OpenAI Entegrasyonu (İsteğe Bağlı)

[](#3-openai-entegrasyonu-i̇steğe-bağlı)

Google Translate yerine OpenAI kullanmak için `.env` dosyasına ekleyin:

```
OPENAI_API_KEY=sk-...
```

`config/services.php` içinde de tanımlanmış olmalı:

```
'openai' => [
    'key' => env('OPENAI_API_KEY'),
],
```

---

Geliştirici Kullanım Kılavuzu
-----------------------------

[](#geliştirici-kullanım-kılavuzu)

### Temel Prensip

[](#temel-prensip)

Geliştirici her yerde standart Laravel `__()` fonksiyonunu kullanır — Türkçe string ile:

```
__('Hoş Geldiniz')
```

`translate` komutu çalıştırıldığında tüm `__('...')` ifadeleri otomatik bulunur, `tr.json` ve `en.json` güncellenir. Kaynak dosyalara **hiç dokunulmaz**.

---

### Blade Dosyalarında Kullanım

[](#blade-dosyalarında-kullanım)

```
{{ __('Sisteme Hoş Geldiniz') }}
{{ __('Kaydet') }}
{{ __('Merhaba, :name', ['name' => $user->name]) }}

{{-- String içinde tırnak kullanımı sorunsuz çalışır --}}
{{ __("Kullanıcı adı 'zorunlu' bir alandır") }}
{{ __('İşlem "başarıyla" tamamlandı') }}
```

### PHP Dosyalarında Kullanım

[](#php-dosyalarında-kullanım)

Controller, Model, Service veya herhangi bir PHP dosyasında aynı şekilde:

```
// Controller
return response()->json(['message' => __('İşlem başarılı')]);

// Exception
throw new \Exception(__('Kayıt bulunamadı'));

// Validation mesajları
$messages = [
    'email.required' => __('E-posta adresi zorunludur'),
    'email.email'    => __('Geçerli bir e-posta adresi giriniz'),
];

// Mail / Notification
$subject = __('Hesabınız oluşturuldu');
```

> `translate` komutu hem `resources/views/` altındaki `.blade.php` dosyalarını hem de `app/` altındaki tüm `.php` dosyalarını tarar.

---

### Tam İş Akışı

[](#tam-i̇ş-akışı)

**1. Kodu yazın** — her yerde Türkçe `__('...')` kullanın.

**2. Tarama ve çeviri komutunu çalıştırın:**

```
# Sadece tr.json ve en.json güncelle
php artisan translate

# tr.json + en.json güncelle, ardından tüm dillere dağıt
php artisan translate --all

# OpenAI motoru ile
php artisan translate --all --engine=openai

# Önce ne yapacağını gör, dosyalara dokunma
php artisan translate --dry-run
```

**3. Dil seçiciyi layout'a ekleyin:**

```

```

**Bu kadar.** Uygulama artık `config/languages.php`'de tanımlı tüm dilleri destekler.

---

### Yeni Geliştirme Döngüsü

[](#yeni-geliştirme-döngüsü)

Projeye her yeni özellik eklendiğinde tek yapılması gereken:

1. Yeni Türkçe string'leri her zamanki gibi `__('...')` ile yaz
2. Komut çalıştır: `php artisan translate --all`
3. Mevcut çeviriler korunur, sadece yeni olanlar eklenir

---

Konsol Komutları
----------------

[](#konsol-komutları)

### `translate`

[](#translate)

Blade ve PHP dosyalarını tarar. `tr.json` ve `en.json` dosyalarını oluşturur veya günceller. **Kaynak dosyalara dokunmaz.**

```
php artisan translate [seçenekler]
```

SeçenekAçıklama`--all`Bittikten sonra `translate:all` komutunu otomatik tetikler`--engine=google`Çeviri motoru: `google` (varsayılan) veya `openai``--dry-run`Nelerin ekleneceğini gösterir, hiçbir şey yazmaz`--module=AdModul`Modül modunda çalışır (Laravel Modules)**Nasıl çalışır:**

1. `resources/views/` → tüm `.blade.php` dosyaları taranır
2. `app/` → tüm `.php` dosyaları taranır (`.blade.php` hariç)
3. `__('...')` ifadeleri yakalanır, kaçış karakterleri çözülür
4. `tr.json`'da olmayan yeni string'ler Türkçe'den İngilizce'ye çevrilir
5. `lang/tr.json` güncellenir (key = value = Türkçe)
6. `lang/en.json` güncellenir (key = Türkçe, value = İngilizce)

---

### `translate:all`

[](#translateall)

`en.json` içeriğini `config/languages.php`'de tanımlı tüm dillere çevirir. `tr` ve `en` otomatik atlanır.

```
php artisan translate:all [seçenekler]
```

SeçenekAçıklama`--lang=de`Sadece belirli bir dile çevir`--engine=google`Çeviri motoru: `google` (varsayılan) veya `openai``--source=en`Kaynak JSON dosyası (varsayılan: `en`)`--module=AdModul`Modül modunda çalışır**Davranış:** Hedef dil dosyasında zaten mevcut olan anahtarları atlar. Sadece eksik olanları çevirir. Bu sayede mevcut çevirilerin üzerine yazılmaz.

---

### `translate:prepare`

[](#translateprepare)

Eski `{_t(value="...")}` etiket formatını kullanan mevcut projeleri sisteme dahil etmek için kullanılan **migration aracıdır.** Bu etiketleri standart `{{ __('...') }}` formatına dönüştürür.

```
php artisan translate:prepare [--module=AdModul]
```

> Yeni projelerde bu komuta gerek yoktur. Yalnızca eski format kullanan dosyaları güncellemek için çalıştırılır.

**Desteklenen eski formatlar:**

- `{_t(value="Metin")}` → `{{ __('Metin') }}`
- `{{ _t($value="Metin") }}` → `{{ __('Metin') }}`

Dönüşüm tamamlandıktan sonra `translate` çalıştırılmalıdır.

---

Dil Seçici Bileşeni
-------------------

[](#dil-seçici-bileşeni)

Hazır dil değiştirme menüsünü herhangi bir Blade dosyasına ekleyin:

```

```

**Özellikler:**

- Sıfır JavaScript/CSS bağımlılığı — tamamen vanilla
- Shadow DOM ile stil izolasyonu (uygulama stilleriyle çakışmaz)
- Arama desteği (Türkçe karakter duyarsız: `o` yazınca `ö` de bulunur)
- Her dil için bayrak, ülke adı ve dil adı gösterimi
- Dil değiştirildiğinde `locale-change` custom event'i tetiklenir

**Tasarımı Özelleştirme:**

```
php artisan vendor:publish --tag=localization-views
```

Bileşen `resources/views/vendor/localization/components/selector.blade.php` konumuna kopyalanır. Orijinal dosya güncellense bile artık projedeki kopya kullanılır.

---

Modüler Mimari Desteği
----------------------

[](#modüler-mimari-desteği)

nWidart/laravel-modules gibi HMVC yapısı kullanan projelerde her modülün çevirileri izole tutulabilir:

```
# Modülü tara ve çevir
php artisan translate --all --module=Kutuphane

# Sadece belirli dile çevir
php artisan translate:all --lang=de --module=Kutuphane
```

**Modül modu dizin yapısı:**

```
Modules/Kutuphane/
├── Resources/
│   ├── views/          ← blade taraması buradan
│   └── lang/
│       ├── tr.json     ← oluşturulur
│       ├── en.json     ← oluşturulur
│       └── de.json     ← translate:all ile oluşturulur
└── Http/               ← php taraması buradan (tüm alt dizinler)

```

Modül çevirileri ana projenin `lang/` klasörüne kesinlikle dokunmaz.

---

Sık Karşılaşılan Sorunlar
-------------------------

[](#sık-karşılaşılan-sorunlar)

**Çeviriler görünmüyor veya hata var:**

```
php artisan optimize:clear
php artisan view:clear
```

**`tr.json` oluşturulmuyor:**`config/app.php` dosyasında `fallback_locale` değerinin `'tr'` olduğundan emin olun.

**`en.json` bulunamadı hatası (`translate:all`):**`translate:all` komutunu çalıştırmadan önce `translate` çalıştırılmış olmalıdır. `en.json` bu komutla oluşturulur.

**PHP dosyalarındaki çeviriler taranmıyor:**Tarama `app/` dizinini kapsar. Bu dizin dışında bir yerde PHP dosyanız varsa (örn. `domain/`) `translate` onu görmez — dosyayı `app/` altına taşıyın veya geliştirici rehberinin ilgili bölümüne bakın.

**Dil seçicideki diller fazla veya eksik:**`config/languages.php` dosyasını kontrol edin. Değişiklikten sonra `php artisan optimize:clear` çalıştırın.

---

Paket Geliştiricisi İçin
------------------------

[](#paket-geliştiricisi-i̇çin)

Bu bölüm paketin kaynak kodunu geliştiren yazılımcılara yöneliktir.

### Mimari Genel Bakış

[](#mimari-genel-bakış)

```
src/
├── Console/Commands/
│   ├── ChangeTranslateKeywordCommand.php   → translate
│   ├── TranslateToLanguageCommand.php      → translate:all
│   └── TranslatePrepareCommand.php         → translate:prepare
├── Http/Middleware/
│   └── LocalizationMiddleware.php          → Her request'te locale ayarlar
├── Services/
│   └── Translate.php                       → Google Translate & OpenAI adaptörü
├── resources/views/
│   └── selector.blade.php                  → Dil seçici bileşeni
├── routes/
│   └── web.php                             → /lang/{locale} rotası
├── config/
│   └── languages.php                       → Varsayılan dil tanımları
└── LocalizationServiceProvider.php         → Paket bootstrap

```

### Temel Tasarım Kararları

[](#temel-tasarım-kararları)

**Neden `{_t(...)}` değil de `__('...')` taranıyor?**Önceki tasarımda özel etiketler blade dosyalarına yazılıyor, komut çalışınca standart formata dönüştürülüyordu. Bu yaklaşım dosyaları değiştirdiği için geri alınamaz ve PHP dosyalarında kullanılamaz. Mevcut tasarımda hiçbir kaynak dosya değiştirilmez — komut yalnızca `lang/` dizinini yönetir.

**Neden pivot dil olarak İngilizce kullanılıyor?**`tr → en → diğer diller` zinciri tercih edildi. Bunun sebebi Google Translate ve OpenAI'nin en yüksek kaliteli çeviriyi İngilizce üzerinden vermesidir. Türkçe'den doğrudan Japonca'ya gitmek yerine Türkçe → İngilizce → Japonca yolu daha doğal sonuçlar üretir.

**`tr.json` neden identity map (key = value)?**Laravel `__('Merhaba')` çağrısında aktif locale'in JSON dosyasını arar. Locale `tr` iken `tr.json`'da `"Merhaba": "Merhaba"` yoksa Laravel string'i olduğu gibi döner — bu aslında çalışır. Ancak `tr.json`'u açıkça oluşturmak, eksik çeviri tespitini (`translate:status` gibi bir komut için) mümkün kılar ve sistemin tutarlı davranmasını sağlar.

### Regex Deseni

[](#regex-deseni)

Tüm tarama komutlarında kullanılan merkezi desen:

```
/__\(\s*(['"])((?:[^\\]|\\.)*?)\1/

```

ParçaAnlamı`__\(`Literal `__(``\s*`İsteğe bağlı boşluk`(['"])`Açılış tırnak — grup 1`((?:[^\\]|\\.)*)`String içeriği — grup 2`[^\\]`Backslash olmayan herhangi bir karakter`\\.`Backslash + herhangi bir karakter (kaçış ifadesi)`\1`Backreference: açılış tırnak ile aynı tırnak ile kapatYakalanan ham metin `stripslashes()` ile işlenir. Bu sayede `__('it\'s fine')` → JSON key `it's fine` olur.

### Çeviri Akışı

[](#çeviri-akışı)

```
translate çalışır
    │
    ├─ resources/views/**/*.blade.php  ──┐
    │                                    ├─→ __('...') regex ile taranır
    ├─ app/**/*.php (blade hariç)      ──┘
    │
    ├─ tr.json yüklenir (mevcut)
    ├─ Fark alınır → yeni string'ler belirlenir
    │
    ├─ Her yeni string için:
    │       Türkçe → Google/OpenAI → İngilizce
    │
    ├─ tr.json güncellenir (identity map)
    └─ en.json güncellenir (key=Türkçe, value=İngilizce)

translate:all çalışır
    │
    ├─ en.json okunur
    ├─ tr ve en atlanır (kaynak + ana dil)
    └─ Her hedef dil için:
            İngilizce → Google/OpenAI → Hedef dil JSON

```

### Yeni Dil Motoru Eklemek

[](#yeni-dil-motoru-eklemek)

`Translate` servisi adaptör deseni ile genişletilebilir. Yeni bir motor eklemek için:

1. `Translate.php` içine `private function translateWithXxx(...)` metodu ekle
2. Constructor'daki `match` bloğuna yeni motoru ekle
3. Komutlardaki `--engine` açıklamasını güncelle

### Dikkat Edilmesi Gerekenler

[](#dikkat-edilmesi-gerekenler)

- `languages.php` sadece dil tanımları içerir. Teknik yapılandırma (scan path, engine config vb.) buraya girmez.
- `translate:all` komutu `tr` ve `en`'i otomatik atlar. Bu dilleri manuel olarak `--lang` ile geçmek zararsızdır, komut onları işlemeden geçer.
- `fallback_locale` her zaman `config('app.fallback_locale', 'tr')` üzerinden okunur. Hardcoded `'tr'` kullanılmaz.
- `matchesType()` metodu `blade` ve `php` türlerini birbirinden ayırır. Blade dosyaları PHP taramasına dahil edilmez — her dosya yalnızca bir kez taranır.

---

Lisans
------

[](#lisans)

MIT — dilediğiniz gibi kullanabilir, değiştirebilir ve dağıtabilirsiniz.

###  Health Score

40

—

FairBetter than 88% of packages

Maintenance89

Actively maintained with recent releases

Popularity10

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

56d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/1ee8104c963a979596448fbbe1e084c2f2c5cce79086d65e2679a5afb3d2ab26?d=identicon)[hakanakgul](/maintainers/hakanakgul)

---

Top Contributors

[![hakanakgul](https://avatars.githubusercontent.com/u/25103259?v=4)](https://github.com/hakanakgul "hakanakgul (4 commits)")

### Embed Badge

![Health badge](/badges/hakanakgul-laravel-blade-translate/health.svg)

```
[![Health](https://phpackages.com/badges/hakanakgul-laravel-blade-translate/health.svg)](https://phpackages.com/packages/hakanakgul-laravel-blade-translate)
```

###  Alternatives

[tanmuhittin/laravel-google-translate

Translate translation files to other languages using google translate api

4312.2M11](/packages/tanmuhittin-laravel-google-translate)[devaslanphp/auto-translate

Auto generate translation JSON files

6623.1k](/packages/devaslanphp-auto-translate)[web64/laravel-nlp

Laravel package for accessing NLP tools

5711.2k](/packages/web64-laravel-nlp)[hpolthof/laravel-translations-db

A database translations implementation for Laravel 5.

545.8k](/packages/hpolthof-laravel-translations-db)[enupal/translate

Translate your website templates and plugins into multiple languages. Bulk translation with Google Translate or Yandex.

1172.1k](/packages/enupal-translate)[mmoreram/translation-server

PHP translation server

233.7k2](/packages/mmoreram-translation-server)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)