Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 220 lines (204 sloc) 7.733 kb
e7f3c31 GWoo going lithium
gwoo authored
1 <?php
2 /**
3 * Lithium: the most rad php framework
4 *
4f1a9c0 Nate Abele Updating copyright year.
nateabele authored
5 * @copyright Copyright 2011, Union of RAD (http://union-of-rad.org)
e7f3c31 GWoo going lithium
gwoo authored
6 * @license http://opensource.org/licenses/bsd-license.php The BSD License
7 */
8
9 namespace lithium\g11n;
10
6fb3f64 Michael Nitschinger change _use lithium_ commands and remove the prefixed slash
daschl authored
11 use lithium\core\Environment;
12 use lithium\util\String;
13 use lithium\g11n\Catalog;
e7f3c31 GWoo going lithium
gwoo authored
14
693b225 David Persson Adding and updating docblocks to/of all g11n classes.
davidpersson authored
15 /**
fed7b31 David Persson Adding `$tn()` plural shortcut for templates.
davidpersson authored
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
1d53548 David Persson Merge branch '0.3' into 0.3-g11n
davidpersson authored
18 * phrase of ""translating a message" is widely used. This leads to the assumption that it's
8af5a7f GWoo change `Message::shortHands()` to `Message::shorthands()`
gwoo authored
19 * a single step process whereas it' a multi step one. A short description of each step is
fed7b31 David Persson Adding `$tn()` plural shortcut for templates.
davidpersson authored
20 * given here in order to help understanding the purpose of this class through the context
21 * of the process as a whole.
693b225 David Persson Adding and updating docblocks to/of all g11n classes.
davidpersson authored
22 *
cdcd170 David Persson Renaming `Message::shorthands()` to `Message::aliases()`.
davidpersson authored
23 * 1. Marking messages as translatable. `$t()` and `$tn()` (implemented in `aliases()`)
4243e27 David Persson Renaming `Message::contentFilters()` to `shortHands()`.
davidpersson authored
24 * are recognized as message marking and picked up by the extraction parser.
6e20dc2 David Persson Better Message class docblocks.
davidpersson authored
25 *
fed7b31 David Persson Adding `$tn()` plural shortcut for templates.
davidpersson authored
26 * 2. Extracting marked messages. Messages can be extracted through the `g11n`
8af5a7f GWoo change `Message::shortHands()` to `Message::shorthands()`
gwoo authored
27 * command which in turn utilizes the `Catalog` class with the built-in `Code`
fed7b31 David Persson Adding `$tn()` plural shortcut for templates.
davidpersson authored
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
1d53548 David Persson Merge branch '0.3' into 0.3-g11n
davidpersson authored
44 * @see lithium\console\command\G11n
45 * @see lithium\g11n\catalog\adapter\Code
693b225 David Persson Adding and updating docblocks to/of all g11n classes.
davidpersson authored
46 */
e7f3c31 GWoo going lithium
gwoo authored
47 class Message extends \lithium\core\StaticObject {
48
49 /**
02cca47 David Persson Enabling caching of message pages.
davidpersson authored
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 /**
42125a4 David Persson Rewriting `Message::translate()` to use filters.
davidpersson authored
59 * Translates a message according to the current or provided locale
60 * and into it's correct plural form.
e7f3c31 GWoo going lithium
gwoo authored
61 *
62 * Usage:
63 * {{{
64 * Message::translate('Mind the gap.');
42125a4 David Persson Rewriting `Message::translate()` to use filters.
davidpersson authored
65 * Message::translate('house', array('count' => 23));
e7f3c31 GWoo going lithium
gwoo authored
66 * }}}
67 *
4b3eb0e David Persson Refactoring `Message` and related filters.
davidpersson authored
68 * `String::insert()`-style placeholders may be used within the message
69 * and replacements provided directly within the `options` argument.
70 *
71 * Example:
72 * {{{
76e9009 David Persson Updating examples in `Message` docblocks.
davidpersson authored
73 * Message::translate('I can see {:count} bike.');
fca4eda David Persson Fixing typo in `Message::translate()` docblock.
davidpersson authored
74 * Message::translate('This painting is {:color}.', array(
76e9009 David Persson Updating examples in `Message` docblocks.
davidpersson authored
75 * 'color' => Message::translate('silver'),
4b3eb0e David Persson Refactoring `Message` and related filters.
davidpersson authored
76 * ));
77 * }}}
78 *
f76ad26 David Persson Updating code formatting to conform with standards.
davidpersson authored
79 * @see lithium\util\String::insert()
42125a4 David Persson Rewriting `Message::translate()` to use filters.
davidpersson authored
80 * @param string $id The id to use when looking up the translation.
81 * @param array $options Valid options are:
158a7e1 David Persson `Message::translate()` to make count absolute before passing.
davidpersson authored
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.
e7f3c31 GWoo going lithium
gwoo authored
89 * - `'locale'`: The target locale, defaults to current locale.
5a40337 David Persson Updating Set dockblocks.
davidpersson authored
90 * - `'scope'`: The scope of the message.
8af5a7f GWoo change `Message::shortHands()` to `Message::shorthands()`
gwoo authored
91 * - `'default'`: Is used as a fall back if `_translated()` returns
92 * without a result.
fc31c7f David Persson Adding `'noop'` option to `Message::translate()`. Adding test.
davidpersson authored
93 * - `'noop'`: If `true` no whatsoever lookup takes place.
8af5a7f GWoo change `Message::shortHands()` to `Message::shorthands()`
gwoo authored
94 * @return string|void The translation or the value of the `'default'` option if none
95 * could be found.
e7f3c31 GWoo going lithium
gwoo authored
96 */
f80098d Nate Abele Adding type hinting to constructor `$config` arrays and all applicable `...
nateabele authored
97 public static function translate($id, array $options = array()) {
4b3eb0e David Persson Refactoring `Message` and related filters.
davidpersson authored
98 $defaults = array(
99 'count' => 1,
8741bbb David Persson Enabling g11n specific environment settings.
davidpersson authored
100 'locale' => Environment::get('locale'),
4b3eb0e David Persson Refactoring `Message` and related filters.
davidpersson authored
101 'scope' => null,
fc31c7f David Persson Adding `'noop'` option to `Message::translate()`. Adding test.
davidpersson authored
102 'default' => null,
26c2192 David Persson QA: Removing trailing comma in arrays, lowercasing some keywords.
davidpersson authored
103 'noop' => false
4b3eb0e David Persson Refactoring `Message` and related filters.
davidpersson authored
104 );
56c7cb7 David Persson Updating `Message::translate()` to not extract options and possibly over...
davidpersson authored
105 $options += $defaults;
4b3eb0e David Persson Refactoring `Message` and related filters.
davidpersson authored
106
56c7cb7 David Persson Updating `Message::translate()` to not extract options and possibly over...
davidpersson authored
107 if ($options['noop']) {
fc31c7f David Persson Adding `'noop'` option to `Message::translate()`. Adding test.
davidpersson authored
108 $result = null;
109 } else {
56c7cb7 David Persson Updating `Message::translate()` to not extract options and possibly over...
davidpersson authored
110 $result = static::_translated($id, abs($options['count']), $options['locale'], array(
111 'scope' => $options['scope']
112 ));
fc31c7f David Persson Adding `'noop'` option to `Message::translate()`. Adding test.
davidpersson authored
113 }
e7f3c31 GWoo going lithium
gwoo authored
114
56c7cb7 David Persson Updating `Message::translate()` to not extract options and possibly over...
davidpersson authored
115 if ($result || $options['default']) {
116 return String::insert($result ?: $options['default'], $options);
4b3eb0e David Persson Refactoring `Message` and related filters.
davidpersson authored
117 }
118 }
f3015b0 Nate Abele Refactoring `template\View` to remove dependency on `g11n\Media`. Conten...
nateabele authored
119
120 /**
cdcd170 David Persson Renaming `Message::shorthands()` to `Message::aliases()`.
davidpersson authored
121 * Returns an array containing named closures which are aliases for `translate()`.
8af5a7f GWoo change `Message::shortHands()` to `Message::shorthands()`
gwoo authored
122 * They can be embedded as content filters in the template layer using a filter for
4243e27 David Persson Renaming `Message::contentFilters()` to `shortHands()`.
davidpersson authored
123 * `Media::_handle()` or be used in other places where needed.
f3015b0 Nate Abele Refactoring `template\View` to remove dependency on `g11n\Media`. Conten...
nateabele authored
124 *
4243e27 David Persson Renaming `Message::contentFilters()` to `shortHands()`.
davidpersson authored
125 * Usage:
126 * {{{
76e9009 David Persson Updating examples in `Message` docblocks.
davidpersson authored
127 * $t('bike');
128 * $tn('bike', 'bikes', array('count' => 3));
4243e27 David Persson Renaming `Message::contentFilters()` to `shortHands()`.
davidpersson authored
129 * }}}
130 *
131 * Using in a method:
132 * {{{
133 * public function index() {
cdcd170 David Persson Renaming `Message::shorthands()` to `Message::aliases()`.
davidpersson authored
134 * extract(Message::aliases());
4243e27 David Persson Renaming `Message::contentFilters()` to `shortHands()`.
davidpersson authored
135 * $notice = $t('look');
136 * }
137 * }}}
138 *
139 * @see lithium\net\http\Media::_handle()
f76ad26 David Persson Updating code formatting to conform with standards.
davidpersson authored
140 * @return array Named aliases (`'t'` and `'tn'`) for translation functions.
f3015b0 Nate Abele Refactoring `template\View` to remove dependency on `g11n\Media`. Conten...
nateabele authored
141 */
cdcd170 David Persson Renaming `Message::shorthands()` to `Message::aliases()`.
davidpersson authored
142 public static function aliases() {
f80098d Nate Abele Adding type hinting to constructor `$config` arrays and all applicable `...
nateabele authored
143 $t = function($message, array $options = array()) {
14d8e15 Nate Abele Refactoring `util\Collection` to remove dependency on `http\Media`. Adde...
nateabele authored
144 return Message::translate($message, $options + array('default' => $message));
f3015b0 Nate Abele Refactoring `template\View` to remove dependency on `g11n\Media`. Conten...
nateabele authored
145 };
f80098d Nate Abele Adding type hinting to constructor `$config` arrays and all applicable `...
nateabele authored
146 $tn = function($message1, $message2, $count, array $options = array()) {
f3015b0 Nate Abele Refactoring `template\View` to remove dependency on `g11n\Media`. Conten...
nateabele authored
147 return Message::translate($message1, $options + compact('count') + array(
148 'default' => $count == 1 ? $message1 : $message2
149 ));
150 };
151 return compact('t', 'tn');
152 }
153
e7f3c31 GWoo going lithium
gwoo authored
154 /**
02cca47 David Persson Enabling caching of message pages.
davidpersson authored
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 /**
42125a4 David Persson Rewriting `Message::translate()` to use filters.
davidpersson authored
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.
e7f3c31 GWoo going lithium
gwoo authored
176 *
f76ad26 David Persson Updating code formatting to conform with standards.
davidpersson authored
177 * @see lithium\g11n\Catalog
42125a4 David Persson Rewriting `Message::translate()` to use filters.
davidpersson authored
178 * @param string $id The lookup key.
4b3eb0e David Persson Refactoring `Message` and related filters.
davidpersson authored
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:
42125a4 David Persson Rewriting `Message::translate()` to use filters.
davidpersson authored
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.
4b3eb0e David Persson Refactoring `Message` and related filters.
davidpersson authored
185 * @filter
e7f3c31 GWoo going lithium
gwoo authored
186 */
f80098d Nate Abele Adding type hinting to constructor `$config` arrays and all applicable `...
nateabele authored
187 protected static function _translated($id, $count, $locale, array $options = array()) {
4b3eb0e David Persson Refactoring `Message` and related filters.
davidpersson authored
188 $params = compact('id', 'count', 'locale', 'options');
42125a4 David Persson Rewriting `Message::translate()` to use filters.
davidpersson authored
189
02cca47 David Persson Enabling caching of message pages.
davidpersson authored
190 $cache =& static::$_cachedPages;
279d766 Svemir Brkic replaced __METHOD__ with __FUNCTION__ in several statis::_filter calls, ...
svemir authored
191 return static::_filter(__FUNCTION__, $params, function($self, $params) use (&$cache) {
4b3eb0e David Persson Refactoring `Message` and related filters.
davidpersson authored
192 extract($params);
e7f3c31 GWoo going lithium
gwoo authored
193
02cca47 David Persson Enabling caching of message pages.
davidpersson authored
194 if (!isset($cache[$options['scope']][$locale])) {
d29e3f5 David Persson Changing the signature of `Catalog::read()` and `Catalog::write()`.
davidpersson authored
195 $cache[$options['scope']][$locale] = Catalog::read(
196 true, 'message', $locale, $options
197 );
02cca47 David Persson Enabling caching of message pages.
davidpersson authored
198 }
199 $page = $cache[$options['scope']][$locale];
177f12d David Persson Refactoring `Catalog`.
davidpersson authored
200
4b3eb0e David Persson Refactoring `Message` and related filters.
davidpersson authored
201 if (!isset($page[$id])) {
202 return null;
203 }
30646bb David Persson Updating logic for _translated_ in `_merge()` of catalog `Base` adapter.
davidpersson authored
204 if (!is_array($page[$id])) {
205 return $page[$id];
206 }
e7f3c31 GWoo going lithium
gwoo authored
207
1256974 David Persson Renaming catalog category `message.plural` to `message.pluralRule`.
davidpersson authored
208 if (!isset($page['pluralRule']) || !is_callable($page['pluralRule'])) {
4b3eb0e David Persson Refactoring `Message` and related filters.
davidpersson authored
209 return null;
210 }
1256974 David Persson Renaming catalog category `message.plural` to `message.pluralRule`.
davidpersson authored
211 $key = $page['pluralRule']($count);
4b3eb0e David Persson Refactoring `Message` and related filters.
davidpersson authored
212
30646bb David Persson Updating logic for _translated_ in `_merge()` of catalog `Base` adapter.
davidpersson authored
213 if (isset($page[$id][$key])) {
214 return $page[$id][$key];
4b3eb0e David Persson Refactoring `Message` and related filters.
davidpersson authored
215 }
216 });
e7f3c31 GWoo going lithium
gwoo authored
217 }
218 }
693b225 David Persson Adding and updating docblocks to/of all g11n classes.
davidpersson authored
219
2bea4d8 GWoo fixing bad closing tag in g11n\Message
gwoo authored
220 ?>
Something went wrong with that request. Please try again.