The CLDR package facilitates the internationalization of your application by leveraging the data and conventions established by the Unicode Common Locale Data Repository (CLDR). It provides valuable locale information such as names for territories, languages, days… as well as formatters for numbers, currencies, dates and times, units, sequences, and lists.
Note
The package targets CLDR version 45; Revision 72.
<?php
use ICanBoogie\CLDR\Numbers\Currency;
/* @var ICanBoogie\CLDR\Repository $repository */
# You get a locale from the repository, here the locale for French.
$fr = $repository->locale_for('fr');
# You can use a locale instance as an array
echo $fr['characters']['auxiliary']; // [á å ä ã ā ē í ì ī ñ ó ò ö ø ú ǔ]
echo $fr['delimiters']['quotationStart']; // «
echo $fr['territories']['TF']; // Terres australes françaises
# You can localize it and get its local name
echo $fr->localized($fr)->name; // Français
# You can use it to format numbers, percents, currencies, lists…
echo $fr->format_number(12345.67); // 12 345,67
echo $fr->format_percent(.1234567); // 12 %
echo $fr->format_currency(12345.67, 'EUR'); // 12 345,67 €
echo $fr->format_list([ "Un", "deux", "trois" ]); // Un, deux et trois
# You can get the default calendar for a locale and access its data
$calendar = $fr->calendar;
echo $calendar['days']['format']['wide']['sun']; // dimanche
echo $calendar->wide_days['sun']; // dimanche
# You can use the calendar to format dates, times, or both
$datetime = '2018-11-24 20:12:22 UTC';
echo $calendar->format_date($datetime, 'long'); // 24 novembre 2018
echo $calendar->format_time($datetime, 'long'); // 20:12:22 UTC
echo $calendar->format_datetime($datetime, 'full'); // samedi 24 novembre 2018 à 20:12:22 UTC
# Alternatively, you can localize a DateTimeInterface and get formatted dates of various lengths
$datetime = new \DateTime('2013-11-04 20:21:22 UTC');
$fr_datetime = new \ICanBoogie\CLDR\Dates\LocalizedDateTime($datetime, $fr);
echo $fr_datetime->as_full; // lundi 4 novembre 2013 à 20:21:22 UTC
echo $fr_datetime->as_long; // 4 novembre 2013 à 20:21:22 UTC
echo $fr_datetime->as_medium; // 4 nov. 2013 20:21:22
echo $fr_datetime->as_short; // 04/11/2013 20:21
# You can format units
$units = $repository->locale_for('en')->units;
echo $units->duration_hour->name; // hours
echo $units->duration_hour->short_name; // h
echo $units->duration_hour(1); // 1 hour
echo $units->duration_hour(23); // 23 hours
echo $units->duration_hour(23)->as_short; // 23 hr
echo $units->duration_hour(23)->as_narrow; // 23h
# You can format a unit per another unit
echo $units->volume_liter(12.345)->per($units->duration_hour);
// 12.345 liters per hour
echo $units->volume_liter(12.345)->per($units->duration_hour)->as_short;
// 12.345 L/h
echo $units->volume_liter(12.345)->per($units->duration_hour)->as_narrow;
// 12.345L/h
# You can format sequences of units
$units->sequence->angle_degree(5)->duration_minute(30)->as_narrow;
// 5° 30m
$units->sequence->length_foot(3)->length_inch(2)->as_short;
// 3 ft, 2 in
# You can access plural rules
$repository->plurals->rule_for(1.5, 'fr'); // one
$repository->plurals->rule_for(2, 'fr'); // other
$repository->plurals->rule_for(2, 'ar'); // two
# You can access currencies and their localized data
$euro = Currency::of('EUR');
$fr_euro = $euro->localized($fr);
echo $fr_euro->name;
echo $fr_euro->name_for(1); // euro
echo $fr_euro->name_for(10); // euros
echo $fr_euro->format(12345.67); // 12 345,67 €
# You can access territories and their localized data
$territory = $repository->territory_for('FR');
echo $territory; // FR
echo $territory->currency; // EUR
echo $territory->currency_at('1977-06-06'); // FRF
echo $territory->currency_at('now'); // EUR
echo $territory->name_as('fr'); // France
echo $territory->name_as('it'); // Francia
echo $territory->name_as('ja'); // フランス
echo $repository->territory_for('FR')->first_day; // mon
echo $repository->territory_for('EG')->first_day; // sat
echo $repository->territory_for('BS')->first_day; // sun
echo $repository->territory_for('AE')->weekend_start; // fri
echo $repository->territory_for('AE')->weekend_end; // sat
echo $territory->localized('fr')->name; // France
echo $territory->localized('it')->name; // Francia
echo $territory->localized('ja')->name; // フランスcomposer require icanboogie/cldrThe documentation is divided into the following parts, mimicking Unicode's documentation:
- Part 1: Core (languages, locales, basic structure)
- Part 2: General (display names & transforms, etc.)
- Part 3: Numbers (number & currency formatting)
- Part 4: Dates (date, time, time zone formatting)
- Part 5: Collation (sorting, searching, grouping)
- Part 6: Supplemental (supplemental data)
The CLDR is represented by a Repository instance, which accesses data through a Provider instance. The package offers several and caching mechanisms. Choosing the right provider depends on your requirements: you may prioritize flexibility during development or predictability in production.
WebProvider offers maximum flexibility by retrieving data from the JSON distribution hosted on GitHub as needed. To minimize web requests, it is advised to use a collection of caches, each with its own strategy. For example, FileCache stores the retrieved data as PHP files, allowing it to benefit from opcache.
The following example demonstrates how a repository can be instantiated:
<?php
use ICanBoogie\CLDR\Cache\CacheCollection;
use ICanBoogie\CLDR\Cache\FileCache;
use ICanBoogie\CLDR\Cache\RedisCache;
use ICanBoogie\CLDR\Cache\RuntimeCache;
use ICanBoogie\CLDR\Provider\CachedProvider;
use ICanBoogie\CLDR\Provider\WebProvider;
use ICanBoogie\CLDR\Repository;
/* @var \Redis $redis_client */
$provider = new CachedProvider(
new WebProvider,
new CacheCollection([
new RunTimeCache,
// You don't have to use Redis, this is only an example
new RedisCache($redis_client),
new FileCache(FileCache::RECOMMENDED_DIR)
])
);
$cldr = new Repository($provider);For greater predictability, consider limiting the repository's usage to a few specific locales and distributing them as part of your application. You can prepopulate the CLDR cache during development and commit the files, or incorporate this step into your CI/CD pipeline build process.
Use the cldr command to warm up the CLDR cache:
./vendor/bin/cldr warm-up de en frThe following example illustrates a setup to limit data access to the cache. RestrictedProvider throws an exception in an attempt to retrieve data not available in the cache.
<?php
use ICanBoogie\CLDR\Cache\FileCache;
use ICanBoogie\CLDR\Provider\CachedProvider;
use ICanBoogie\CLDR\Provider\RestrictedProvider;
use ICanBoogie\CLDR\Repository;
$provider = new CachedProvider(
new RestrictedProvider(),
new FileCache(FileCache::RECOMMENDED_DIR),
);
$cldr = new Repository($provider);The project is continuously tested by GitHub actions.
This project adheres to a Contributor Code of Conduct. By participating in this project and its community, you're expected to uphold this code.
See CONTRIBUTING for details.
icanboogie/cldr is released under the MIT License.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent