1: <?php
2: /**
3: * CMessageSource class file.
4: *
5: * @author Qiang Xue <qiang.xue@gmail.com>
6: * @link http://www.yiiframework.com/
7: * @copyright 2008-2013 Yii Software LLC
8: * @license http://www.yiiframework.com/license/
9: */
10:
11: /**
12: * CMessageSource is the base class for message translation repository classes.
13: *
14: * A message source is an application component that provides message internationalization (i18n).
15: * It stores messages translated in different languages and provides
16: * these translated versions when requested.
17: *
18: * A concrete class must implement {@link loadMessages} or override {@link translateMessage}.
19: *
20: * @property string $language The language that the source messages are written in.
21: * Defaults to {@link CApplication::language application language}.
22: *
23: * @author Qiang Xue <qiang.xue@gmail.com>
24: * @package system.i18n
25: * @since 1.0
26: */
27: abstract class CMessageSource extends CApplicationComponent
28: {
29: /**
30: * @var boolean whether to force message translation when the source and target languages are the same.
31: * Defaults to false, meaning translation is only performed when source and target languages are different.
32: * @since 1.1.4
33: */
34: public $forceTranslation=false;
35:
36: private $_language;
37: private $_messages=array();
38:
39: /**
40: * Loads the message translation for the specified language and category.
41: * @param string $category the message category
42: * @param string $language the target language
43: * @return array the loaded messages
44: */
45: abstract protected function loadMessages($category,$language);
46:
47: /**
48: * @return string the language that the source messages are written in.
49: * Defaults to {@link CApplication::language application language}.
50: */
51: public function getLanguage()
52: {
53: return $this->_language===null ? Yii::app()->sourceLanguage : $this->_language;
54: }
55:
56: /**
57: * @param string $language the language that the source messages are written in.
58: */
59: public function setLanguage($language)
60: {
61: $this->_language=CLocale::getCanonicalID($language);
62: }
63:
64: /**
65: * Translates a message to the specified language.
66: *
67: * Note, if the specified language is the same as
68: * the {@link getLanguage source message language}, messages will NOT be translated.
69: *
70: * If the message is not found in the translations, an {@link onMissingTranslation}
71: * event will be raised. Handlers can mark this message or do some
72: * default handling. The {@link CMissingTranslationEvent::message}
73: * property of the event parameter will be returned.
74: *
75: * @param string $category the message category
76: * @param string $message the message to be translated
77: * @param string $language the target language. If null (default), the {@link CApplication::getLanguage application language} will be used.
78: * @return string the translated message (or the original message if translation is not needed)
79: */
80: public function translate($category,$message,$language=null)
81: {
82: if($language===null)
83: $language=Yii::app()->getLanguage();
84: if($this->forceTranslation || $language!==$this->getLanguage())
85: return $this->translateMessage($category,$message,$language);
86: else
87: return $message;
88: }
89:
90: /**
91: * Translates the specified message.
92: * If the message is not found, an {@link onMissingTranslation}
93: * event will be raised.
94: * @param string $category the category that the message belongs to
95: * @param string $message the message to be translated
96: * @param string $language the target language
97: * @return string the translated message
98: */
99: protected function translateMessage($category,$message,$language)
100: {
101: $key=$language.'.'.$category;
102: if(!isset($this->_messages[$key]))
103: $this->_messages[$key]=$this->loadMessages($category,$language);
104: if(isset($this->_messages[$key][$message]) && $this->_messages[$key][$message]!=='')
105: return $this->_messages[$key][$message];
106: elseif($this->hasEventHandler('onMissingTranslation'))
107: {
108: $event=new CMissingTranslationEvent($this,$category,$message,$language);
109: $this->onMissingTranslation($event);
110: return $event->message;
111: }
112: else
113: return $message;
114: }
115:
116: /**
117: * Raised when a message cannot be translated.
118: * Handlers may log this message or do some default handling.
119: * The {@link CMissingTranslationEvent::message} property
120: * will be returned by {@link translateMessage}.
121: * @param CMissingTranslationEvent $event the event parameter
122: */
123: public function onMissingTranslation($event)
124: {
125: $this->raiseEvent('onMissingTranslation',$event);
126: }
127: }
128:
129:
130: /**
131: * CMissingTranslationEvent represents the parameter for the {@link CMessageSource::onMissingTranslation onMissingTranslation} event.
132: *
133: * @author Qiang Xue <qiang.xue@gmail.com>
134: * @package system.i18n
135: * @since 1.0
136: */
137: class CMissingTranslationEvent extends CEvent
138: {
139: /**
140: * @var string the message to be translated
141: */
142: public $message;
143: /**
144: * @var string the category that the message belongs to
145: */
146: public $category;
147: /**
148: * @var string the ID of the language that the message is to be translated to
149: */
150: public $language;
151:
152: /**
153: * Constructor.
154: * @param mixed $sender sender of this event
155: * @param string $category the category that the message belongs to
156: * @param string $message the message to be translated
157: * @param string $language the ID of the language that the message is to be translated to
158: */
159: public function __construct($sender,$category,$message,$language)
160: {
161: parent::__construct($sender);
162: $this->message=$message;
163: $this->category=$category;
164: $this->language=$language;
165: }
166: }
167: