/ 
Time-Keeper-0.12
/ Time::Keeper::Locale

NAME

Time::Keeper::Locale - what CLDR says of every locale Time::Keeper knows

VERSION

Version 0.11

SYNOPSIS

use Time::Keeper::Locale;

my @codes = Time::Keeper::Locale->codes;                  # 1121 of them
Time::Keeper::Locale->name('fr_CA');                      # French (Canada)
Time::Keeper::Locale->native_name('fr-CA');               # français (Canada)
Time::Keeper::Locale->first_day_of_week('en-GB');         # 1, Monday
Time::Keeper::Locale->names('de', 'months', 'abbreviated');
Time::Keeper::Locale->cldr_version;                       # 48.2.3

DESCRIPTION

The calendar names and formats a Time::Keeper value uses come from the Unicode Common Locale Data Repository (CLDR). This module answers questions about that data without a value.

Every method is a class method and takes a locale's code first. A code is matched without regard to case, with _ taken as -: fr_CA, fr-ca and fr-CA are one locale. Every locale in CLDR's full set is here, and every code CLDR lists as default content, which names its parent's data (fr-FR is fr), as DateTime::Locale has them; and CLDR's aliases for retired codes, such as iw for he, in for id. A code it does not know is an error.

A locale's data is read the first time something asks for it, and kept for the life of the process. English is always there and reads nothing.

METHODS

codes

The codes of every locale, English first.

code

Time::Keeper::Locale->code('EN_gb');    # en-GB
Time::Keeper::Locale->code('iw');       # he
Time::Keeper::Locale->code('xx');       # undef

The locale's code as Time::Keeper writes it, or undef for one it does not know. This is the one method that does not die for an unknown code. A -u-ca- extension naming a calendar (th-u-ca-buddhist) is not part of the code and is stripped here and in every method that takes a locale; "CALENDARS" in Time::Keeper says what reads it.

name

native_name

The locale's name in English, and in its own language: French (Canada) and français (Canada), as CLDR's display pattern makes them.

cldr_version

The CLDR release the data was compiled from.

first_day_of_week

The first day of the week where the locale is used, 1 for Monday to 7 for Sunday: 7 in the United States, 1 in most of Europe, 6 in some countries. The locale's region decides it; a language with no region takes the one CLDR thinks most likely (fr is France).

min_days_in_first_week

How many days of January the first week of a year must hold: 4 where weeks are counted as ISO 8601 counts them, 1 in the United States.

prefers_24_hour_time

True if the locale's own times are written with a 24-hour clock.

names

my @months = Time::Keeper::Locale->names('fr', 'months');
my @days   = Time::Keeper::Locale->names('fr', 'days', 'abbreviated', 'stand-alone');

A list of names: months (January first), days (Monday first), quarters, eras (before Christ, then after) or am_pm. A width may follow, wide (the default), abbreviated or narrow, and short for days; and a context, format (the default), the form used inside a date, or stand-alone, the form used alone. Where a language has only one form the two are the same. A calendar's id may follow as a fifth argument: its months (CLDR's slots, thirteen for the Hebrew with Adar II a fourteenth), eras and cyclic_years in the locale, as "CALENDARS" in Time::Keeper uses them.

day_periods

my $p = Time::Keeper::Locale->day_periods('en');
$p->{noon};             # noon
$p->{afternoon1};       # in the afternoon

The locale's names for the parts of a day, as a hash reference keyed by CLDR's ids: am, pm, midnight, noon, morning1, morning2, afternoon1, afternoon2, evening1, evening2, night1 and night2, those the locale has. A width may follow, wide (the default), abbreviated or narrow, and a context, format (the default), the form inside a time, or stand-alone, the form used alone; where a language has one form the two are the same. These are the words B writes in a pattern.

Time::Keeper::Locale->day_periods('es', 'wide', 'stand-alone');

day_period_rules

my @rules = Time::Keeper::Locale->day_period_rules('en');
# { period => 'morning1', from => 360, before => 720 }, ... { period => 'noon', at => 720 }

When each named period is, as a list of hash references: the period's id and either from and before, minutes of the day with the end excluded, or at, the one minute of midnight or noon. CLDR cuts the day at midnight, so no period crosses it: English's night runs from 21:00 to 24:00 and its morning from 00:00. Locales that share CLDR's rules share them.

formats

my ($full, $long, $medium, $short) = Time::Keeper::Locale->formats('ja', 'date');

The locale's four CLDR patterns for date, time or datetime. In a datetime pattern {1} is the date and {0} the time. A calendar's id as a third argument gives the calendar's own date and datetime patterns; the time patterns are the Gregorian's. A pattern is returned as its letters, without the numbering system CLDR may attach to it.

available_formats

