Merge pull request #2163 from Ragazzo/i18n_docs_improved

i18n docs added

docs/guide/i18n.md

@@ -284,4 +284,101 @@ Formatters
 In order to use formatters you need to install and enable [intl](http://www.php.net/manual/en/intro.intl.php) PHP
 extension.
 
+Examples
+--------
+
+###Translating module messages
+
+If you want to translate messages for a module and avoid using a single translation file for all messages, you can make it like the following:
+
+```php
+<?php
+
+namespace app\modules\users;
+
+use Yii;
+
+class Module extends \yii\base\Module
+{
+	public $controllerNamespace = 'app\modules\users\controllers';
+
+	public function init()
+	{
+		parent::init();
+		$this->registerTranslations();
+	}
+
+	public function registerTranslations()
+	{
+		Yii::$app->i18n->translations['modules/users/*'] = [
+			'class' => 'yii\i18n\PhpMessageSource',
+			'sourceLanguage' => 'en',
+			'basePath' => '@app/modules/users/messages',
+			'fileMap' => [
+				'modules/users/validation' => 'validation.php',
+				'modules/users/form' => 'form.php',
+				...
+			],
+		];
+	}
+
+	public static function t($category, $message, $params = [], $language = null)
+	{
+		return Yii::t('modules/users/' . $category, $message, $params, $language);
+	}
+
+}
+```
+
+In the example above we are using wildcard for matching and then filtering each category per needed file.
+
+###Translating widgets messages
+
+Same rules can be applied for widgets too, for example:
+
+```php
+<?php
+
+namespace app\widgets\menu;
+
+use yii\base\Widget;
+use Yii;
+
+class Menu extends Widget
+{
+
+	public function init()
+	{
+		parent::init();
+		$this->registerTranslations();
+	}
+
+	public function registerTranslations()
+	{
+		$i18n = Yii::$app->i18n;
+		$i18n->translations['widgets/menu/*'] = [
+			'class' => 'yii\i18n\PhpMessageSource',
+			'sourceLanguage' => 'en',
+			'basePath' => '@app/widgets/menu/messages',
+			'fileMap' => [
+				'widgets/menu/messages' => 'messages.php',
+			],
+		];
+	}
+
+	public function run()
+	{
+		echo $this->render('index');
+	}
+
+	public static function t($category, $message, $params = [], $language = null)
+	{
+		return Yii::t('widgets/menu/' . $category, $message, $params, $language);
+	}
+
+}
+```
+
+> **Note**: For widgets you also can use i18n views, same rules as for controllers are applied to them too.
+
 TBD: provided classes overview.