view release on metacpan or  search on metacpan

docs/EN.AmberDB-Locale_User-Guide.md  view on Meta::CPAN

[Home](index.html)  â€¢  [About](EN.About_AmberDB.html)  â€¢  [Quick Start](index.html#quick-start)  â€¢  [Tutorial](EN.AmberDB_User-Guide.html)  â€¢  [Benchmark](EN.AmberDB-vs-SQLite_Benchmark.html)  â€¢&...

---

# AmberDB::Locale - Comprehensive Guide

## 1. Overview

`AmberDB::Locale` is a **locale-aware text processing engine** designed for multilingual applications. Written in Perl, it provides the following core capabilities:

| Capability | Description |
|---|---|
| Case conversion | Locale-aware `uc`, `lc`, `ucfirst` |
| Sorting | Unicode Collation Algorithm (UCA) based |
| ASCII transliteration | Convert accented characters to plain ASCII (slugs, IDs) |
| Number → Text | Written-out numbers for invoices/documents |
| Date/time formatting | Locale-specific date formats |
| Number/currency formatting | Grouping separators, decimal separators, symbol placement |
| HTML entity decoding | Named + numeric entity decode |
| Plural rules | CLDR-based plural form selection |
| UTF-8 safe substring | Character-based slicing (not byte-based) |

**Architectural principle:** Engine logic lives in `AmberDB::Locale.pm`, while language data resides in `AmberDB::Locale::Lang::*` packages as **pure data**. Engine and data are completely separated.

---

## 2. Architecture

```
AmberDB::Locale                 ← Main engine (all logic here)
├── AmberDB::Locale::Lang::gb   ← Global Base data (default/fallback)
├── AmberDB::Locale::Lang::en   ← English data
├── AmberDB::Locale::Lang::tr   ← Turkish data
├── AmberDB::Locale::Lang::de   ← German data
├── AmberDB::Locale::Lang::fr   ← French data
├── AmberDB::Locale::Lang::es   ← Spanish data
├── AmberDB::Locale::Lang::ru   ← Russian data
├── AmberDB::Locale::Lang::az   ← Azerbaijani data
├── AmberDB::Locale::Lang::ar   ← Arabic data
├── AmberDB::Locale::Lang::ja   ← Japanese data
└── AmberDB::Locale::Currency   ← ISO 4217 universal currency data
```

Each `Lang::*` module contains only a single subroutine called `data()` and returns a hash-ref. **No logic is included.**

---

## 3. Object Construction (Constructor)

```perl
use AmberDB::Locale;

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

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

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

# 4) No args → defaults to "gb" (Global Base)
my $lang = AmberDB::Locale->new();
```

### Internal behaviors

- **Caching:** A second `new()` call for the same language returns the existing instance (singleton-like).
- **Alias support:** Labels like `"global"`, `"gl"`, `"turkish"`, `"tr_tr"`, `"tr-tr"` are automatically mapped to canonical codes.
- **Fallback:** If an unknown language is requested, a `cluck` warning is emitted and it falls back to `gb`.
- **Collator:** Attempts to load `Unicode::Collate::Locale`; if it fails, falls back to base `Unicode::Collate`, and if that's also unavailable, uses a custom `sort_map` Schwartzian transform.

### AmberDB integration

```perl
# Language is automatically pulled from cfg
my $db = AmberDB->new(cfg => { language => "tr" });
$db->uc("ığdır");   # works via inheritance: IĞDIR
```