## Apache Zeta Components Manual :: File Source for translation.php

## Source for file translation.php

Documentation is available at translation.php

1. <?php
2. /**
3. *
4. * Licensed to the Apache Software Foundation (ASF) under one
5. * or more contributor license agreements. See the NOTICE file
6. * distributed with this work for additional information
7. * regarding copyright ownership. The ASF licenses this file
8. * to you under the Apache License, Version 2.0 (the
9. * "License"); you may not use this file except in compliance
10. * with the License. You may obtain a copy of the License at
11. *
12. * http://www.apache.org/licenses/LICENSE-2.0
13. *
14. * Unless required by applicable law or agreed to in writing,
15. * software distributed under the License is distributed on an
16. * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17. * KIND, either express or implied. See the License for the
18. * specific language governing permissions and limitations
19. * under the License.
20. *
21. * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0
22. * @version //autogentag//
23. * @filesource
24. * @package Translation
25. */
27. /**
28. * ezcTranslation is a container that holds the translated strings for a
29. * specific context.
30. *
31. * ezcTranslation objects are returned by the ezcTranslationManager for every
32. * requested context.
33. *
34. * For an example see {@link ezcTranslationManager}.
35. *
36. * @package Translation
37. * @version //autogentag//
38. * @mainclass
39. */
40. class ezcTranslation
41. {
42. /**
43. * Contains an array where the key is the original string (often
44. * English) and the element is an object of the class
45. * ezcTranslationData (a struct).
46. *
47. * @var array(string=>ezcTranslationData)
48. */
49. private $translationMap;
51. /**
52. * Constructs the ezcTranslation object.
53. *
54. * The constructor receives an array containing the translation elements,
55. * and builds up an internal map between the original string and the
56. * accompanying translation data.
57. *
58. * @param array(ezcTranslationData) $data
59. */
60. function __construct ( array $data )
61. {
62. $this->translationMap = array();
63. foreach ( $data as $translationElement )
64. {
65. $this->translationMap[$translationElement->original] = $translationElement;
66. }
67. }
69. /**
70. * Returns the replacement for the key $key from the parameters $params.
71. *
72. * The params array is an associative array in the form array('key'=>'value').
73. *
74. * This is a callback function used by the getTranslation() method for each
75. * matched parameter in the translated string.
76. *
77. * @param string $key
78. * @param array $params
79. * @return string
80. */
81. private function parameterCallback( $key, array $params )
82. {
83. if ( !isset( $params[strtolower( $key )] ) )
84. {
85. throw new ezcTranslationParameterMissingException ( $key );
86. }
87. $string = $params[ strtolower ( $key )];
88. // We use ctype_upper() here to check if the first character of the key
89. // is an uppercase letter. If it is then we make the first character of
90. // the returned translation also an upper case character. With this
91. // mechanism we can correctly upper case translated strings if word
92. // order changes. See
93. // {@link ezcTranslationTest::testGetStringWithParameters} for an
94. // example of this.
95. if ( ctype_upper ( $key[0] ) )
96. {
97. $string = ucfirst ( $string );
98. }
99. return $string;
100. }
102. /**
103. * Returns the translated version of the original string $key.
104. *
105. * This method returns a translated string and substitutes the parameters $param
106. * in the localized string.
107. *
108. * @throws ezcTranslationKeyNotAvailableException when the key is not
109. * available in the translation definitions
110. * @throws ezcTranslationParameterMissingException when not enough
111. * parameters are passed for a parameterized string
112. * @param string $key
113. * @param array(string=>string) $params
114. * @return string
115. */
116. public function getTranslation ( $key, array $params = array() )
117. {
118. if ( !isset( $this->translationMap[$key] ) )
119. {
120. throw new ezcTranslationKeyNotAvailableException ( $key );
121. }
122. $translatedString = $this->translationMap[$key]->translation;
123. // Little optimization to prevent preg if not needed, it bails out too
124. // if there is just a percent sign in the string without a valid
125. // parameter-identifier, but we can live with that.
126. if ( strstr ( $translatedString, '%' ) === false )
127. {
128. return $translatedString;
129. }
130. // So we do have a possibility of a parameterized string, replace those
131. // with the parameters. The callback function can actually throw an
132. // exception to tell that there was a missing parameter.
133. return (string) preg_replace ( '@%(([A-Za-z][a-z_]*[a-z])|[1-9])@e', '$this->parameterCallback("\\1", $params)', $translatedString );
134. }
136. /**
137. * Returns the replacement for the key $key from the parameters $params.
138. *
139. * The params array is an associative array in the form array('key'=>'value').
140. *
141. * This is a callback function used by the compileTranslation() method for each
142. * matched parameter in the translated string.
143. *
144. * @param string $key
145. * @param array $params
146. * @return string
147. */
148. private function parameterCallbackCompile( $key, array $params )
149. {
150. if ( !isset( $params[strtolower( $key )] ) )
151. {
152. throw new ezcTranslationParameterMissingException ( $key );
153. }
154. // We use ctype_upper() here to check if the first character of the key
155. // is an uppercase letter. If it is then we make the first character of
156. // the returned translation also an upper case character. With this
157. // mechanism we can correctly upper case translated strings if word
158. // order changes. See
159. // {@link ezcTranslationTest::testGetStringWithParameters} for an
160. // example of this.
161. if ( ctype_upper ( $key[0] ) )
162. {
163. $string = "' . ucfirst(". $params[ strtolower ( $key )] . ") . '";
164. }
165. else
166. {
167. $string = "' . ". $params[ strtolower ( $key )] . " . '";
168. }
169. return $string;
170. }
172. /**
173. * Returns the translated version of the original string $key.
174. *
175. * This method returns a translated string and substitutes the parameters $param
176. * in the localized string with PHP code to place the variable data into
177. * the string at a later moment. Instead of the values for each of the
178. * parameters, an expression to get to the data should be sumbitted into
179. * the $params array.
180. *
181. * <code>
182. * echo $translation->compileTranslation( "Hello #%nr", array( "nr" => '$this->send->nr' ) );
183. * </code>
184. *
185. * Will return something like:
186. * <code>
187. * 'Hallo #' . $this->send->nr . ''
188. * </code>
189. *
190. * @param string $key
191. * @param array(string=>string) $params
192. * @return string
193. */
194. public function compileTranslation ( $key, array $params = array() )
195. {
196. if ( !isset( $this->translationMap[$key] ) )
197. {
198. throw new ezcTranslationKeyNotAvailableException ( $key );
199. }
200. $translatedString = var_export ( $this->translationMap[$key]->translation, true );
201. // Little optimization to prevent preg if not needed, it bails out too
202. // if there is just a percent sign in the string without a valid
203. // parameter-identifier, but we can live with that.
204. if ( strstr ( $translatedString, '%' ) === false )
205. {
206. return $translatedString;
207. }
208. // So we do have a possibility of a parameterized string, replace those
209. // with the parameters. The callback function can actually throw an
210. // exception to tell that there was a missing parameter.
211. return (string) preg_replace ( '@%(([A-Za-z][a-z_]*[a-z])|[1-9])@e', '$this->parameterCallbackCompile("\\1", $params)', $translatedString );
212. }
213. }
214. ?>

Documentation generated by phpDocumentor 1.4.3