A hash reference of the locale's patterns by skeleton, as "format_skeleton" in Time::Keeper uses them. A calendar's id as a second argument lays the calendar's skeletons over the Gregorian ones.

calendars

my @ids = Time::Keeper::Locale->calendars('th');   # buddhist gregory

The calendars the locale's territory uses, most preferred first: "preferred" in Time::Keeper::Calendar for a locale code.

parts

my $p = Time::Keeper::Locale->parts('zh-Hant-TW');
$p->{territory};               # TW
$p->{script_name};             # Traditional
$p->{native_territory_name};   # 台灣

The locale's subtags, language, script, territory and variant (undef for those it does not have), with each one's name in English (language_name and so on) and in the locale itself (native_language_name and so on), as a hash reference.

digits

The ten digits the locale writes, 0 to 9: 0 to 9 in most, ٠ to ٩ in ar-EG, ০ to ৯ in bn.

number_symbols

my $s = Time::Keeper::Locale->number_symbols('de');
$s->{decimal};          # ,
$s->{group};            # .
$s->{minus};            # -

The symbols the locale writes numbers with, in its default numbering system: the decimal separator, the group separator and the minus sign. Some carry a Unicode mark, as Arabic's minus does.

ascii_digits

Time::Keeper::Locale->ascii_digits('٢٠٢٦');   # 2026

The text with the digits of every script written as 0 to 9, as the parsers read them; anything else is left as it is.

weekend_start

weekend_end

Time::Keeper::Locale->weekend_start('ar-EG');   # 5, Friday

The first and last day of the locale's weekend, 1 for Monday to 7 for Sunday, from CLDR's data for the locale's territory: Saturday and Sunday in most of the world, Friday and Saturday in Egypt, Thursday and Friday in Afghanistan, Sunday alone in India.

plural_category

Time::Keeper::Locale->plural_category('ru', 21);   # one
Time::Keeper::Locale->plural_category('ru', 5);    # many

The CLDR plural category of a whole number in the locale: zero, one, two, few, many or other. English has one and other; Russian one, few, many and other; Arabic all six; Japanese other alone. The sign is ignored.

relative_names

my $r = Time::Keeper::Locale->relative_names('en', 'day');
$r->{display};          # day
$r->{at}{-1};           # yesterday
$r->{at}{1};            # tomorrow
$r->{future}{one};      # in {0} day
$r->{past}{other};      # {0} days ago

The locale's words for a relative time in a field (year, quarter, month, week, day, hour, minute or second) and a width (long, the default, short or narrow), as a hash reference: the field's name, the words for the field -2 to 2 away where the locale has them (at, keyed by the offset), and the patterns for a count in the future and the past by plural category, with {0} for the number.

A weekday is a field too, mon to sun: at holds the locale's "last Tuesday", "this Tuesday" and "next Tuesday" (-1, 0 and 1), and the patterns are its "in {0} Tuesdays" and "{0} Tuesdays ago". A weekday has no display name; "names" gives the day's.

unit_patterns

my $u = Time::Keeper::Locale->unit_patterns('de', 'hour', 'short');
$u->{display};          # Std.
$u->{count}{one};       # {0} Std.

The locale's words for a duration unit (year, month, week, day, hour, minute, second, millisecond, microsecond or nanosecond) in a width (long, short or narrow): its name and the pattern for a count by plural category.

duration_patterns

A hash reference of the locale's patterns for a duration written as digits: hm (h:mm), hms (h:mm:ss) and ms (m:ss).

list_patterns

my $l = Time::Keeper::Locale->list_patterns('en', 'unit');
$l->{two};              # {0}, {1}
$l->{start};  $l->{middle};  $l->{end};

The locale's patterns for joining a list, of the type standard (and), unit, unit-short or unit-narrow, as a hash reference: two for a list of two, and start, middle and end for a longer one.

interval_formats

my $i = Time::Keeper::Locale->interval_formats('en', 'yMMMd');
$i->{d};                # MMM d – d, y
$i->{M};                # MMM d – MMM d, y
my $all = Time::Keeper::Locale->interval_formats('en');   # by skeleton

The locale's interval formats for a skeleton: a hash reference from the greatest field that differs between the two ends (y, M, d, a, h, H, m, B or G) to the pattern, whose second half begins at the first field that repeats. With no skeleton, every skeleton's, as a hash of hashes.

interval_fallback

The locale's pattern for an interval no format fits, {0} – {1} in English.

SEE ALSO

Time::Keeper, https://cldr.unicode.org/

AUTHOR

LNATION, <email at lnation.org>

LICENSE AND COPYRIGHT

This software is Copyright (c) 2026 by LNATION.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)

The locale data is from the Unicode Common Locale Data Repository, Copyright (c) 1991-2026 Unicode, Inc., under the Unicode License v3.