From 9cab8ae58a29ecf7387e6865aa170715caeabf04 Mon Sep 17 00:00:00 2001 From: Stefan Parviainen Date: Tue, 30 Dec 2014 19:57:12 +0100 Subject: Language names via intl library. Fixes #773 --- library/intl/README.md | 163 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 163 insertions(+) create mode 100644 library/intl/README.md (limited to 'library/intl/README.md') diff --git a/library/intl/README.md b/library/intl/README.md new file mode 100644 index 000000000..8de2de4d9 --- /dev/null +++ b/library/intl/README.md @@ -0,0 +1,163 @@ +intl +===== + +[![Build Status](https://travis-ci.org/commerceguys/intl.svg?branch=master)](https://travis-ci.org/commerceguys/intl) + +A PHP 5.4+ internationalization library, powered by CLDR data. + +Features: +- NumberFormatter, inspired by [intl](http://php.net/manual/en/class.numberformatter.php). +- Currencies +- Countries +- Languages + +Coming soon: date formatting. + +Why not use the intl extension? +------------------------------- +The intl extension isn't present by default on PHP installs, requiring +it can hurt software adoption. +Behind the scenes the extension relies on libicu which includes the CLDR dataset, +but depending on the OS/distribution used, could be several major CLDR releases behind. + +Since the CLDR dataset is freely available in JSON form, it is possible to +reimplement the intl functionality in pure PHP code while ensuring that the +dataset is always fresh. + +Having access to the CLDR dataset also makes it possible to offer additional APIs, +such as listing all currencies. + +More backstory can be found in [this blog post](https://drupalcommerce.org/blog/15916/commerce-2x-stories-internationalization). + +Formatting numbers +------------------ +Formats numbers (decimals, percents, currency amounts) using locale-specific rules. + +This ensures that the decimal and grouping separators, the position of the currency +symbol, as well as the actual symbol used match what the user is expecting. + +The amounts passed for formatting should already be rounded, because the +formatter doesn't do any rounding of its own. + +```php +use CommerceGuys\Intl\Currency\CurrencyRepository; +use CommerceGuys\Intl\NumberFormat\NumberFormatRepository; +use CommerceGuys\Intl\Formatter\NumberFormatter; + +$currencyRepository = new CurrencyRepository; +$numberFormatRepository = new NumberFormatRepository; + +$currency = $currencyRepository->get('USD'); +$numberFormat = $numberFormatRepository->get('en'); + +$decimalFormatter = new NumberFormatter($numberFormat); +echo $decimalFormatter->format('1234.99'); // 123,456.99 + +$percentFormatter = new NumberFormatter($numberFormat, NumberFormatter::PERCENT); +echo $percentFormatter->format('0.75'); // 75% + +$currencyFormatter = new NumberFormatter($numberFormat, NumberFormatter::CURRENCY); +echo $currencyFormatter->formatCurrency('2.99', $currency); // $2.99 + +// The accounting pattern shows negative numbers differently and is used +// primarily for amounts shown on invoices. +$invoiceCurrencyFormatter = new NumberFormatter($numberFormat, NumberFormatter::CURRENCY_ACCOUNTING); +echo $invoiceCurrencyFormatter->formatCurrency('-2.99', $currency); // (2.99$) + +// Arabic, Arabic extended, Bengali, Devanagari digits are supported as expected. +$currency = $currencyRepository->get('USD', 'ar'); +$numberFormat = $numberFormatRepository->get('ar'); +$currencyFormatter = new NumberFormatter($numberFormat, NumberFormatter::CURRENCY); +echo $currencyFormatter->formatCurrency('1230.99', $currency); // US$ ١٬٢٣٠٫٩٩ + +// Parse formatted values into numeric values. +echo $currencyFormatter->parseCurrency('US$ ١٬٢٣٠٫٩٩', $currency); // 1230.99 +``` + +Currencies +---------- +```php +use CommerceGuys\Intl\Currency\CurrencyRepository; + +// Reads the currency definitions from resources/currency. +$currencyRepository = new CurrencyRepository; + +// Get the USD currency using the default locale (en). +$currency = $currencyRepository->get('USD'); +echo $currency->getCurrencyCode(); // USD +echo $currency->getNumericCode(); // 840 +echo $currency->getFractionDigits(); // 2 +echo $currency->getName(); // US Dollar +echo $currency->getSymbol(); // $ +echo $currency->getLocale(); // en + +// Get the USD currency using the fr-FR locale. +$currency = $currencyRepository->get('USD', 'fr-FR'); +echo $currency->getName(); // dollar des États-Unis +echo $currency->getSymbol(); // $US +echo $currency->getLocale(); // fr-FR + +$allCurrencies = $currencyRepository->getAll(); +``` + +Countries +--------- +```php +use CommerceGuys\Intl\Country\CountryRepository; + +// Reads the country definitions from resources/country. +$countryRepository = new CountryRepository; + +// Get the US country using the default locale (en). +$country = $countryRepository->get('US'); +echo $country->getCountryCode(); // US +echo $country->getTelephoneCode(); // 1 +echo $country->getName(); // United States + +// Get the US country using the fr-FR locale. +$country = $countryRepository->get('US', 'fr-FR'); +echo $country->getName(); // États-Unis + +$allCountries = $countryRepository->getAll(); +``` + +Languages +--------- +```php +use CommerceGuys\Intl\Language\LanguageRepository; + +// Reads the language definitions from resources/language. +$languageRepository = new LanguageRepository; + +// Get the german language using the default locale (en). +$language = $languageRepository->get('de'); +echo $language->getLanguageCode(); // de +echo $language->getName(); // German + +// Get the german language using the fr-FR locale. +$language = $languageRepository->get('de', 'fr-FR'); +echo $language->getName(); // allemand + +$allLanguages = $languageRepository->getAll(); +``` + +Implementing the library +------------------------ +While the library can be used as-is, most applications will want to store the +relevant definitions (currencies, countries, etc) in the database. +This allows for better performance while giving users the ability to modify and +expand the data. + +Taking currencies as an example, a merchant frequently wants to be able to: + +- Define custom currencies. +- Enable/disable existing currencies +- Modify an existing currency (changing the default number of fraction digits, for example). + +This would be accomplished by using the CurrencyRepository to get all default currencies and +insert them into the database. The doctrine entity (or any similar data object) would then implement +the CurrencyInterface so that the NumberFormatter can continue to work. + +Related projects +---------------- +[commerceguys/pricing](http://github.com/commerceguys/pricing) provides a Price object. -- cgit v1.2.3 From 4f35efa0bad4ae6489b63f3eebafe6542d654094 Mon Sep 17 00:00:00 2001 From: RedMatrix Date: Wed, 31 Dec 2014 10:43:19 +1100 Subject: Revert "Language names via intl library." --- library/intl/README.md | 163 ------------------------------------------------- 1 file changed, 163 deletions(-) delete mode 100644 library/intl/README.md (limited to 'library/intl/README.md') diff --git a/library/intl/README.md b/library/intl/README.md deleted file mode 100644 index 8de2de4d9..000000000 --- a/library/intl/README.md +++ /dev/null @@ -1,163 +0,0 @@ -intl -===== - -[![Build Status](https://travis-ci.org/commerceguys/intl.svg?branch=master)](https://travis-ci.org/commerceguys/intl) - -A PHP 5.4+ internationalization library, powered by CLDR data. - -Features: -- NumberFormatter, inspired by [intl](http://php.net/manual/en/class.numberformatter.php). -- Currencies -- Countries -- Languages - -Coming soon: date formatting. - -Why not use the intl extension? -------------------------------- -The intl extension isn't present by default on PHP installs, requiring -it can hurt software adoption. -Behind the scenes the extension relies on libicu which includes the CLDR dataset, -but depending on the OS/distribution used, could be several major CLDR releases behind. - -Since the CLDR dataset is freely available in JSON form, it is possible to -reimplement the intl functionality in pure PHP code while ensuring that the -dataset is always fresh. - -Having access to the CLDR dataset also makes it possible to offer additional APIs, -such as listing all currencies. - -More backstory can be found in [this blog post](https://drupalcommerce.org/blog/15916/commerce-2x-stories-internationalization). - -Formatting numbers ------------------- -Formats numbers (decimals, percents, currency amounts) using locale-specific rules. - -This ensures that the decimal and grouping separators, the position of the currency -symbol, as well as the actual symbol used match what the user is expecting. - -The amounts passed for formatting should already be rounded, because the -formatter doesn't do any rounding of its own. - -```php -use CommerceGuys\Intl\Currency\CurrencyRepository; -use CommerceGuys\Intl\NumberFormat\NumberFormatRepository; -use CommerceGuys\Intl\Formatter\NumberFormatter; - -$currencyRepository = new CurrencyRepository; -$numberFormatRepository = new NumberFormatRepository; - -$currency = $currencyRepository->get('USD'); -$numberFormat = $numberFormatRepository->get('en'); - -$decimalFormatter = new NumberFormatter($numberFormat); -echo $decimalFormatter->format('1234.99'); // 123,456.99 - -$percentFormatter = new NumberFormatter($numberFormat, NumberFormatter::PERCENT); -echo $percentFormatter->format('0.75'); // 75% - -$currencyFormatter = new NumberFormatter($numberFormat, NumberFormatter::CURRENCY); -echo $currencyFormatter->formatCurrency('2.99', $currency); // $2.99 - -// The accounting pattern shows negative numbers differently and is used -// primarily for amounts shown on invoices. -$invoiceCurrencyFormatter = new NumberFormatter($numberFormat, NumberFormatter::CURRENCY_ACCOUNTING); -echo $invoiceCurrencyFormatter->formatCurrency('-2.99', $currency); // (2.99$) - -// Arabic, Arabic extended, Bengali, Devanagari digits are supported as expected. -$currency = $currencyRepository->get('USD', 'ar'); -$numberFormat = $numberFormatRepository->get('ar'); -$currencyFormatter = new NumberFormatter($numberFormat, NumberFormatter::CURRENCY); -echo $currencyFormatter->formatCurrency('1230.99', $currency); // US$ ١٬٢٣٠٫٩٩ - -// Parse formatted values into numeric values. -echo $currencyFormatter->parseCurrency('US$ ١٬٢٣٠٫٩٩', $currency); // 1230.99 -``` - -Currencies ----------- -```php -use CommerceGuys\Intl\Currency\CurrencyRepository; - -// Reads the currency definitions from resources/currency. -$currencyRepository = new CurrencyRepository; - -// Get the USD currency using the default locale (en). -$currency = $currencyRepository->get('USD'); -echo $currency->getCurrencyCode(); // USD -echo $currency->getNumericCode(); // 840 -echo $currency->getFractionDigits(); // 2 -echo $currency->getName(); // US Dollar -echo $currency->getSymbol(); // $ -echo $currency->getLocale(); // en - -// Get the USD currency using the fr-FR locale. -$currency = $currencyRepository->get('USD', 'fr-FR'); -echo $currency->getName(); // dollar des États-Unis -echo $currency->getSymbol(); // $US -echo $currency->getLocale(); // fr-FR - -$allCurrencies = $currencyRepository->getAll(); -``` - -Countries ---------- -```php -use CommerceGuys\Intl\Country\CountryRepository; - -// Reads the country definitions from resources/country. -$countryRepository = new CountryRepository; - -// Get the US country using the default locale (en). -$country = $countryRepository->get('US'); -echo $country->getCountryCode(); // US -echo $country->getTelephoneCode(); // 1 -echo $country->getName(); // United States - -// Get the US country using the fr-FR locale. -$country = $countryRepository->get('US', 'fr-FR'); -echo $country->getName(); // États-Unis - -$allCountries = $countryRepository->getAll(); -``` - -Languages ---------- -```php -use CommerceGuys\Intl\Language\LanguageRepository; - -// Reads the language definitions from resources/language. -$languageRepository = new LanguageRepository; - -// Get the german language using the default locale (en). -$language = $languageRepository->get('de'); -echo $language->getLanguageCode(); // de -echo $language->getName(); // German - -// Get the german language using the fr-FR locale. -$language = $languageRepository->get('de', 'fr-FR'); -echo $language->getName(); // allemand - -$allLanguages = $languageRepository->getAll(); -``` - -Implementing the library ------------------------- -While the library can be used as-is, most applications will want to store the -relevant definitions (currencies, countries, etc) in the database. -This allows for better performance while giving users the ability to modify and -expand the data. - -Taking currencies as an example, a merchant frequently wants to be able to: - -- Define custom currencies. -- Enable/disable existing currencies -- Modify an existing currency (changing the default number of fraction digits, for example). - -This would be accomplished by using the CurrencyRepository to get all default currencies and -insert them into the database. The doctrine entity (or any similar data object) would then implement -the CurrencyInterface so that the NumberFormatter can continue to work. - -Related projects ----------------- -[commerceguys/pricing](http://github.com/commerceguys/pricing) provides a Price object. -- cgit v1.2.3 From 7bf7f8180dbc3a89824815de3bc1e4f40857d2f6 Mon Sep 17 00:00:00 2001 From: Stefan Parviainen Date: Wed, 31 Dec 2014 10:42:08 +0100 Subject: Revert "Revert "Language names via intl library."" This reverts commit 4f35efa0bad4ae6489b63f3eebafe6542d654094. --- library/intl/README.md | 163 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 163 insertions(+) create mode 100644 library/intl/README.md (limited to 'library/intl/README.md') diff --git a/library/intl/README.md b/library/intl/README.md new file mode 100644 index 000000000..8de2de4d9 --- /dev/null +++ b/library/intl/README.md @@ -0,0 +1,163 @@ +intl +===== + +[![Build Status](https://travis-ci.org/commerceguys/intl.svg?branch=master)](https://travis-ci.org/commerceguys/intl) + +A PHP 5.4+ internationalization library, powered by CLDR data. + +Features: +- NumberFormatter, inspired by [intl](http://php.net/manual/en/class.numberformatter.php). +- Currencies +- Countries +- Languages + +Coming soon: date formatting. + +Why not use the intl extension? +------------------------------- +The intl extension isn't present by default on PHP installs, requiring +it can hurt software adoption. +Behind the scenes the extension relies on libicu which includes the CLDR dataset, +but depending on the OS/distribution used, could be several major CLDR releases behind. + +Since the CLDR dataset is freely available in JSON form, it is possible to +reimplement the intl functionality in pure PHP code while ensuring that the +dataset is always fresh. + +Having access to the CLDR dataset also makes it possible to offer additional APIs, +such as listing all currencies. + +More backstory can be found in [this blog post](https://drupalcommerce.org/blog/15916/commerce-2x-stories-internationalization). + +Formatting numbers +------------------ +Formats numbers (decimals, percents, currency amounts) using locale-specific rules. + +This ensures that the decimal and grouping separators, the position of the currency +symbol, as well as the actual symbol used match what the user is expecting. + +The amounts passed for formatting should already be rounded, because the +formatter doesn't do any rounding of its own. + +```php +use CommerceGuys\Intl\Currency\CurrencyRepository; +use CommerceGuys\Intl\NumberFormat\NumberFormatRepository; +use CommerceGuys\Intl\Formatter\NumberFormatter; + +$currencyRepository = new CurrencyRepository; +$numberFormatRepository = new NumberFormatRepository; + +$currency = $currencyRepository->get('USD'); +$numberFormat = $numberFormatRepository->get('en'); + +$decimalFormatter = new NumberFormatter($numberFormat); +echo $decimalFormatter->format('1234.99'); // 123,456.99 + +$percentFormatter = new NumberFormatter($numberFormat, NumberFormatter::PERCENT); +echo $percentFormatter->format('0.75'); // 75% + +$currencyFormatter = new NumberFormatter($numberFormat, NumberFormatter::CURRENCY); +echo $currencyFormatter->formatCurrency('2.99', $currency); // $2.99 + +// The accounting pattern shows negative numbers differently and is used +// primarily for amounts shown on invoices. +$invoiceCurrencyFormatter = new NumberFormatter($numberFormat, NumberFormatter::CURRENCY_ACCOUNTING); +echo $invoiceCurrencyFormatter->formatCurrency('-2.99', $currency); // (2.99$) + +// Arabic, Arabic extended, Bengali, Devanagari digits are supported as expected. +$currency = $currencyRepository->get('USD', 'ar'); +$numberFormat = $numberFormatRepository->get('ar'); +$currencyFormatter = new NumberFormatter($numberFormat, NumberFormatter::CURRENCY); +echo $currencyFormatter->formatCurrency('1230.99', $currency); // US$ ١٬٢٣٠٫٩٩ + +// Parse formatted values into numeric values. +echo $currencyFormatter->parseCurrency('US$ ١٬٢٣٠٫٩٩', $currency); // 1230.99 +``` + +Currencies +---------- +```php +use CommerceGuys\Intl\Currency\CurrencyRepository; + +// Reads the currency definitions from resources/currency. +$currencyRepository = new CurrencyRepository; + +// Get the USD currency using the default locale (en). +$currency = $currencyRepository->get('USD'); +echo $currency->getCurrencyCode(); // USD +echo $currency->getNumericCode(); // 840 +echo $currency->getFractionDigits(); // 2 +echo $currency->getName(); // US Dollar +echo $currency->getSymbol(); // $ +echo $currency->getLocale(); // en + +// Get the USD currency using the fr-FR locale. +$currency = $currencyRepository->get('USD', 'fr-FR'); +echo $currency->getName(); // dollar des États-Unis +echo $currency->getSymbol(); // $US +echo $currency->getLocale(); // fr-FR + +$allCurrencies = $currencyRepository->getAll(); +``` + +Countries +--------- +```php +use CommerceGuys\Intl\Country\CountryRepository; + +// Reads the country definitions from resources/country. +$countryRepository = new CountryRepository; + +// Get the US country using the default locale (en). +$country = $countryRepository->get('US'); +echo $country->getCountryCode(); // US +echo $country->getTelephoneCode(); // 1 +echo $country->getName(); // United States + +// Get the US country using the fr-FR locale. +$country = $countryRepository->get('US', 'fr-FR'); +echo $country->getName(); // États-Unis + +$allCountries = $countryRepository->getAll(); +``` + +Languages +--------- +```php +use CommerceGuys\Intl\Language\LanguageRepository; + +// Reads the language definitions from resources/language. +$languageRepository = new LanguageRepository; + +// Get the german language using the default locale (en). +$language = $languageRepository->get('de'); +echo $language->getLanguageCode(); // de +echo $language->getName(); // German + +// Get the german language using the fr-FR locale. +$language = $languageRepository->get('de', 'fr-FR'); +echo $language->getName(); // allemand + +$allLanguages = $languageRepository->getAll(); +``` + +Implementing the library +------------------------ +While the library can be used as-is, most applications will want to store the +relevant definitions (currencies, countries, etc) in the database. +This allows for better performance while giving users the ability to modify and +expand the data. + +Taking currencies as an example, a merchant frequently wants to be able to: + +- Define custom currencies. +- Enable/disable existing currencies +- Modify an existing currency (changing the default number of fraction digits, for example). + +This would be accomplished by using the CurrencyRepository to get all default currencies and +insert them into the database. The doctrine entity (or any similar data object) would then implement +the CurrencyInterface so that the NumberFormatter can continue to work. + +Related projects +---------------- +[commerceguys/pricing](http://github.com/commerceguys/pricing) provides a Price object. -- cgit v1.2.3