icanboogie / cldr
Localize applications using Unicode's CLDR
Installs: 231 599
Dependents: 5
Suggesters: 0
Security: 0
Stars: 51
Watchers: 4
Forks: 4
Open Issues: 0
Requires
- php: >=7.1 <8.2
- ext-curl: *
- ext-json: *
- ext-mbstring: *
- icanboogie/accessor: ^3.0|^4.0
- icanboogie/common: ^1.3
Requires (Dev)
- ext-redis: *
- phpstan/phpstan: ^1.4
- phpunit/phpunit: ^7.5.20|^8.5
README
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.
Example usage
<?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; // フランス
Installation
composer require icanboogie/cldr
Documentation
The 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)
Getting started
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.
Favor flexibility
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);
Favor predictability
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 fr
The 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);
Continuous Integration
The project is continuously tested by GitHub actions.
Code of Conduct
This project adheres to a Contributor Code of Conduct. By participating in this project and its community, you're expected to uphold this code.
Contributing
See CONTRIBUTING for details.
License
icanboogie/cldr is released under the MIT License.