Permalink
Browse files

Adding and updating docblocks to/of all g11n classes.

  • Loading branch information...
1 parent 5df9f6c commit 693b2253ef44e822dd0d6ca0a09829208d34e122 @davidpersson davidpersson committed Oct 25, 2009
@@ -11,6 +11,25 @@
use \lithium\core\Libraries;
use \lithium\util\Collection;
+/**
+ * Globalization data is not just translated messages, it's validation rules, formats and a lot
+ * more, too. Data is grouped into 4 different kinds of categories: inflection, validation, message
+ * and list.
+ *
+ * Generally speaking is the `Catalog` class allowing us to retrieve and store globalized
+ * data, providing low-level functionality to other classes. It's interface is similar to classes
+ * like Session or Cache and like those extensible through adapters.
+ *
+ * We need to deal with different kinds of sources for this data, but we don't want differing
+ * results depending on the adapter in use. This is why results are kept in a neutral inter-
+ * changeable format. You can rely on getting the same format of obtained results independent
+ * from the adapter they're coming from.
+ *
+ * The class is able to aggregate data from different sources which allows to complement sparse
+ * data. Not all categories must be supported by an individual adapter.
+ *
+ * @todo Extend \lithium\core\Adaptable.
+ */
class Catalog extends \lithium\core\StaticObject {
protected static $_configurations = null;
@@ -12,12 +12,32 @@
use \InvalidArgumentException;
/**
- * Locale class.
+ * The `Locale` class provides methods to deal with locale identifiers. The locale
+ * (here: locale identifier) is used to distinguish among different sets of common
+ * preferences. The identifier used by Lithium is based in it's structure upon Unicode's
+ * language identifier and is compliant to BCP 47.
+ *
+ * `language[_Script][_TERRITORY][_VARIANT]`
+ * - `language` The spoken language, here represented by an ISO 639-1 code,
+ * where not available ISO 639-3 and ISO 639-5 codes are allowed too) tag.
+ * The tag should be lowercased and is required.
+ * - `Script` The tag should have it's first character capitalized, all others
+ * lowercased. The tag is optional.
+ * - `TERRITORY` A geographical area, here represented by an ISO 3166-1 code.
+ * Should be all uppercased and is optional.
+ * - `VARIANT` Should be all uppercased and is optional.
+ *
+ * In order to avoid unnecessary overhead methods accepting a locale identifier require it to
+ * be well-formed according to the structue layed out above. For assuring the correct format
+ * use `Locale::canonicalize()` once on the input locale.
*
* @method string|void language(string $locale) Parses a locale and returns it's language tag.
* @method string|void script(string $locale) Parses a locale and returns it's script tag.
* @method string|void territory(string $locale) Parses a locale and returns it's territory tag.
* @method string|void variant(string $locale) Parses a locale and returns it's variant tag.
+ * @link http://www.unicode.org/reports/tr35/tr35-12.html#Identifiers
+ * @link http://www.rfc-editor.org/rfc/bcp/bcp47.txt
+ * @link http://www.iana.org/assignments/language-subtag-registry
*/
class Locale extends \lithium\core\StaticObject {
@@ -50,7 +70,7 @@ public static function __callStatic($method, $params = array()) {
}
/**
- * Composes a locale from locale tags.
+ * Composes a locale from locale tags. This is the pendant to `Locale::decompose()`.
*
* @param array $tags An array as obtained from `Locale::decompose()`.
* @return string|void A locale with tags separated by underscores or `null`
@@ -70,15 +90,11 @@ public static function compose($tags) {
}
/**
- * Parses a locale into locale tags. A valid locale has the structure and format
- * `language[_Script][_TERRITORY][_VARIANT]`. The language tag is an ISO 639-1 code,
- * where not available ISO 639-3 and ISO 639-5 codes are allowed too. The territory
- * tag is an ISO 3166-1 code.
+ * Parses a locale into locale tags. This is the pendant to `Locale::compose()``.
*
- * @param string $locale I.e. `'en'`, `'en_US'` or `'de_DE'`.
+ * @param string $locale A locale in it's canoncial form i.e. `'en'` or `'fr_CA'`.
* @return array Parsed language, script, territory and variant tags.
* @throws InvalidArgumentException
- * @link http://www.rfc-editor.org/rfc/bcp/bcp47.txt
*/
public static function decompose($locale) {
$regex = '(?P<language>[a-z]{2,3})';
@@ -121,6 +137,7 @@ public static function canonicalize($locale) {
* // returns array('zh_Hans_HK_REVISED', 'zh_Hans_HK', 'zh_Hans', 'zh', 'root')
* }}}
*
+ * @param string $locale A locale in it's canoncial form i.e. `'en'` or `'fr_CA'`.
* @return array Indexed array of locales (starting with the most specific one).
*/
public static function cascade($locale) {
@@ -13,10 +13,24 @@
use \lithium\g11n\Locale;
use \lithium\g11n\Catalog;
+/**
+ * The `Message` class is the interface for retrieving translations of static message
+ * strings throughout the framework. Internally the `Catalog` class is used to access
+ * translation data which must have been created in a 3 step process.
+ * 1. Prepare messages for translation. There are a few best practices making the
+ * process a lot easier. Use entire English sentences (as it gives context) and
+ * split paragraphs into multiple messages. Instead of string concatenation utilize
+ * `String::insert()`-style format strings. Avoid to embed markup into the messages
+ * and do not escape i.e. quotation marks where possible.
+ * 2. Extract messages from the source code and create a template for the translators.
+ * 3. Translate the messages and store the translations.
+ *
+ * @see \lithium\g11n\Catalog
+ */
class Message extends \lithium\core\StaticObject {
/**
- * Returns the translation for a message ID. Translates messages according to current locale.
+ * Returns the translation of a message. Translates messages according to current locale.
* You can use this method either for translating a single message or for messages with a plural
* form. The provided message will be used as a fall back if it isn't translateable. You may
* also use `String::insert()`-style placeholders within message strings and provide
@@ -35,7 +49,6 @@ class Message extends \lithium\core\StaticObject {
* }}}
*
* @param string $singular Either a single or the singular form of the message.
- * Used as the message ID.
* @param array $options Allowed keys are:
* - `'plural'`: Used as a fall back if needed.
* - `'count'`: Used to determine the correct plural form.
@@ -62,12 +75,13 @@ public static function translate($singular, $options = array()) {
}
/**
- * Retrieves a translated message version of a message ID.
+ * Retrieves the translation for a message ID. Uses the `Catalog` class to
+ * access translation data and determines the correct plural form (if necessary).
*
- * @param string $id The singular form of the message.
+ * @param string $id The message ID.
* @param string $locale The target locale.
- * @param integer $count Used to determine the correct plural form (optional).
- * @param string $scope The scope of the message ID (optional).
+ * @param integer $count Used to determine the correct plural form.
+ * @param string $scope The scope of the message ID.
* @return string|void The translated message or `null` if `$singular` is not
* translateable or a plural rule couldn't be found.
* @todo Message pages need caching.
@@ -96,4 +110,5 @@ protected static function _translated($id, $locale, $count = null, $scope = null
}
}
}
+
?>
@@ -11,7 +11,7 @@
use \lithium\util\Set;
/**
- * Base class for all g11n catalog adapters.
+ * The `Base` class is the foundation for all g11n catalog adapters.
*/
abstract class Base extends \lithium\core\Object {
@@ -51,6 +51,11 @@
'template' => array('read' => false, 'write' => false)
));
+ /**
+ * Initializer. Merges redefined categories.
+ *
+ * @return void
+ */
protected function _init() {
parent::_init();
$properties = get_class_vars(__CLASS__);
@@ -73,9 +78,9 @@ public function isSupported($category, $operation) {
/**
* Reads data.
*
- * @param string $category Dot-delimited categoy.
+ * @param string $category Dot-delimited category.
* @param string $locale A locale identifier.
- * @param string $scope The scope for the current request.
+ * @param string $scope The scope for the current operation.
* @return mixed
* @see \lithium\g11n\catalog\adapters\Base::$_categories.
*/
@@ -86,7 +91,7 @@ public function isSupported($category, $operation) {
*
* @param string $category Dot-delimited category.
* @param string $locale A locale identifier.
- * @param string $scope The scope for the current request.
+ * @param string $scope The scope for the current operation.
* @param mixed $data The data to write.
* @return boolean
* @see \lithium\g11n\catalog\adapters\Base::$_categories.
@@ -13,8 +13,17 @@
use \lithium\util\Inflector;
use \lithium\g11n\Locale;
+/**
+ * The `Cldr` class is an adapter which allows reading from the Common Locale Data Repository
+ * maintained by the Unicode Consortium. Writing and deleting is not supported.
+ */
class Cldr extends \lithium\g11n\catalog\adapters\Base {
+ /**
+ * Supported categories.
+ *
+ * @var array
+ */
protected $_categories = array(
'validation' => array(
'postalCode' => array('read' => true)
@@ -26,18 +35,40 @@ class Cldr extends \lithium\g11n\catalog\adapters\Base {
'currency' => array('read' => true)
));
+ /**
+ * Constructor.
+ *
+ * @param array $config Available configuration options are:
+ * - `'path'`: The path to the directory holding the data.
+ * - `'scope'`: Scope to use.
+ * @return void
+ */
public function __construct($config = array()) {
$defaults = array('path' => null, 'scope' => null);
parent::__construct($config + $defaults);
}
+ /**
+ * Initializer. Checks if the configured path exists.
+ *
+ * @return void
+ * @throws \Exception
+ */
protected function _init() {
parent::_init();
if (!is_dir($this->_config['path'])) {
throw new Exception("Cldr directory does not exist at `{$this->_config['path']}`");
}
}
+ /**
+ * Reads data.
+ *
+ * @param string $category Dot-delimited category.
+ * @param string $locale A locale identifier.
+ * @param string $scope The scope for the current operation.
+ * @return mixed
+ */
public function read($category, $locale, $scope) {
if ($scope !== $this->_config['scope']) {
return null;
@@ -97,7 +128,28 @@ public function read($category, $locale, $scope) {
return $this->_parseXml($file, $query, $yield, $post);
}
- protected function _parseXml($file, $query, $yield, $post) {
+ /**
+ * Writing is not supported.
+ *
+ * @param string $category Dot-delimited category.
+ * @param string $locale A locale identifier.
+ * @param string $scope The scope for the current operation.
+ * @param mixed $data The data to write.
+ * @return void
+ */
+ public function write($category, $locale, $scope, $data) {}
+
+ /**
+ * Parses a XML file and retrieves data from it using an XPATH query
+ * and a given closure.
+ *
+ * @param string $file Absolute path to the XML file.
+ * @param string $query An XPATH query to select items.
+ * @param callback $yield A closure which is passed the data from the XPATH query.
+ * @param callback $post A closure for applying formatting to the yielded results.
+ * @return mixed
+ */
+ protected function _parseXml($file, $query, $yield, $post = null) {
$document = new SimpleXmlElement($file, LIBXML_COMPACT, true);
$nodes = $document->xpath($query);
@@ -109,8 +161,6 @@ protected function _parseXml($file, $query, $yield, $post) {
}
return $data;
}
-
- public function write($category, $locale, $scope, $data) {}
}
?>
@@ -12,25 +12,60 @@
use \RecursiveIteratorIterator;
use \RecursiveDirectoryIterator;
+/**
+ * The `Code` class is an adapter which treats files containing code as just another source
+ * of globalized data. In fact it allows for extracting messages which are needed to build
+ * message catalog templates. Currently only code written in PHP is supported through a parser
+ * using the built-in tokenizer.
+ *
+ * @see \lithium\g11n\Message
+ */
class Code extends \lithium\g11n\catalog\adapters\Base {
+ /**
+ * Supported categories.
+ *
+ * @var array
+ */
protected $_categories = array(
'message' => array(
'template' => array('read' => true)
));
+ /**
+ * Constructor.
+ *
+ * @param array $config Available configuration options are:
+ * - `'path'`: The path to the directory holding the data.
+ * - `'scope'`: Scope to use.
+ * @return void
+ */
public function __construct($config = array()) {
$defaults = array('path' => null, 'scope' => null);
parent::__construct($config + $defaults);
}
+ /**
+ * Initializer. Checks if the configured path exists.
+ *
+ * @return void
+ * @throws \Exception
+ */
protected function _init() {
parent::_init();
if (!is_dir($this->_config['path'])) {
throw new Exception("Code directory does not exist at `{$this->_config['path']}`");
}
}
+ /**
+ * Extracts data from files within configured path recursively.
+ *
+ * @param string $category Dot-delimited category.
+ * @param string $locale A locale identifier.
+ * @param string $scope The scope for the current operation.
+ * @return mixed
+ */
public function read($category, $locale, $scope) {
if ($scope !== $this->_config['scope']) {
return null;
@@ -55,6 +90,15 @@ public function read($category, $locale, $scope) {
}
}
+ /**
+ * Writing is not supported.
+ *
+ * @param string $category Dot-delimited category.
+ * @param string $locale A locale identifier.
+ * @param string $scope The scope for the current operation.
+ * @param mixed $data The data to write.
+ * @return void
+ */
public function write($category, $locale, $scope, $data) {}
/**
Oops, something went wrong.

0 comments on commit 693b225

Please sign in to comment.