From 951598c013ffe1f3da084723007f2b721d7978d3 Mon Sep 17 00:00:00 2001 From: Jose Lorenzo Rodriguez Date: Sun, 11 Jan 2015 20:34:53 +0100 Subject: [PATCH] Adding a composer.json and a README to I18n --- composer.json | 6 +- src/I18n/README.md | 86 ++++++++++++++++ src/I18n/composer.json | 24 +++++ src/I18n/functions.php | 226 +++++++++++++++++++++++++++++++++++++++++ src/Log/README.md | 2 +- src/basics.php | 212 -------------------------------------- 6 files changed, 341 insertions(+), 215 deletions(-) create mode 100644 src/I18n/README.md create mode 100644 src/I18n/composer.json create mode 100644 src/I18n/functions.php diff --git a/composer.json b/composer.json index 9ae97a5d3bd..7d0d63bbb1d 100644 --- a/composer.json +++ b/composer.json @@ -36,7 +36,8 @@ }, "files": [ "src/Core/functions.php", - "src/Collection/functions.php" + "src/Collection/functions.php", + "src/I18n/functions.php" ] }, "autoload-dev": { @@ -59,6 +60,7 @@ "cakephp/datasource": "self.version", "cakephp/database": "self.version", "cakephp/cache": "self.version", - "cakephp/log": "self.version" + "cakephp/log": "self.version", + "cakephp/i18n": "self.version" } } diff --git a/src/I18n/README.md b/src/I18n/README.md new file mode 100644 index 00000000000..e1d0e8d9534 --- /dev/null +++ b/src/I18n/README.md @@ -0,0 +1,86 @@ +# CakePHP Internationalization Library + +The I18n library provides a `I18n` service locator that can be used for setting +the current locale, building translation bundles and translating messagges. + +Additionally, it provides the `Time` and `Number` classes which can be used to +ouput dates, currecies and any numbers in the right format for the speciafied locale. + +## Usage + +The `I18n` class uses internally the [Aura.Intl](https://github.com/auraphp/Aura.Intl) library. +Getting familiar with it, will help you understand how to build and manipulate translation bundles +should you wish to create them manually instead of using the conventions this library uses. + +### Setting the Current Locale + +```php +use Cake\I18n\I18n; + +I18n::locale('de_DE'); +``` + +### Translating a message + +```php +echo __( + 'Hi {0,string}, your balance on the {1,date} is {2,number,currency}', + ['Charles', '2014-01-13 11:12:00', 1354.37] +); + +// Returns +Hi Charles, your balance on the Jan 13, 2014, 11:12 AM is $ 1,354.37 +``` + +### Creating your Own Translators + +```php +use Cake\I18n\I18n; +use Aura\Intl\Package; + +I18n::translator('animals', 'fr_FR', function () { + $package = new Package( + 'default', // The formatting strategy (ICU) + 'default', // The fallback domain + ); + $package->setMessages([ + 'Dog' => 'Chien', + 'Cat' => 'Chat', + 'Bird' => 'Oiseau' + ... + ]); + + return $package; +}); + +I18n::locale('fr_FR'); +__d('animals', 'Dog'); // Returns "Chien" +``` + +### Formatting Time + +```php +$time = Time::now(); +echo $time; // shows '4/20/14, 10:10 PM' for the en-US locale +``` + +### Formattng Numbers + +```php +echo Number::format(100100100); +``` + +```php +echo Number::currency(123456.7890, 'EUR'); +// outputs €100,100,100.00 +``` + +## Documentation + +Please make sure you check the [official I18n documentation](http://book.cakephp.org/3.0/en/core-libraries/internationalization-and-localization.html) + +The [documentation for the Time class](http://book.cakephp.org/3.0/en/core-libraries/time.html) contains instruction on how configure and output +time strings for selected locales. + +The [documentation for the Number class](http://book.cakephp.org/3.0/en/core-libraries/number.html) shows how to use the `Number` class for +displaying numbers in specific locales. diff --git a/src/I18n/composer.json b/src/I18n/composer.json new file mode 100644 index 00000000000..056da1a5a2b --- /dev/null +++ b/src/I18n/composer.json @@ -0,0 +1,24 @@ +{ + "name": "cakephp/i18n", + "description": "CakePHP Internationalization library with support for messages translation and dates and numbers localization", + "license": "MIT", + "authors": [ + { + "name": "CakePHP Community", + "homepage": "http://cakephp.org" + } + ], + "autoload": { + "psr-4": { + "Cake\\I18n\\": "." + }, + "files": ["functions.php"] + }, + "require": { + "cakephp/core": "dev-master", + "ext-intl": "*", + "nesbot/Carbon": "~1.13", + "aura/intl": "1.1.*" + }, + "minimum-stability": "dev" +} diff --git a/src/I18n/functions.php b/src/I18n/functions.php new file mode 100644 index 00000000000..51af1f19719 --- /dev/null +++ b/src/I18n/functions.php @@ -0,0 +1,226 @@ +translate($singular, $arguments); + } + +} + +if (!function_exists('__n')) { + /** + * Returns correct plural form of message identified by $singular and $plural for count $count. + * Some languages have more than one form for plural messages dependent on the count. + * + * @param string $singular Singular text to translate + * @param string $plural Plural text + * @param int $count Count + * @param mixed $args Array with arguments or multiple arguments in function + * @return mixed plural form of translated string + * @link http://book.cakephp.org/3.0/en/core-libraries/global-constants-and-functions.html#__n + */ + function __n($singular, $plural, $count, $args = null) + { + if (!$singular) { + return; + } + + $arguments = func_num_args() === 4 ? (array)$args : array_slice(func_get_args(), 3); + return I18n::translator()->translate( + $plural, + ['_count' => $count, '_singular' => $singular] + $arguments + ); + } + +} + +if (!function_exists('__d')) { + /** + * Allows you to override the current domain for a single message lookup. + * + * @param string $domain Domain + * @param string $msg String to translate + * @param mixed $args Array with arguments or multiple arguments in function + * @return string translated string + * @link http://book.cakephp.org/3.0/en/core-libraries/global-constants-and-functions.html#__d + */ + function __d($domain, $msg, $args = null) + { + if (!$msg) { + return; + } + $arguments = func_num_args() === 3 ? (array)$args : array_slice(func_get_args(), 2); + return I18n::translator($domain)->translate($msg, $arguments); + } + +} + +if (!function_exists('__dn')) { + /** + * Allows you to override the current domain for a single plural message lookup. + * Returns correct plural form of message identified by $singular and $plural for count $count + * from domain $domain. + * + * @param string $domain Domain + * @param string $singular Singular string to translate + * @param string $plural Plural + * @param int $count Count + * @param mixed $args Array with arguments or multiple arguments in function + * @return string plural form of translated string + * @link http://book.cakephp.org/3.0/en/core-libraries/global-constants-and-functions.html#__dn + */ + function __dn($domain, $singular, $plural, $count, $args = null) + { + if (!$singular) { + return; + } + + $arguments = func_num_args() === 5 ? (array)$args : array_slice(func_get_args(), 4); + return I18n::translator($domain)->translate( + $plural, + ['_count' => $count, '_singular' => $singular] + $arguments + ); + } + +} + +if (!function_exists('__x')) { + /** + * Returns a translated string if one is found; Otherwise, the submitted message. + * The context is a unique identifier for the translations string that makes it unique + * for in the same domain. + * + * @param string $context Context of the text + * @param string $singular Text to translate + * @param mixed $args Array with arguments or multiple arguments in function + * @return mixed translated string + * @link http://book.cakephp.org/3.0/en/core-libraries/global-constants-and-functions.html#__ + */ + function __x($context, $singular, $args = null) + { + if (!$singular) { + return; + } + + $arguments = func_num_args() === 3 ? (array)$args : array_slice(func_get_args(), 2); + return I18n::translator()->translate($singular, ['_context' => $context] + $arguments); + } + +} + +if (!function_exists('__xn')) { + /** + * Returns correct plural form of message identified by $singular and $plural for count $count. + * Some languages have more than one form for plural messages dependent on the count. + * The context is a unique identifier for the translations string that makes it unique + * for in the same domain. + * + * @param string $context Context of the text + * @param string $singular Singular text to translate + * @param string $plural Plural text + * @param int $count Count + * @param mixed $args Array with arguments or multiple arguments in function + * @return mixed plural form of translated string + * @link http://book.cakephp.org/3.0/en/core-libraries/global-constants-and-functions.html#__xn + */ + function __xn($context, $singular, $plural, $count, $args = null) + { + if (!$singular) { + return; + } + + $arguments = func_num_args() === 5 ? (array)$args : array_slice(func_get_args(), 2); + return I18n::translator()->translate( + $singular, + ['_count' => $count, '_singular' => $singular, '_context' => $context] + $arguments + ); + } + +} + +if (!function_exists('__dx')) { + /** + * Allows you to override the current domain for a single message lookup. + * The context is a unique identifier for the translations string that makes it unique + * for in the same domain. + * + * @param string $domain Domain + * @param string $context Context of the text + * @param string $msg String to translate + * @param mixed $args Array with arguments or multiple arguments in function + * @return string translated string + * @link http://book.cakephp.org/3.0/en/core-libraries/global-constants-and-functions.html#__dx + */ + function __dx($domain, $context, $msg, $args = null) + { + if (!$msg) { + return; + } + + $arguments = func_num_args() === 4 ? (array)$args : array_slice(func_get_args(), 2); + return I18n::translator($domain)->translate( + $msg, + ['_context' => $context] + $arguments + ); + } + +} + +if (!function_exists('__dxn')) { + /** + * Returns correct plural form of message identified by $singular and $plural for count $count. + * Allows you to override the current domain for a single message lookup. + * The context is a unique identifier for the translations string that makes it unique + * for in the same domain. + * + * @param string $domain Domain + * @param string $context Context of the text + * @param string $singular Singular text to translate + * @param string $plural Plural text + * @param int $count Count + * @param mixed $args Array with arguments or multiple arguments in function + * @return mixed plural form of translated string + * @link http://book.cakephp.org/3.0/en/core-libraries/global-constants-and-functions.html#__dxn + */ + function __dxn($domain, $context, $singular, $plural, $count, $args = null) + { + if (!$singular) { + return; + } + + $arguments = func_num_args() === 6 ? (array)$args : array_slice(func_get_args(), 2); + return I18n::translator($domain)->translate( + $singular, + ['_count' => $count, '_singular' => $singular, '_context' => $context] + $arguments + ); + } + +} diff --git a/src/Log/README.md b/src/Log/README.md index 633770a4e92..d7b151daf67 100644 --- a/src/Log/README.md +++ b/src/Log/README.md @@ -1,6 +1,6 @@ # CakePHP Logging Library -The Cache library provides a `Log` service locator for interfacing with +The Log library provides a `Log` service locator for interfacing with multiple logging backends using a simple interface. With the `Log` class it is possible to send a single message to multiple logging backends at the same time or just a subset of them based on the log level or context. diff --git a/src/basics.php b/src/basics.php index 0b6f4e5e6f3..77221584f02 100644 --- a/src/basics.php +++ b/src/basics.php @@ -14,7 +14,6 @@ */ use Cake\Core\Configure; use Cake\Error\Debugger; -use Cake\I18n\I18n; /** * Basic defines for timing functions. @@ -124,217 +123,6 @@ function stackTrace(array $options = []) } -if (!function_exists('__')) { - /** - * Returns a translated string if one is found; Otherwise, the submitted message. - * - * @param string $singular Text to translate - * @param mixed $args Array with arguments or multiple arguments in function - * @return mixed translated string - * @link http://book.cakephp.org/3.0/en/core-libraries/global-constants-and-functions.html#__ - */ - function __($singular, $args = null) - { - if (!$singular) { - return; - } - - $arguments = func_num_args() === 2 ? (array)$args : array_slice(func_get_args(), 1); - return I18n::translator()->translate($singular, $arguments); - } - -} - -if (!function_exists('__n')) { - /** - * Returns correct plural form of message identified by $singular and $plural for count $count. - * Some languages have more than one form for plural messages dependent on the count. - * - * @param string $singular Singular text to translate - * @param string $plural Plural text - * @param int $count Count - * @param mixed $args Array with arguments or multiple arguments in function - * @return mixed plural form of translated string - * @link http://book.cakephp.org/3.0/en/core-libraries/global-constants-and-functions.html#__n - */ - function __n($singular, $plural, $count, $args = null) - { - if (!$singular) { - return; - } - - $arguments = func_num_args() === 4 ? (array)$args : array_slice(func_get_args(), 3); - return I18n::translator()->translate( - $plural, - ['_count' => $count, '_singular' => $singular] + $arguments - ); - } - -} - -if (!function_exists('__d')) { - /** - * Allows you to override the current domain for a single message lookup. - * - * @param string $domain Domain - * @param string $msg String to translate - * @param mixed $args Array with arguments or multiple arguments in function - * @return string translated string - * @link http://book.cakephp.org/3.0/en/core-libraries/global-constants-and-functions.html#__d - */ - function __d($domain, $msg, $args = null) - { - if (!$msg) { - return; - } - $arguments = func_num_args() === 3 ? (array)$args : array_slice(func_get_args(), 2); - return I18n::translator($domain)->translate($msg, $arguments); - } - -} - -if (!function_exists('__dn')) { - /** - * Allows you to override the current domain for a single plural message lookup. - * Returns correct plural form of message identified by $singular and $plural for count $count - * from domain $domain. - * - * @param string $domain Domain - * @param string $singular Singular string to translate - * @param string $plural Plural - * @param int $count Count - * @param mixed $args Array with arguments or multiple arguments in function - * @return string plural form of translated string - * @link http://book.cakephp.org/3.0/en/core-libraries/global-constants-and-functions.html#__dn - */ - function __dn($domain, $singular, $plural, $count, $args = null) - { - if (!$singular) { - return; - } - - $arguments = func_num_args() === 5 ? (array)$args : array_slice(func_get_args(), 4); - return I18n::translator($domain)->translate( - $plural, - ['_count' => $count, '_singular' => $singular] + $arguments - ); - } - -} - -if (!function_exists('__x')) { - /** - * Returns a translated string if one is found; Otherwise, the submitted message. - * The context is a unique identifier for the translations string that makes it unique - * for in the same domain. - * - * @param string $context Context of the text - * @param string $singular Text to translate - * @param mixed $args Array with arguments or multiple arguments in function - * @return mixed translated string - * @link http://book.cakephp.org/3.0/en/core-libraries/global-constants-and-functions.html#__ - */ - function __x($context, $singular, $args = null) - { - if (!$singular) { - return; - } - - $arguments = func_num_args() === 3 ? (array)$args : array_slice(func_get_args(), 2); - return I18n::translator()->translate($singular, ['_context' => $context] + $arguments); - } - -} - -if (!function_exists('__xn')) { - /** - * Returns correct plural form of message identified by $singular and $plural for count $count. - * Some languages have more than one form for plural messages dependent on the count. - * The context is a unique identifier for the translations string that makes it unique - * for in the same domain. - * - * @param string $context Context of the text - * @param string $singular Singular text to translate - * @param string $plural Plural text - * @param int $count Count - * @param mixed $args Array with arguments or multiple arguments in function - * @return mixed plural form of translated string - * @link http://book.cakephp.org/3.0/en/core-libraries/global-constants-and-functions.html#__xn - */ - function __xn($context, $singular, $plural, $count, $args = null) - { - if (!$singular) { - return; - } - - $arguments = func_num_args() === 5 ? (array)$args : array_slice(func_get_args(), 2); - return I18n::translator()->translate( - $singular, - ['_count' => $count, '_singular' => $singular, '_context' => $context] + $arguments - ); - } - -} - -if (!function_exists('__dx')) { - /** - * Allows you to override the current domain for a single message lookup. - * The context is a unique identifier for the translations string that makes it unique - * for in the same domain. - * - * @param string $domain Domain - * @param string $context Context of the text - * @param string $msg String to translate - * @param mixed $args Array with arguments or multiple arguments in function - * @return string translated string - * @link http://book.cakephp.org/3.0/en/core-libraries/global-constants-and-functions.html#__dx - */ - function __dx($domain, $context, $msg, $args = null) - { - if (!$msg) { - return; - } - - $arguments = func_num_args() === 4 ? (array)$args : array_slice(func_get_args(), 2); - return I18n::translator($domain)->translate( - $msg, - ['_context' => $context] + $arguments - ); - } - -} - -if (!function_exists('__dxn')) { - /** - * Returns correct plural form of message identified by $singular and $plural for count $count. - * Allows you to override the current domain for a single message lookup. - * The context is a unique identifier for the translations string that makes it unique - * for in the same domain. - * - * @param string $domain Domain - * @param string $context Context of the text - * @param string $singular Singular text to translate - * @param string $plural Plural text - * @param int $count Count - * @param mixed $args Array with arguments or multiple arguments in function - * @return mixed plural form of translated string - * @link http://book.cakephp.org/3.0/en/core-libraries/global-constants-and-functions.html#__dxn - */ - function __dxn($domain, $context, $singular, $plural, $count, $args = null) - { - if (!$singular) { - return; - } - - $arguments = func_num_args() === 6 ? (array)$args : array_slice(func_get_args(), 2); - return I18n::translator($domain)->translate( - $singular, - ['_count' => $count, '_singular' => $singular, '_context' => $context] + $arguments - ); - } - -} - if (!function_exists('json_last_error_msg')) { /** * Provides the fallback implementation of json_last_error_msg() available in PHP 5.5 and above.