view release on metacpan or  search on metacpan

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

# 3. İnceltme / Düzeltme işaretleri
$tr->normalize_word("kârın");       # "karin"
$tr->normalize_word("ÂLÎM");        # "alim"

# 4. Kelime sonu ötümsüzleşme (Sertleşme / Fonetik dönüşüm)
$tr->normalize_word("tevhid");      # "tevhit"  (d$ => t)
$tr->normalize_word("gazab");       # "gazap"   (b$ => p)
$tr->normalize_word("mehmed");      # "mehmet"  (d$ => t)
```

#### `search_pattern($query)`

Arama sorgusu için çok dilli, esnek ve fonetik regex arama kalıpları derler:

```perl
my $pattern = $tr->search_pattern("Türkiye");
# "t[uü]rk[iıİI]y[eE]" gibi Türkçe ve ASCII varyantlarını kapsayan fonetik desen üretir
```

#### `search_regex($string, $pattern)`

Hedef metin (`$string`) içerisinde arama kalıbının (`$pattern`) locale kurallarıyla eşleşip eşleşmediğini kontrol eder. Eşleşirse `1`, eşleşmezse `0` döner:

```perl
my $bulundu = $tr->search_regex("İstanbul Boğazı", "istanbul"); # 1
my $eslesti = $tr->search_regex("Ä°zmir Kordon", $pattern);      # 1
```

---

### 5.7 HTML Entity Çözümleme

#### `decode_entities($string)`

```perl
$lang->decode_entities("& < > € € ç");
# "& < > € € ç"
```

Üç aşama:
1. **Hex numerik:** `&#x20AC;` → `€`
2. **Desimal numerik:** `&#8364;` → `€`
3. **Named entity'ler:** Evrensel set (`&amp;`, `&lt;`, `&nbsp;`, `&euro;`, vb.) + locale'e özgü ekler (`&ccedil;`, `&scaron;`, `&gbreve;`, vb.)

---

### 5.8 UTF-8 Güvenli Substring

#### `substring($string, [$offset], $length)`

```perl
my $tr = AmberDB::Locale->new(language => "tr");
$tr->substring("Çanakkale", 0, 4);     # "Çana"  (4 karakter, 4 byte değil!)
$tr->substring("Ä°stanbul", 2, 3);      # "tan"

# Raw UTF-8 byte string ile de güvenli:
my $raw = encode('UTF-8', "Şanlıurfa");
$tr->substring($raw, 0, 5);            # "Şanlı" (doğru şekilde re-encode edilir)
```

> `Encode::is_utf8()` ile string'in decode edilip edilmediği kontrol edilir. Raw byte ise `decode → substr → encode` zinciri uygulanır; böylece multibyte karakterler ortadan kesilmez.

---

### 5.9 Tarih/Saat Ä°ÅŸlemleri

#### `format_date($time [, $pattern_or_style])`

```perl
my $tr = AmberDB::Locale->new(language => "tr");
my $epoch = time();   # örn: 2026-08-09

$tr->format_date($epoch);                    # "09.08.2026"
$tr->format_date($epoch, 'medium');          # "9 AÄŸu 2026"
$tr->format_date($epoch, 'long');            # "9 AÄŸustos 2026"
$tr->format_date($epoch, 'full');            # "Pazar, 9 AÄŸustos 2026"
$tr->format_date($epoch, 'time');            # "14:30"
$tr->format_date($epoch, 'datetime');        # "09.08.2026 14:30"

# Özel pattern
$tr->format_date($epoch, 'YYYY-MM-DD');     # "2026-08-09"
$tr->format_date($epoch, 'DD/MM/YYYY');     # "09/08/2026"

# Tarih string'i de kabul eder
$tr->format_date("2026-08-09", 'full');     # "Pazar, 9 AÄŸustos 2026"
```

**Desteklenen token'lar:**

| Token | Anlam | Örnek |
|---|---|---|
| `YYYY` / `YY` | 4/2 haneli yıl | 2026 / 26 |
| `MMMM` / `MMM` / `MM` / `M` | Ay adı / kısa / 2 haneli / tek | Ağustos / Ağu / 08 / 8 |
| `DD` / `D` | Gün (2 haneli / tek) | 09 / 9 |
| `dddd` / `ddd` | Gün adı / kısa | Pazar / Paz |
| `HH` / `H` | Saat | 14 / 14 |
| `mm` / `m` | Dakika | 05 / 5 |
| `ss` / `s` | Saniye | 09 / 9 |

**Kabul edilen giriş formatları:**
- Unix timestamp: `1786345200`
- Tarih string'i: `2026-08-09`, `2026/08/09`, `2026.08.09`
- Tarih + saat: `2026-08-09 14:30:00`, `2026-08-09T14:30`

#### `parse_date($string [, %opts])`

```perl
my $epoch = $tr->parse_date("09.08.2026");            # Unix timestamp
my $h     = $tr->parse_date("09.08.2026", hash => 1);
# { year => 2026, month => 8, day => 9, hour => 0, minute => 0, second => 0 }
```

> Kısa tarih formatı locale'in `date_format.short` değerine göre `GG.AA.YYYY` mı yoksa `AA/GG/YYYY` mı olduğu otomatik tespit edilir.

---

### 5.10 Sayı ve Para Birimi Biçimlendirme

#### `format_number($num [, %opts])`

```perl