view release on metacpan or  search on metacpan

docs/TR.AmberDB-Locale_Kullanim_Rehberi.md  view on Meta::CPAN

`AmberDB::Locale`, çok dilli uygulamalar için tasarlanmış **yerel (locale) duyarlı bir metin işleme motorudur**. Perl dilinde yazılmış olup aşağıdaki temel yetenekleri sunar:

| Yetenek | Açıklama |
|---|---|
| Büyük/küçük harf dönüşümü | Dil kurallarına uygun `uc`, `lc`, `ucfirst` |
| Sıralama | Unicode Collation Algorithm (UCA) tabanlı |
| ASCII dönüşümü | Aksanlı karakterleri düz ASCII'ye çevirme (slug, ID üretimi) |
| Sayı → Metin | Fatura/belge yazımı için sayıların yazıyla ifadesi |
| Tarih/saat biçimlendirme | Locale özgü tarih formatları |
| Sayı/para birimi biçimlendirme | Binlik ayraç, ondalık ayraç, sembol yerleşimi |
| HTML entity çözümleme | Named + numeric entity decode |
| Çoğul kuralları | CLDR tabanlı plural form seçimi |
| UTF-8 güvenli substring | Karakter bazlı kesme (byte değil) |

**Mimari prensip:** Motor mantığı `AmberDB::Locale.pm`'de, dil verileri ise `AmberDB::Locale::Lang::*` paketlerinde **saf data** olarak tutulur. Motor ve veri tamamen ayrılmıştır.

---

## 2. Mimari

```
AmberDB::Locale                 ← Ana motor (tüm mantık burada)
├── AmberDB::Locale::Lang::gb   ← Global Base veri (varsayılan/fallback)
├── AmberDB::Locale::Lang::en   ← İngilizce veri
├── AmberDB::Locale::Lang::tr   ← Türkçe veri
├── AmberDB::Locale::Lang::de   ← Almanca veri
├── AmberDB::Locale::Lang::fr   ← Fransızca veri
├── AmberDB::Locale::Lang::es   ← İspanyolca veri
├── AmberDB::Locale::Lang::ru   ← Rusça veri
├── AmberDB::Locale::Lang::az   ← Azerice veri
├── AmberDB::Locale::Lang::ar   ← Arapça veri
├── AmberDB::Locale::Lang::ja   ← Japonca veri
└── AmberDB::Locale::Currency   ← ISO 4217 evrensel para birimi verisi
```

Her `Lang::*` modülü yalnızca `data()` adlı tek bir subroutine içerir ve bir hash-ref döndürür. **Hiçbir mantık barındırmaz.**

---

## 3. Nesne OluÅŸturma (Constructor)

```perl
use AmberDB::Locale;

# 1) Named-param API (önerilen)
my $lang = AmberDB::Locale->new(language => "tr");

# 2) Hashref API
my $lang = AmberDB::Locale->new({ language => "de" });

# 3) Pozisyonel string API
my $lang = AmberDB::Locale->new("fr");

# 4) Argümansız → varsayılan "gb" (Global Base)
my $lang = AmberDB::Locale->new();
```

### Dahili davranışlar

- **Önbellekleme:** Aynı dil için ikinci `new()` çağrısı mevcut nesneyi döndürür (singleton benzeri).
- **Alias desteÄŸi:** `"global"`, `"gl"`, `"turkish"`, `"tr_tr"`, `"tr-tr"` gibi etiketler otomatik olarak eÅŸlenir.
- **Fallback:** Bilinmeyen bir dil istenirse `cluck` ile uyarı verilir ve `gb`'ye düşülür.
- **Collator:** `Unicode::Collate::Locale` yüklenmeye çalışılır; başarısız olursa `Unicode::Collate` tabanına, o da yoksa özel `sort_map` Schwartzian transform'una düşülür.

### AmberDB entegrasyonu

```perl
# cfg üzerinden dil otomatik çekilir
my $db = AmberDB->new(cfg => { language => "tr" });
$db->uc("ığdır");   # kalıtım yoluyla çalışır
```

---

## 4. Dil Veri Yapısı (`data()` Hash-Ref)

Her dil modülünün döndürdüğü yapının tam şeması:

```perl
{
    uc_map          => { },   # uc() öncesi karakter eşleme
    lc_map          => { },   # lc() öncesi karakter eşleme
    sort_map        => { },   # Özel sıralama ağırlıkları (collator yoksa)
    alphabet_chars  => "...",  # normalize() için güvenli karakter sınıfı
    accent_map      => { },   # normalize() aksan → yerel eşdeğer
    ascii_map       => { },   # to_ascii() NFD öncesi ön eşleme
    numbers         => { },   # num2text sayı kelimeleri
    html_entities   => { },   # Locale'e özgü ek HTML entity'ler
    months          => [ ],   # 12 elemanlı ay adları
    days            => [ ],   # 7 elemanlı gün adları (Pazar → Cumartesi)
    number_format   => { },   # Ondalık/binlik ayraç ayarları
    default_currency    => "",
    currency_position   => "prefix|suffix",
    currency_space      => 0|1,
    date_format     => { },   # short, medium, long, full, time, datetime
    plural_rule     => "...", # CLDR çoğul kural ifadesi
}
```

---

## 5. Public API - Metot Referansı

### 5.1 Büyük/Küçük Harf Dönüşümleri

#### `uc($string)` - Büyük harfe çevir

```perl
my $tr = AmberDB::Locale->new(language => "tr");
$tr->uc("ığdır");       # "IĞDIR"
$tr->uc("istanbul");    # "İSTANBUL"  (i → İ, Türkçe kural)

my $de = AmberDB::Locale->new(language => "de");
$de->uc("straße");      # "STRASSE"   (ß → SS)
```

> **Türkçe detay:** `uc_map` içinde `'i' => "\x{130}"` eşlemesi Perl'in `CORE::uc()` çağrısından **önce** uygulanır. Böylece `i → İ` dönüşümü doğru yapılır.

#### `lc($string)` - Küçük harfe çevir

```perl