Unicod...Locale(3perl)

📦

version 5.44.0 · 14 versions

💖 Unicode::Collate::Locale 💖

okay bestie, buckle up — this is the manual page for Unicode::Collate::Locale from the Perl Programmers Reference Guide (that's the (3perl) one, iykyk). It's a big one and it comes in two parts, so we're doing part 1 right now, no skipping, no skimming. 💅

✨ NAME ✨

Unicode::Collate::Locale — Linguistic tailoring for DUCET via Unicode::Collate

🌸 SYNOPSIS 🌸

use Unicode::Collate::Locale;

#construct
$Collator = Unicode::Collate::Locale->
    new(locale => $locale_name, %tailoring);

#sort
@sorted = $Collator->sort(@not_sorted);

#compare
$result = $Collator->cmp($a, $b); # returns 1, 0, or -1.

Note: the strings in @not_sorted, $a and $b are read according to Perl's Unicode support. Go read perlunicode, perluniintro, perlunitut, perlunifaq, and utf8 for the lore. Otherwise you can use "preprocess" (check "Unicode::Collate") or you should decode them before you hand them over. 🔥

🦋 DESCRIPTION 🦋

This module gives you linguistic tailoring by being a total freeloader off "Unicode::Collate" (affectionate). 💖

🎀 Constructor 🎀

The "new" method hands you back a collator object, as it should.

The parameter list for the constructor is a hash, and it can hold a special key "locale" plus its value (case-insensitive) that stands for a Unicode base language code — two or three letters, bestie. So like, "Unicode::Collate::Locale->new(locale => 'ES')" returns you a collator that's tailored for Spanish. 🫶

$locale_name can also be suffixed with a Unicode script code (four letters), a Unicode region (territory) code, or a Unicode language variant code. These codes are case-insensitive and separated with '_' or '-'. E.g. "en_US" for English in USA, "az_Cyrl" for Azerbaijani in the Cyrillic script, "es_ES_traditional" for Spanish in Spain (Traditional). Periodt.

If $locale_name isn't available, the fallback gets picked in this exact order:

language with a variant code
language with a script code
language with a region code
language
default

Tailoring tags that "Unicode::Collate" provides are allowed, as long as they're not being used for "locale" support. Esp. the "table" tag is always untailorable, because it is reserved for DUCET — hands off. 🚫

But "entry" is allowed, even if it's used for "locale" support, so you can add or override mappings.

E.g. a collator for Spanish that ignores diacritics and case difference (i.e. level 1), with reversed case ordering and no normalization:

Unicode::Collate::Locale->new(
    level => 1,
    locale => 'es',
    upper_before_lower => 1,
    normalization => undef
)

Overriding a behavior that's already tailored by "locale" is disallowed if that tailoring gets passed to new(). Not me finding out the hard way:

Unicode::Collate::Locale->new(
    locale => 'da',
    upper_before_lower => 0, # causes error as reserved by 'da'
)

However, change() — inherited from "Unicode::Collate" — does allow that kind of tailoring, even when "locale" has reserved it. Examples:

new(locale => 'fr_ca')->change(backwards => undef)
new(locale => 'da')->change(upper_before_lower => 0)
new(locale => 'ja')->change(overrideCJK => undef)

💜 Methods 💜

"Unicode::Collate::Locale" is a subclass of "Unicode::Collate", and literally every method other than "new" is inherited from "Unicode::Collate". Slay, no code duplication. ✨

Here's the list of the extra methods:

$Collator->getlocale — returns a language code that was accepted and is actually being used on collation. If linguistic tailoring isn't provided for a language code you passed (whether on purpose for some languages, or because the implementation is incomplete), this method returns the string 'default', which means no special tailoring at all. 💀
$Collator->locale_version — (Since Unicode::Collate::Locale 0.87) returns the version number (perhaps /\d\.\d\d/) of the locale, same as that of Locale/*.pl.

Note: the Locale/*.pl that a collator uses should be identified by a combination of return values from "getlocale" and "locale_version". Two data points, one identity. 🧚

🌈 A list of tailorable locales 🌈

okay here's the whole roster, every single one, no cuts:

af — Afrikaans
ar — Arabic
as — Assamese
az — Azerbaijani (Azeri)
be — Belarusian
bn — Bengali
bs — Bosnian (tailored as Croatian)
bs_Cyrl — Bosnian in Cyrillic (tailored as Serbian)
ca — Catalan
cs — Czech
cu — Church Slavic
cy — Welsh
da — Danish
de__phonebook — German (umlaut as 'ae', 'oe', 'ue')
de_AT_phonebook — Austrian German (umlaut primary greater)
dsb — Lower Sorbian
ee — Ewe
eo — Esperanto
es — Spanish
es__traditional — Spanish ('ch' and 'll' as a grapheme)
et — Estonian
fa — Persian
fi — Finnish (v and w are primary equal)
fi__phonebook — Finnish (v and w as separate characters)
fil — Filipino
fo — Faroese
fr_CA — Canadian French
gu — Gujarati
ha — Hausa
haw — Hawaiian
he — Hebrew
hi — Hindi
hr — Croatian
hu — Hungarian
hy — Armenian
ig — Igbo
is — Icelandic
ja — Japanese [1]
kk — Kazakh
kl — Kalaallisut
kn — Kannada
ko — Korean [2]
kok — Konkani
lkt — Lakota
ln — Lingala
lt — Lithuanian
lv — Latvian
mk — Macedonian
ml — Malayalam
mr — Marathi
mt — Maltese
nb — Norwegian Bokmal
nn — Norwegian Nynorsk
nso — Northern Sotho
om — Oromo
or — Oriya
pa — Punjabi
pl — Polish
ro — Romanian
sa — Sanskrit
se — Northern Sami
si — Sinhala
si__dictionary — Sinhala (U+0DA5 = U+0DA2,0DCA,0DA4)
sk — Slovak
sl — Slovenian
sq — Albanian
sr — Serbian
sr_Latn — Serbian in Latin (tailored as Croatian)
sv — Swedish (v and w are primary equal)
sv__reformed — Swedish (v and w as separate characters)
ta — Tamil
te — Telugu
th — Thai
tn — Tswana
to — Tonga
tr — Turkish
ug_Cyrl — Uyghur in Cyrillic
uk — Ukrainian
ur — Urdu
vi — Vietnamese
vo — Volapu"k
wae — Walser
wo — Wolof
yo — Yoruba
zh — Chinese
zh__big5han — Chinese (ideographs: big5 order)
zh__gb2312han — Chinese (ideographs: GB-2312 order)
zh__pinyin — Chinese (ideographs: pinyin order) [3]
zh__stroke — Chinese (ideographs: stroke order) [3]
zh__zhuyin — Chinese (ideographs: zhuyin order) [3]

Locales that follow the default UCA rules include am (Amharic) without "[reorder Ethi]", bg (Bulgarian) without "[reorder Cyrl]", chr (Cherokee) without "[reorder Cher]", de (German), en (English), fr (French), ga (Irish), id (Indonesian), it (Italian), ka (Georgian) without "[reorder Geor]", mn (Mongolian) without "[reorder Cyrl Mong]", ms (Malay), nl (Dutch), pt (Portuguese), ru (Russian) without "[reorder Cyrl]", sw (Swahili), zu (Zulu).

🍓 Note 🍓

[1] ja: Ideographs are sorted in JIS X 0208 order. Fullwidth and halfwidth forms are identical to their regular form. The difference between hiragana and katakana is at the 4th level, the comparison also requires "(variable => 'Non-ignorable')", and then "katakana_before_hiragana" has no effect. 😭

[2] ko: Plenty of ideographs are sorted by their reading. Such an ideograph is primary (level 1) equal to, and secondary (level 2) greater than, the corresponding hangul syllable.

[3] zh__pinyin, zh__stroke and zh__zhuyin: implemented alt='short', where a smaller number of ideographs are tailored.

⭐ A list of variant codes and their aliases ⭐

dictionary — alias dict
phonebook — alias phone, phonebk
reformed — alias reform
traditional — alias trad
big5han — alias big5
gb2312han — alias gb2312
pinyin
stroke
zhuyin

Note: 'pinyin' is Han in Latin, 'zhuyin' is Han in Bopomofo. 🧠

🎀 INSTALL 🎀

Installing "Unicode::Collate::Locale" needs Collate/Locale.pm, Collate/Locale/*.pm, Collate/CJK/*.pm and Collate/allkeys.txt. When building, "Unicode::Collate::Locale" doesn't require any of data/*.txt, gendata/*, and mklocale. The tests for "Unicode::Collate::Locale" are named t/loc_*.t. So like, go get your files in order first, bestie — the build is lowkey chill about it. 💅

💖 CAVEAT 💖

okay bestie, before you go feral customizing your locale, there's some stuff you need to know, fr fr. no cap, these are real limitations and you can't just vibe past them.

😭 Tailoring is not maximum

so like, here's the thing — even if a certain letter is tailored, its equivalent would not always be tailored as well as it. it's giving "partial glow-up" energy. for example, even though W is tailored, fullwidth W ("U+FF37"), W with acute ("U+1E82"), etc. are not tailored. so rude of them honestly.

the result may depend on whether source strings are normalized or not, and whether decomposed or composed. nl, that's messy. thus (normalization => undef) is less preferred. 💅

🚫 Collation reordering is not supported

the order of any groups including scripts is not changed. periodt. that's it, that's the whole thing. no reordering for you bestie, the groups stay put. 🛑

📚 Reference

here's the full receipts list, mapping each locale to its based CLDR or other reference. keep it exactly as-is, i don't make the rules:

             locale            based CLDR or other reference
           --------------------------------------------------------------------
             af                30 = 1.8.1
             ar                30 = 28 ("compat" wo [reorder Arab]) = 1.9.0
             as                30 = 28 (without [reorder Beng..]) = 23
             az                30 = 24 ("standard" wo [reorder Latn Cyrl])
             be                30 = 28 (without [reorder Cyrl])
             bn                30 = 28 ("standard" wo [reorder Beng..]) = 2.0.1
             bs                30 = 28 (type="standard": [import hr])
             bs_Cyrl           30 = 28 (type="standard": [import sr])
             ca                30 = 23 (alt="proposed" type="standard")
             cs                30 = 1.8.1 (type="standard")
             cu                34 = 30 (without [reorder Cyrl])
             cy                30 = 1.8.1
             da                22.1 = 1.8.1 (type="standard")
             de__phonebook     30 = 2.0 (type="phonebook")
             de_AT_phonebook   30 = 27 (type="phonebook")
             dsb               30 = 26
             ee                30 = 21
             eo                30 = 1.8.1
             es                30 = 1.9.0 (type="standard")
             es__traditional   30 = 1.8.1 (type="traditional")
             et                30 = 26
             fa                22.1 = 1.8.1
             fi                22.1 = 1.8.1 (type="standard" alt="proposed")
             fi__phonebook     22.1 = 1.8.1 (type="phonebook")
             fil               30 = 1.9.0 (type="standard") = 1.8.1
             fo                22.1 = 1.8.1 (alt="proposed" type="standard")
             fr_CA             30 = 1.9.0
             gu                30 = 28 ("standard" wo [reorder Gujr..]) = 1.9.0
             ha                30 = 1.9.0
             haw               30 = 24
             he                30 = 28 (without [reorder Hebr]) = 23
             hi                30 = 28 (without [reorder Deva..]) = 1.9.0
             hr                30 = 28 ("standard" wo [reorder Latn Cyrl]) = 1.9.0
             hu                22.1 = 1.8.1 (alt="proposed" type="standard")
             hy                30 = 28 (without [reorder Armn]) = 1.8.1
             ig                30 = 1.8.1
             is                22.1 = 1.8.1 (type="standard")
             ja                22.1 = 1.8.1 (type="standard")
             kk                30 = 28 (without [reorder Cyrl])
             kl                22.1 = 1.8.1 (type="standard")
             kn                30 = 28 ("standard" wo [reorder Knda..]) = 1.9.0
             ko                22.1 = 1.8.1 (type="standard")
             kok               30 = 28 (without [reorder Deva..]) = 1.8.1
             lkt               30 = 25
             ln                30 = 2.0 (type="standard") = 1.8.1
             lt                22.1 = 1.9.0
             lv                22.1 = 1.9.0 (type="standard") = 1.8.1
             mk                30 = 28 (without [reorder Cyrl])
             ml                22.1 = 1.9.0
             mr                30 = 28 (without [reorder Deva..]) = 1.8.1
             mt                22.1 = 1.9.0
             nb                22.1 = 2.0   (type="standard")
             nn                22.1 = 2.0   (type="standard")
             nso           [*] 26 = 1.8.1
             om                22.1 = 1.8.1
             or                30 = 28 (without [reorder Orya..]) = 1.9.0
             pa                22.1 = 1.8.1
             pl                30 = 1.8.1
             ro                30 = 1.9.0 (type="standard")
             sa            [*] 1.9.1 = 1.8.1 (type="standard" alt="proposed")
             se                22.1 = 1.8.1 (type="standard")
             si                30 = 28 ("standard" wo [reorder Sinh..]) = 1.9.0
             si__dictionary    30 = 28 ("dictionary" wo [reorder Sinh..]) = 1.9.0
             sk                22.1 = 1.9.0 (type="standard")
             sl                22.1 = 1.8.1 (type="standard" alt="proposed")
             sq                22.1 = 1.8.1 (alt="proposed" type="standard")
             sr                30 = 28 (without [reorder Cyrl])
             sr_Latn           30 = 28 (type="standard": [import hr])
             sv                22.1 = 1.9.0 (type="standard")
             sv__reformed      22.1 = 1.8.1 (type="reformed")
             ta                22.1 = 1.9.0
             te                30 = 28 (without [reorder Telu..]) = 1.9.0
             th                22.1 = 22
             tn            [*] 26 = 1.8.1
             to                22.1 = 22
             tr                22.1 = 1.8.1 (type="standard")
             uk                30 = 28 (without [reorder Cyrl])
             ug_Cyrl           https://en.wikipedia.org/wiki/Uyghur_Cyrillic_alphabet
             ur                22.1 = 1.9.0
             vi                22.1 = 1.8.1
             vo                30 = 25
             wae               30 = 2.0
             wo            [*] 1.9.1 = 1.8.1
             yo                30 = 1.8.1
             zh                22.1 = 1.8.1 (type="standard")
             zh__big5han       22.1 = 1.8.1 (type="big5han")
             zh__gb2312han     22.1 = 1.8.1 (type="gb2312han")
             zh__pinyin        22.1 = 2.0   (type='pinyin' alt='short')
             zh__stroke        22.1 = 1.9.1 (type='stroke' alt='short')
             zh__zhuyin        22.1 = 22    (type='zhuyin' alt='short')
           --------------------------------------------------------------------

and the lil footnote for the starred entries ✨:

[*] http://www.unicode.org/repos/cldr/tags/latest/seed/collation/

👑 AUTHOR 👑

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. slay, that's the license, go off bestie. 💜

🌈 SEE ALSO 🌈

the required reading list, in order, no skimming:

Unicode Collation Algorithm - UTS #10 — <http://www.unicode.org/reports/tr10/>
The Default Unicode Collation Element Table (DUCET) — <http://www.unicode.org/Public/UCA/latest/allkeys.txt>
Unicode Locale Data Markup Language (LDML) - UTS #35 — <http://www.unicode.org/reports/tr35/>
CLDR - Unicode Common Locale Data Repository — <http://cldr.unicode.org/>
Unicode::Collate
Unicode::Normalize

and that's a wrap on Unicod...Locale(3perl) bestie!! 🌸 this was perl v5.44.0, dated 2026-10-17, so you know exactly which era of perl you're reading. go forth and collate responsibly 💖✨

📦 where this page comes from

arch rolling: perl 5.44.0-1 · Artistic-1.0-Perl AND GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms