Skip to content
This repository
Newer
Older
100644 220 lines (204 sloc) 7.733 kb
e7f3c313 » gwoo
2009-10-12 going lithium
1 <?php
2 /**
3 * Lithium: the most rad php framework
4 *
4f1a9c0d » nateabele
2011-03-28 Updating copyright year.
5 * @copyright Copyright 2011, Union of RAD (http://union-of-rad.org)
e7f3c313 » gwoo
2009-10-12 going lithium
6 * @license http://opensource.org/licenses/bsd-license.php The BSD License
7 */
8
9 namespace lithium\g11n;
10
6fb3f644 » daschl
2010-11-16 change _use lithium_ commands and remove the prefixed slash
11 use lithium\core\Environment;
12 use lithium\util\String;
13 use lithium\g11n\Catalog;
e7f3c313 » gwoo
2009-10-12 going lithium
14
693b2253 » davidpersson
2009-10-25 Adding and updating docblocks to/of all g11n classes.
15 /**
fed7b31d » davidpersson
2009-11-21 Adding `$tn()` plural shortcut for templates.
16 * The `Message` class is concerned with an aspect of globalizing static message strings
17 * throughout the framework and applications. When referring to message globalization the
1d53548b » davidpersson
2009-12-08 Merge branch '0.3' into 0.3-g11n
18 * phrase of ""translating a message" is widely used. This leads to the assumption that it's
8af5a7f2 » gwoo
2010-02-14 change `Message::shortHands()` to `Message::shorthands()`
19 * a single step process whereas it' a multi step one. A short description of each step is
fed7b31d » davidpersson
2009-11-21 Adding `$tn()` plural shortcut for templates.
20 * given here in order to help understanding the purpose of this class through the context
21 * of the process as a whole.
693b2253 » davidpersson
2009-10-25 Adding and updating docblocks to/of all g11n classes.
22 *
cdcd170e » davidpersson
2010-02-15 Renaming `Message::shorthands()` to `Message::aliases()`.
23 * 1. Marking messages as translatable. `$t()` and `$tn()` (implemented in `aliases()`)
4243e278 » davidpersson
2010-02-09 Renaming `Message::contentFilters()` to `shortHands()`.
24 * are recognized as message marking and picked up by the extraction parser.
6e20dc20 » davidpersson
2009-10-25 Better Message class docblocks.
25 *
fed7b31d » davidpersson
2009-11-21 Adding `$tn()` plural shortcut for templates.
26 * 2. Extracting marked messages. Messages can be extracted through the `g11n`
8af5a7f2 » gwoo
2010-02-14 change `Message::shortHands()` to `Message::shorthands()`
27 * command which in turn utilizes the `Catalog` class with the built-in `Code`
fed7b31d » davidpersson
2009-11-21 Adding `$tn()` plural shortcut for templates.
28 * adapter or other custom adapters which are concerned with extracting
29 * translatable content.
30 *
31 * 3. Creating a message template from extracted messages. Templates are created
32 * by the `g11n` command using the `Catalog` class with an adapter for a format
33 * you prefer.
34 *
35 * 4. Translating messages. The actual translation of messages by translators
36 * happens outside using external applications.
37 *
38 * 5. Storing translated messages. Translations are most often stored by the external
39 * applications itself.
40 *
41 * 6. Retrieving the translation for a message. See description for `Message::translate()`.
42 *
43 * @see lithium\g11n\Catalog
1d53548b » davidpersson
2009-12-08 Merge branch '0.3' into 0.3-g11n
44 * @see lithium\console\command\G11n
45 * @see lithium\g11n\catalog\adapter\Code
693b2253 » davidpersson
2009-10-25 Adding and updating docblocks to/of all g11n classes.
46 */
e7f3c313 » gwoo
2009-10-12 going lithium
47 class Message extends \lithium\core\StaticObject {
48
49 /**
02cca472 » davidpersson
2010-03-17 Enabling caching of message pages.
50 * Holds cached message pages generated and used
51 * by `lithium\g11n\Message::_translated()`.
52 *
53 * @var array
54 * @see lithium\g11n\Message::_translated()
55 */
56 protected static $_cachedPages = array();
57
58 /**
42125a47 » davidpersson
2009-11-25 Rewriting `Message::translate()` to use filters.
59 * Translates a message according to the current or provided locale
60 * and into it's correct plural form.
e7f3c313 » gwoo
2009-10-12 going lithium
61 *
62 * Usage:
63 * {{{
64 * Message::translate('Mind the gap.');
42125a47 » davidpersson
2009-11-25 Rewriting `Message::translate()` to use filters.
65 * Message::translate('house', array('count' => 23));
e7f3c313 » gwoo
2009-10-12 going lithium
66 * }}}
67 *
4b3eb0eb » davidpersson
2010-02-09 Refactoring `Message` and related filters.
68 * `String::insert()`-style placeholders may be used within the message
69 * and replacements provided directly within the `options` argument.
70 *
71 * Example:
72 * {{{
76e90099 » davidpersson
2010-02-09 Updating examples in `Message` docblocks.
73 * Message::translate('I can see {:count} bike.');
fca4edac » davidpersson
2010-02-25 Fixing typo in `Message::translate()` docblock.
74 * Message::translate('This painting is {:color}.', array(
76e90099 » davidpersson
2010-02-09 Updating examples in `Message` docblocks.
75 * 'color' => Message::translate('silver'),
4b3eb0eb » davidpersson
2010-02-09 Refactoring `Message` and related filters.
76 * ));
77 * }}}
78 *
f76ad26a » davidpersson
2010-02-24 Updating code formatting to conform with standards.
79 * @see lithium\util\String::insert()
42125a47 » davidpersson
2009-11-25 Rewriting `Message::translate()` to use filters.
80 * @param string $id The id to use when looking up the translation.
81 * @param array $options Valid options are:
158a7e1c » davidpersson
2010-02-25 `Message::translate()` to make count absolute before passing.
82 * - `'count'`: Used to determine the correct plural form. You can either pass
83 * a signed or unsigned integer, the behavior when passing other types
84 * is yet undefined.
85 * The count is made absolute before being passed to the pluralization
86 * function. This has the effect that that with i.e. an English
87 * pluralization function passing `-1` results in a singular
88 * translation.
e7f3c313 » gwoo
2009-10-12 going lithium
89 * - `'locale'`: The target locale, defaults to current locale.
5a40337c » davidpersson
2009-10-20 Updating Set dockblocks.
90 * - `'scope'`: The scope of the message.
8af5a7f2 » gwoo
2010-02-14 change `Message::shortHands()` to `Message::shorthands()`
91 * - `'default'`: Is used as a fall back if `_translated()` returns
92 * without a result.
fc31c7f5 » davidpersson
2010-02-09 Adding `'noop'` option to `Message::translate()`. Adding test.
93 * - `'noop'`: If `true` no whatsoever lookup takes place.
8af5a7f2 » gwoo
2010-02-14 change `Message::shortHands()` to `Message::shorthands()`
94 * @return string|void The translation or the value of the `'default'` option if none
95 * could be found.
e7f3c313 » gwoo
2009-10-12 going lithium
96 */
f80098da » nateabele
2010-02-16 Adding type hinting to constructor `$config` arrays and all applicabl…
97 public static function translate($id, array $options = array()) {
4b3eb0eb » davidpersson
2010-02-09 Refactoring `Message` and related filters.
98 $defaults = array(
99 'count' => 1,
8741bbba » davidpersson
2010-02-13 Enabling g11n specific environment settings.
100 'locale' => Environment::get('locale'),
4b3eb0eb » davidpersson
2010-02-09 Refactoring `Message` and related filters.
101 'scope' => null,
fc31c7f5 » davidpersson
2010-02-09 Adding `'noop'` option to `Message::translate()`. Adding test.
102 'default' => null,
26c2192d » davidpersson
2011-03-23 QA: Removing trailing comma in arrays, lowercasing some keywords.
103 'noop' => false
4b3eb0eb » davidpersson
2010-02-09 Refactoring `Message` and related filters.
104 );
56c7cb72 » davidpersson
2011-03-27 Updating `Message::translate()` to not extract options and possibly o…
105 $options += $defaults;
4b3eb0eb » davidpersson
2010-02-09 Refactoring `Message` and related filters.
106
56c7cb72 » davidpersson
2011-03-27 Updating `Message::translate()` to not extract options and possibly o…
107 if ($options['noop']) {
fc31c7f5 » davidpersson
2010-02-09 Adding `'noop'` option to `Message::translate()`. Adding test.
108 $result = null;
109 } else {
56c7cb72 » davidpersson
2011-03-27 Updating `Message::translate()` to not extract options and possibly o…
110 $result = static::_translated($id, abs($options['count']), $options['locale'], array(
111 'scope' => $options['scope']
112 ));
fc31c7f5 » davidpersson
2010-02-09 Adding `'noop'` option to `Message::translate()`. Adding test.
113 }
e7f3c313 » gwoo
2009-10-12 going lithium
114
56c7cb72 » davidpersson
2011-03-27 Updating `Message::translate()` to not extract options and possibly o…
115 if ($result || $options['default']) {
116 return String::insert($result ?: $options['default'], $options);
4b3eb0eb » davidpersson
2010-02-09 Refactoring `Message` and related filters.
117 }
118 }
f3015b0c » nateabele
2010-01-22 Refactoring `template\View` to remove dependency on `g11n\Media`. Con…
119
120 /**
cdcd170e » davidpersson
2010-02-15 Renaming `Message::shorthands()` to `Message::aliases()`.
121 * Returns an array containing named closures which are aliases for `translate()`.
8af5a7f2 » gwoo
2010-02-14 change `Message::shortHands()` to `Message::shorthands()`
122 * They can be embedded as content filters in the template layer using a filter for
4243e278 » davidpersson
2010-02-09 Renaming `Message::contentFilters()` to `shortHands()`.
123 * `Media::_handle()` or be used in other places where needed.
f3015b0c » nateabele
2010-01-22 Refactoring `template\View` to remove dependency on `g11n\Media`. Con…
124 *
4243e278 » davidpersson
2010-02-09 Renaming `Message::contentFilters()` to `shortHands()`.
125 * Usage:
126 * {{{
76e90099 » davidpersson
2010-02-09 Updating examples in `Message` docblocks.
127 * $t('bike');
128 * $tn('bike', 'bikes', array('count' => 3));
4243e278 » davidpersson
2010-02-09 Renaming `Message::contentFilters()` to `shortHands()`.
129 * }}}
130 *
131 * Using in a method:
132 * {{{
133 * public function index() {
cdcd170e » davidpersson
2010-02-15 Renaming `Message::shorthands()` to `Message::aliases()`.
134 * extract(Message::aliases());
4243e278 » davidpersson
2010-02-09 Renaming `Message::contentFilters()` to `shortHands()`.
135 * $notice = $t('look');
136 * }
137 * }}}
138 *
139 * @see lithium\net\http\Media::_handle()
f76ad26a » davidpersson
2010-02-24 Updating code formatting to conform with standards.
140 * @return array Named aliases (`'t'` and `'tn'`) for translation functions.
f3015b0c » nateabele
2010-01-22 Refactoring `template\View` to remove dependency on `g11n\Media`. Con…
141 */
cdcd170e » davidpersson
2010-02-15 Renaming `Message::shorthands()` to `Message::aliases()`.
142 public static function aliases() {
f80098da » nateabele
2010-02-16 Adding type hinting to constructor `$config` arrays and all applicabl…
143 $t = function($message, array $options = array()) {
14d8e152 » nateabele
2010-02-03 Refactoring `util\Collection` to remove dependency on `http\Media`. A…
144 return Message::translate($message, $options + array('default' => $message));
f3015b0c » nateabele
2010-01-22 Refactoring `template\View` to remove dependency on `g11n\Media`. Con…
145 };
f80098da » nateabele
2010-02-16 Adding type hinting to constructor `$config` arrays and all applicabl…
146 $tn = function($message1, $message2, $count, array $options = array()) {
f3015b0c » nateabele
2010-01-22 Refactoring `template\View` to remove dependency on `g11n\Media`. Con…
147 return Message::translate($message1, $options + compact('count') + array(
148 'default' => $count == 1 ? $message1 : $message2
149 ));
150 };
151 return compact('t', 'tn');
152 }
153
e7f3c313 » gwoo
2009-10-12 going lithium
154 /**
02cca472 » davidpersson
2010-03-17 Enabling caching of message pages.
155 * Returns or sets the page cache used for mapping message ids to translations.
156 *
157 * @param array $cache A multidimensional array to use when pre-populating the cache. The
158 * structure of the array is `scope/locale/id`. If `false`, the cache is cleared.
159 * @return array Returns an array of cached pages, formatted per the description for `$cache`.
160 */
161 public static function cache($cache = null) {
162 if ($cache === false) {
163 static::$_cachedPages = array();
164 }
165 if (is_array($cache)) {
166 static::$_cachedPages += $cache;
167 }
168 return static::$_cachedPages;
169 }
170
171 /**
42125a47 » davidpersson
2009-11-25 Rewriting `Message::translate()` to use filters.
172 * Retrieves translations through the `Catalog` class by using `$id` as the lookup
173 * key and taking the current or - if specified - the provided locale as well as the
174 * scope into account. Hereupon the correct plural form is determined by passing the
175 * value of the `'count'` option to a closure.
e7f3c313 » gwoo
2009-10-12 going lithium
176 *
f76ad26a » davidpersson
2010-02-24 Updating code formatting to conform with standards.
177 * @see lithium\g11n\Catalog
42125a47 » davidpersson
2009-11-25 Rewriting `Message::translate()` to use filters.
178 * @param string $id The lookup key.
4b3eb0eb » davidpersson
2010-02-09 Refactoring `Message` and related filters.
179 * @param integer $count Used to determine the correct plural form.
180 * @param string $locale The target locale.
181 * @param array $options Passed through to `Catalog::read()`. Valid options are:
42125a47 » davidpersson
2009-11-25 Rewriting `Message::translate()` to use filters.
182 * - `'scope'`: The scope of the message.
183 * @return string|void The translation or `null` if none could be found or the plural
184 * form could not be determined.
4b3eb0eb » davidpersson
2010-02-09 Refactoring `Message` and related filters.
185 * @filter
e7f3c313 » gwoo
2009-10-12 going lithium
186 */
f80098da » nateabele
2010-02-16 Adding type hinting to constructor `$config` arrays and all applicabl…
187 protected static function _translated($id, $count, $locale, array $options = array()) {
4b3eb0eb » davidpersson
2010-02-09 Refactoring `Message` and related filters.
188 $params = compact('id', 'count', 'locale', 'options');
42125a47 » davidpersson
2009-11-25 Rewriting `Message::translate()` to use filters.
189
02cca472 » davidpersson
2010-03-17 Enabling caching of message pages.
190 $cache =& static::$_cachedPages;
279d766a » svemir
2011-01-11 replaced __METHOD__ with __FUNCTION__ in several statis::_filter call…
191 return static::_filter(__FUNCTION__, $params, function($self, $params) use (&$cache) {
4b3eb0eb » davidpersson
2010-02-09 Refactoring `Message` and related filters.
192 extract($params);
e7f3c313 » gwoo
2009-10-12 going lithium
193
02cca472 » davidpersson
2010-03-17 Enabling caching of message pages.
194 if (!isset($cache[$options['scope']][$locale])) {
d29e3f53 » davidpersson
2010-07-16 Changing the signature of `Catalog::read()` and `Catalog::write()`.
195 $cache[$options['scope']][$locale] = Catalog::read(
196 true, 'message', $locale, $options
197 );
02cca472 » davidpersson
2010-03-17 Enabling caching of message pages.
198 }
199 $page = $cache[$options['scope']][$locale];
177f12d0 » davidpersson
2010-01-06 Refactoring `Catalog`.
200
4b3eb0eb » davidpersson
2010-02-09 Refactoring `Message` and related filters.
201 if (!isset($page[$id])) {
202 return null;
203 }
30646bb2 » davidpersson
2010-02-25 Updating logic for _translated_ in `_merge()` of catalog `Base` adapter.
204 if (!is_array($page[$id])) {
205 return $page[$id];
206 }
e7f3c313 » gwoo
2009-10-12 going lithium
207
12569744 » davidpersson
2010-03-15 Renaming catalog category `message.plural` to `message.pluralRule`.
208 if (!isset($page['pluralRule']) || !is_callable($page['pluralRule'])) {
4b3eb0eb » davidpersson
2010-02-09 Refactoring `Message` and related filters.
209 return null;
210 }
12569744 » davidpersson
2010-03-15 Renaming catalog category `message.plural` to `message.pluralRule`.
211 $key = $page['pluralRule']($count);
4b3eb0eb » davidpersson
2010-02-09 Refactoring `Message` and related filters.
212
30646bb2 » davidpersson
2010-02-25 Updating logic for _translated_ in `_merge()` of catalog `Base` adapter.
213 if (isset($page[$id][$key])) {
214 return $page[$id][$key];
4b3eb0eb » davidpersson
2010-02-09 Refactoring `Message` and related filters.
215 }
216 });
e7f3c313 » gwoo
2009-10-12 going lithium
217 }
218 }
693b2253 » davidpersson
2009-10-25 Adding and updating docblocks to/of all g11n classes.
219
2bea4d8c » gwoo
2009-10-20 fixing bad closing tag in g11n\Message
220 ?>
Something went wrong with that request. Please try again.