Skip to content

Y
yii2
Commit fa07b12f by Carsten Brandt
Options

Merge branch 'master' of github.com:yiisoft/yii2

* 'master' of github.com:yiisoft/yii2: Update test-fixtures.md docs/guide-ja/tutorial-mailing.md - added [ci skip] docs/guide/tutorial-mailing.md - corrections [ci skip] docs/guide/tutorial-i18n.md revised [ci skip] Fixed typo docs/guide-ja updated [ci skip] docs/guide-ja/tutorial-i18n.md - completed [ci skip] docs/guide-ja/tutorial-i18n.md - WIP docs/guide-ja/tutorial-i18n.md - WIP [ci skip] docs/guide-ja/tutorial-i18n.md - WIP [ci skip] Update start-hello.md yii\db\ActiveQuery phpDoc fix
parents 92f22165 cb77a4d4
Showing with 890 additions and 65 deletions
docs/guide-ja/README.md
......@@ -165,8 +165,8 @@ RESTful ウェブサービス
* [アプリケーションを一から構築する](tutorial-start-from-scratch.md)
* [コンソールコマンド](tutorial-console.md)
* [コアバリデータ](tutorial-core-validators.md)
* **翻訳中** [国際化](tutorial-i18n.md)
* **翻訳中** [メール](tutorial-mailing.md)
* [国際化](tutorial-i18n.md)
* [メール送信](tutorial-mailing.md)
* **翻訳中** [パフォーマンスチューニング](tutorial-performance-tuning.md)
* **翻訳中** [共有ホスト環境](tutorial-shared-hosting.md)
* **翻訳中** [テンプレートエンジン](tutorial-template-engines.md)
......
docs/guide-ja/db-active-record.md
......@@ -91,6 +91,11 @@ $customer->email = 'jane@example.com';
$customer->save();
```
> Note|注意: 自明なことですが、カラム名が直接にアクティブレコードクラスの属性名になりますので、データベースの命名スキーマでアンダースコアを使用している場合はアンダースコアを持つ属性名になります。
> 例えば、`user_name` というカラムは、アクティブレコードのオブジェクトでは `$user->user_name` としてアクセスされることになります。
> コードスタイルが気になるのであれば、データベースの命名スキーマも camelCase を使用しなければなりません。
> しかしながら、camelCase の使用は要求されてはいません。Yii は他のどのような命名スタイルでも十分に動作します。
データベースに接続する
----------------------
......
docs/guide-ja/test-fixtures.md
フィクスチャ
============
> Note|注意: この節はまだ執筆中です。
フィクスチャはテストの重要な部分です。
フィクスチャの主な目的は、テストを期待されている方法で繰り返して実行できるように、環境を固定された既知の状態に設定することです。
Yii は、フィクスチャを正確に定義して容易に使うことを可能にするフィクスチャフレームワークを提供しています。
......@@ -42,6 +40,12 @@ class UserFixture extends ActiveFixture
> [[yii\test\ActiveFixture::tableName]] プロパティまたは [[yii\test\ActiveFixture::modelClass]] プロパティを設定することによって、テーブルを指定することが出来ます。
> 後者を使う場合は、`modelClass` によって指定される `ActiveRecord` クラスからテーブル名が取得されます。
> Note|注意: [[yii\test\ActiveFixture]] は SQL データベースにのみ適しています。
> NoSQL データベースのためには、Yii は以下の `ActiveFixture` クラスを提供しています。
>
> - Mongo DB: [[yii\mongodb\ActiveFixture]]
> - Elasticsearch: [[yii\elasticsearch\ActiveFixture]] (バージョン 2.0.2 以降)
`ActiveFixture` フィクスチャのフィクスチャデータは通常は `FixturePath/data/TableName.php` として配置されるファイルで提供されます。
ここで `FixturePath` はフィクスチャクラスファイルを含むディレクトリを意味し、`TableName` はフィクスチャと関連付けられているテーブルの名前です。
......@@ -92,6 +96,10 @@ class UserProfileFixture extends ActiveFixture
}
```
依存関係は、また、複数のフィクスチャが正しく定義された順序でロードされ、アンロードされることを保証します。
上記の例では、全ての外部キー参照が存在することを保証するために `UserFixture` は常に `UserProfileFixture` の前にロードされます。
また、同じ理由によって、`UserFixture` は常に `UserProfileFixture` がアンロードされた後でアンロードされます。
上記では、DB テーブルに関してフィクスチャを定義する方法を示しました。
DB と関係しないフィクスチャ (例えば、何らかのファイルやディレクトリに関するフィクスチャ) を定義するためには、より汎用的な基底クラス [[yii\test\Fixture]] から拡張して、[[yii\test\Fixture::load()|load()]] と [[yii\test\Fixture::unload()|unload()]] のメソッドをオーバーライドすることが出来ます。
......@@ -232,7 +240,9 @@ data\
Managing Fixtures
=================
// todo: this tutorial may be merged into test-fixture.md
> Note: This section is under development.
>
> todo: this tutorial may be merged with the above part of test-fixtures.md
Fixtures are important part of testing. Their main purpose is to populate you with data that needed by testing
different cases. With this data using your tests becoming more efficient and useful.
......
docs/guide-ja/tutorial-i18n.md 0 → 100644
国際化
======
> Note|注意: この節はまだ執筆中です。
国際化 (I18N) とは、工学的な変更を伴わずにさまざまな言語と地域に順応できるように、ソフトウェアアプリケーションを設計するプロセスを指します。
潜在的なユーザが世界中にいるウェブアプリケーションにとっては、このことは特に重要な意味を持ちます。
Yii は、メッセージの翻訳、数字や日付の書式設定など、ウェブサイトの国際化を手助けするいくつかのツールを提供しています。
ロケールと言語
--------------
Yii のアプリケーションでは二つの言語が定義されます。
すなわち、[[yii\base\Application::$sourceLanguage|ソース言語]] と [[yii\base\Application::$language|ターゲット言語]] です。
ソース言語とは、次のように、コードに直接書かれているオリジナルのアプリケーションメッセージの言語です。
```php
echo \Yii::t('app', 'I am a message!');
```
ターゲット言語は、現在のページを表示するのに使用されるべき言語、すなわち、オリジナルのメッセージの翻訳先となるべき言語です。
これはアプリケーションの構成情報において、次のように定義されているものです。
```php
return [
'id' => 'applicationID',
'basePath' => dirname(__DIR__),
// ...
'language' => 'ru-RU', // <- ここ !
// ...
]
```
> **Tip**|ヒント: [[yii\base\Application::$sourceLanguage|ソース言語]] のデフォルト値は英語であり、この値は変えないことが推奨されます。
> 理由は、英語から他の言語への翻訳者を見つける方が、非英語から非英語への翻訳者を見つけるより簡単だからです。
アプリケーションの言語を実行時に設定して、ユーザが選択した言語をターゲットにすることが可能です。
この操作は、全ての出力に対して正しく効果を発揮するように、まだ出力が何も生成されていない時点で行われなければなりません。
そのためには、アプリケーションのターゲット言語プロパティを望ましい値に変更するだけです。
```php
\Yii::$app->language = 'zh-CN';
```
言語/ロケールの書式は `ll-CC` です。`ll` は [ISO-639](http://www.loc.gov/standards/iso639-2/) に従った二文字または三文字の小文字の言語コードであり、`CC` は [ISO-3166](http://www.iso.org/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html) に従った国コードです。
> **Note**|注意: ロケールの概念と構文に関する詳細な情報については、[ICU プロジェクトのドキュメント](http://userguide.icu-project.org/locale#TOC-The-Locale-Concept) を参照してください。
メッセージ翻訳
--------------
メッセージ翻訳は、アプリケーションによって出力されたメッセージを別の言語に翻訳して、さまざまな国のユーザが自国語でアプリケーションを使えるようにするために使用されるものです。
Yii におけるメッセージ翻訳機能は、ソース言語からターゲット言語へとメッセージの翻訳を探すという単純な動作をします。
メッセージ翻訳機能を使うためには、オリジナルのメッセージ文字列を [[Yii::t()]] メソッドで包みます。
このメソッドの最初のパラメータは、メッセージの生成元であるアプリケーションのさまざまな部分を区別するためのカテゴリであり、二番目のパラメータはメッセージそのものです。
```php
echo \Yii::t('app', 'This is a string to translate!');
```
Yii は `i18n` [アプリケーションコンポーネント](structure-application-components.md) に定義されているメッセージソースの中から、現在の [[yii\base\Application::$language|アプリケーション言語]] に従って、適切な翻訳を読み込もうと試みます。
メッセージソースは、翻訳メッセージを提供する一群のファイルまたはデータベースです。
次の構成情報の例は、メッセージを PHP ファイルから取得するメッセージソースを定義するものです。
```php
'components' => [
// ...
'i18n' => [
'translations' => [
'app*' => [
'class' => 'yii\i18n\PhpMessageSource',
//'basePath' => '@app/messages',
//'sourceLanguage' => 'en-US',
'fileMap' => [
'app' => 'app.php',
'app/error' => 'error.php',
],
],
],
],
],
```
上記において `app*` は、このメッセージソースによって扱われるカテゴリを指定するパターンです。
この例では、`app` から始まる全てのカテゴリをこのメッセージソースで処理します。
メッセージファイルは `@app/messages`、すなわち、アプリケーションディレクトリの下の `messages` ディレクトリに配置されています。
[[yii\i18n\PhpMessageSource::fileMap|fileMap]] 配列が、どのカテゴリに対してどのファイルが使われるべきかを定義しています。
`fileMap` を構成する代りに、カテゴリ名をファイル名として使用する規約 (例えば、`app/error` というカテゴリは、[[yii\i18n\PhpMessageSource::basePath|basePath]] の下の `app/error.php` というファイル名に帰結します) に依存することも出来ます。
`\Yii::t('app', 'This is a string to translate!')` というメッセージを翻訳するとき、アプリケーション言語が `ja-JP` である場合は、Yii は利用できるメッセージのリストを取得するために、まず `@app/messages/ja-JP/app.php` というファイルを探します。
`ja-JP` ディレクトリにファイルが無い場合は、失敗であるとする前に、`ja` ディレクトリも探します。
メッセージを PHP ファイルに保存する [[yii\i18n\PhpMessageSource|PhpMessageSource]] に加えて、Yii は二つのクラスを提供しています。
- [[yii\i18n\GettextMessageSource]] - GNU Gettext の MO ファイルまたは PO ファイルを使用
- [[yii\i18n\DbMessageSource]] - データベースを使用
> Note|訳注: 以下においては、メッセージ書式の理解を助けるために、原文にはない日本語への翻訳例 (とその出力結果) をコードサンプルに追加しています。
### 名前付きプレースホルダ
翻訳メッセージには、翻訳後に対応する値に置き換えられるパラメータを追加することが出来ます。
このパラメータの形式は、次の例で示すように、パラメータ名を波括弧で囲むものです。
```php
$username = 'Alexander';
echo \Yii::t('app', 'Hello, {username}!', [
'username' => $username,
]);
// 翻訳: '{username} さん、こんにちは!'
```
パラメータへの代入には波括弧を使わないことに注意してください。
### 序数プレースホルダ
```php
$sum = 42;
echo \Yii::t('app', 'Balance: {0}', $sum);
// 翻訳: '差引残高: {0}'
```
> **Tip**|ヒント: メッセージ文字列の意味が分らなくならないように努めて、あまりに多くの序数プレースホルダを使うことは避けてください。
> 翻訳者にはソース文字列しか無く、従って、各プレースホルダに何が入るのかは自明でなければならない、ということを忘れないでください。
### 高度なプレースホルダの書式
高度な機能を使うためには、[intl PHP 拡張](http://www.php.net/manual/ja/intro.intl.php) をインストールして有効にする必要があります。
それをインストールして有効にして初めて、プレースホルダのための拡張構文を使うことが出来るようになります。
すなわち、デフォルトの書式を意味する短い形式 `{プレースホルダ名, タイプ}`、あるいは、書式のスタイルを指定できる完全な形式 `{プレースホルダ名, タイプ, スタイル}` を使うことが出来るようになります。
完全なリファレンスは [ICU ウェブサイト](http://icu-project.org/apiref/icu4c/classMessageFormat.html) で入手可能ですが、以下においてはいくつかの例を示します。
#### 数値
```php
$sum = 42;
echo \Yii::t('app', 'Balance: {0, number}', $sum);
// 翻訳: '差引残高: {0, number}'
// 出力: '差引残高: 12,345'
```
内蔵のスタイル (`integer`、`currency`、`percent`) の一つを指定することが出来ます。
```php
$sum = 42;
echo \Yii::t('app', 'Balance: {0, number, currency}', $sum);
// 翻訳: '差引残高: {0, number, currency}'
// 出力: '差引残高: &yen; 12,345'
```
または、カスタムパターンを指定することも出来ます。
```php
$sum = 42;
echo \Yii::t('app', 'Balance: {0, number, ,000,000000}', $sum);
// 翻訳: '差引残高: {0, number, ,000,000000}'
// 出力: '差引残高: 000,012345'
```
[書式のリファレンス](http://icu-project.org/apiref/icu4c/classicu_1_1DecimalFormat.html).
#### 日付
```php
echo \Yii::t('app', 'Today is {0, date}', time());
// 翻訳: '今日は {0, date} です。'
// 出力: '今日は 2015/01/07 です。'
```
内蔵の書式は、`short`、`medium`、`long`、そして `full` です。
```php
echo \Yii::t('app', 'Today is {0, date, short}', time());
// 翻訳: '今日は {0, date, short} です。'
// 出力: '今日は 2015/01/07 です。'
```
カスタムパターンを指定することも出来ます。
```php
echo \Yii::t('app', 'Today is {0, date, yyyy-MM-dd}', time());
// 翻訳: '今日は {0, date, yyyy-MM-dd} です。'
// 出力: '今日は 2015-01-07 です。'
```
[書式のリファレンス](http://icu-project.org/apiref/icu4c/classicu_1_1SimpleDateFormat.html).
#### 時刻
```php
echo \Yii::t('app', 'It is {0, time}', time());
// 翻訳: '現在 {0, time} です。'
// 出力: '現在 22:37:47 です。'
```
内蔵の書式は、`short`、`medium`、`long`、そして `full` です。
```php
echo \Yii::t('app', 'It is {0, time, short}', time());
// 翻訳: '現在 {0, time, short} です。'
// 出力: '現在 22:37 です。'
```
カスタムパターンを指定することも出来ます。
```php
echo \Yii::t('app', 'It is {0, date, HH:mm}', time());
// 翻訳: '現在 {0, time, HH:mm} です。'
// 出力: '現在 22:37 です。'
```
[書式のリファレンス](http://icu-project.org/apiref/icu4c/classicu_1_1SimpleDateFormat.html).
#### 綴り
```php
echo \Yii::t('app', '{n, number} is spelled as {n, spellout}', ['n' => 12345]);
// 翻訳: '{n, number} は、文字で綴ると {n, spellout} です。'
// 出力: '12,345 は、文字で綴ると 一万二千三百四十五 です。'
```
#### 序数
```php
echo \Yii::t('app', 'You are the {n, ordinal} visitor here!', ['n' => 42]);
```
これは、"You are the 42nd visitor here!" というメッセージになります。
> Note|訳注: 上記のソースメッセージを、プレースホルダの書式指定を守って日本語に翻訳すると、'あなたはこのサイトの {n, ordinal} の訪問者です' となります。
> しかし、その出力結果は、'あなたはこのサイトの 第42 の訪問者です' となり、意味は通じますが、日本語としては若干不自然なものになります。
>
> プレースホルダの書式指定は、翻訳時に変更することが可能であるだけでなく、進んで変更すべき場合すらあります。
>
> この場合も、'あなたはこのサイトの {n} 番目の訪問者です' のように、プレースホルダの書式も含めて全体を翻訳する方が良いでしょう。
#### 継続時間
```php
echo \Yii::t('app', 'You are here for {n, duration} already!', ['n' => 47]);
```
これは、"You are here for 47 sec. already!" というメッセージになります。
> Note|訳注: このソースメッセージを 'あなたはこのサイトに既に {n, duration} の間滞在しています' と翻訳した場合の出力結果は、'あなたはこのサイトに既に 47 の間滞在しています' となります。
> ICU ライブラリのバグでしょうか。これも、プレースホルダの書式も含めて全体を翻訳し直す方が良いようです。
#### 複数形
言語によって、複数形の語形変化はさまざまに異なります。
Yii は、さまざまな形式の複数形語形変化に対応したメッセージ翻訳のための便利な方法を提供しています。
それは、非常に複雑な規則に対しても、十分に機能するものです。
語形変化の規則を直接に処理する代りに、特定の状況における語形変化した言葉の翻訳を提供するだけで十分です。
```php
echo \Yii::t('app', 'There {n, plural, =0{are no cats} =1{is one cat} other{are # cats}}!', ['n' => $n]);
```
結果は以下のようになります。
- `$n = 0` の場合は "There are no cats!"
- `$n = 1` の場合は "There is one cat!"
- そして `$n = 42` の場合は "There are 42 cats!"
上記の複数形規則の引数において、`=0` はぴったりゼロ、`=1` はぴったり 1、そして `other` はそれ以外の数を表します。
`#` は `n` の値によって置き換えられます。
英語以外の言語では、これほど単純ではありません。
例えば、次はロシア語の例です。
```
Здесь {n, plural, =0{котов нет} =1{есть один кот} one{# кот} few{# кота} many{# котов} other{# кота}}!
```
上の例について言及する価値があると思われるのは、`=1` が `n = 1` にぴったりと一致するのに対して、`one` が `21` や `101` などに一致する、ということです。
注意して欲しいのは、あなたの [[yii\base\Application::$sourceLanguage|ソース言語]] を `ru_RU` に設定しなければ、このロシア語のメッセージを `Yii::t()` の中に直接に書くことは出来ない、ということです。
ただし、ソース言語を `ru_RU` に設定することは推奨されません。
むしろ、このような文字列はメッセージファイルまたは (DB ソースが使われている場合は) メッセージデータベースに入れるべきです。
Yii は翻訳された言語の文字列にある複数形規則を使います。翻訳が入手できない場合にはソース言語の複数形規則にフォールバックします。
あなたの言語について、どのような語形変化を指定すべきかを学習するためには、[unicode.org にある規則のリファレンス](http://unicode.org/repos/cldr-tmp/trunk/diff/supplemental/language_plural_rules.html) を参照してください。
> Note|訳注: 上記のソースメッセージの日本語翻訳は以下のようなものになります。
>
> '猫は{n, plural, =0{いません} other{#匹います}}。'
>
> 日本語では単数形と複数形を区別しませんので、たいていの場合、`=0` と `other` を指定するだけで事足ります。
> 横着をして、`{n, plural, ...}` を `{n, number}` に置き換えても、多分、大きな問題は生じないでしょう。
#### 選択肢
キーワードに基づいて表現を選択することが出来ます。
この場合のパターンは、キーワードに対する表現の割り当てを指定し、デフォルトの表現を提供するものです。
```php
echo \Yii::t('app', '{name} is a {gender} and {gender, select, female{she} male{he} other{it}} loves Yii!', [
'name' => 'Snoopy',
'gender' => 'dog',
]);
```
これは "Snoopy is a dog and it loves Yii!" となります。
式の中で、`female` と `male` が `gender` が取り得る値であり、`other` がそれらに一致しない値を処理します。
波括弧の中の文字列は下位の式であり、単なる文字列でも、さらにプレースホルダを持つ文字列でも構いません。
> Note|訳注: 翻訳: '{name} は {gender} であり、{gender, select, female{彼女} male{彼} other{それ}}は Yii を愛しています。'
>
> 出力: 'Snoopy は dog であり、それは Yii を愛しています。'
### デフォルトのメッセージソースを指定する
他のメッセージソースにマッチしないカテゴリのフォールバックとして使用されるデフォルトのメッセージソースを指定することが出来ます。
このメッセージソースは `*` によってマークされなければなりません。
そうするためには、アプリケーションの構成情報に次のように追加します。
```php
// i18n コンポーネントを構成する
'i18n' => [
'translations' => [
'*' => [
'class' => 'yii\i18n\PhpMessageSource'
],
],
],
```
こうすることで、個別に構成することなくカテゴリを使うことが可能になり、Yii 1.1 の振る舞いと同じになります。
カテゴリのメッセージは、デフォルトの翻訳の `basePath` すなわち `@app/messages` の下にあるファイルから読み込まれます。
```php
echo Yii::t('not_specified_category', 'message from unspecified category');
```
この場合、メッセージは `@app/messages/<LanguageCode>/not_specified_category.php` から読み込まれます。
### モジュールのメッセージを翻訳する
モジュール用のメッセージを翻訳したいけれども、全てのメッセージに対して一つの翻訳ファイルを使うことは避けたい、という場合には、次のようにすることが出来ます。
```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-US',
'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);
}
}
```
上記の例では、マッチングのためにワイルドカードを使い、次に必要なファイルごとに各カテゴリをフィルタリングしています。
`fileMap` を使わずに、カテゴリを同じ名前のファイルにマップする規約を使って済ませることも出来ます。
以上のようにすれば、直接に `Module::t('validation', 'your custom validation message')` や `Module::t('form', 'some form label')` などを使用することが出来ます。
### ウィジェットのメッセージを翻訳する
モジュールに適用できる同じ規則をウィジェットにも適用することが出来ます。例えば、
```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-US',
'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);
}
}
```
`fileMap` を使わずに、カテゴリを同じ名前のファイルにマップする規約を使って済ませることも出来ます。
これで、直接に `Menu::t('messages', 'new messages {messages}', ['{messages}' => 10])` を使用することが出来ます。
> **Note**|注意: ウィジェットのためには i18n ビューも使うことが出来ます。コントローラのための同じ規則がウィジェットにも適用されます。
### フレームワークメッセージを翻訳する
Yii には、バリデーションエラーとその他いくつかの文字列に対するデフォルトの翻訳メッセージが付属しています。
これらのメッセージは、全て 'yii' というカテゴリの中にあります。
場合によっては、あなたのアプリケーションのために、デフォルトのフレームワークメッセージの翻訳を修正したいことがあるでしょう。
そうするためには、`i18n` [アプリケーションコンポーネント](structure-application-components.md) を以下のように構成してください。
```php
'i18n' => [
'translations' => [
'yii' => [
'class' => 'yii\i18n\PhpMessageSource',
'sourceLanguage' => 'en-US',
'basePath' => '@app/messages'
],
],
],
```
これで、あなたの修正した翻訳を `@app/messages/<language>/yii.php` に置くことが出来ます。
### 欠落している翻訳の処理
ソースに翻訳が欠落している場合でも、Yii はリクエストされたメッセージの内容を原文で表示します。
このような振舞いは、原文のメッセージが正当かつ詳細なテキストである場合には、非常に好都合です。
しかし、場合によっては、それだけでは十分ではありません。
リクエストされた翻訳がソースに欠落しているときに、何らかの特別な処理を実行する必要がある場合もあります。
そういう処理は、[[yii\i18n\MessageSource]] の [[yii\i18n\MessageSource::EVENT_MISSING_TRANSLATION|missingTranslation]] イベントを使うことによって達成できます。
例えば、全ての欠落している翻訳を簡単に見つけられるように、何か目立つマークを付けることにしましょう。
最初にイベントハンドラをセットアップする必要がありますが、それはアプリケーションの構成によって行うことが出来ます。
```php
'components' => [
// ...
'i18n' => [
'translations' => [
'app*' => [
'class' => 'yii\i18n\PhpMessageSource',
'fileMap' => [
'app' => 'app.php',
'app/error' => 'error.php',
],
'on missingTranslation' => ['app\components\TranslationEventHandler', 'handleMissingTranslation']
],
],
],
],
```
次に、私たち独自のイベントハンドラを実装する必要があります。
```php
<?php
namespace app\components;
use yii\i18n\MissingTranslationEvent;
class TranslationEventHandler
{
public static function handleMissingTranslation(MissingTranslationEvent $event) {
$event->translatedMessage = "@MISSING: {$event->category}.{$event->message} FOR LANGUAGE {$event->language} @";
}
}
```
このイベントハンドラによって [[yii\i18n\MissingTranslationEvent::translatedMessage]] がセットされた場合は、それが翻訳結果として表示されます。
> Note|注意: 全てのメッセージソースは、欠落した翻訳をそれぞれ独自に処理します。
> いくつかのメッセージソースを使っていて、それらが同じ方法で欠落した翻訳を取り扱うようにしたい場合は、対応するイベントハンドラを全てのメッセージソースそれぞれに割り当てなければなりません。
ビュー
------
前の項で説明したようなメッセージの翻訳の代りに、ビューの中で `i18n` を使ってさまざまな言語に対するサポートを提供することも出来ます。
例えば、`views/site/index.php` というビューがあり、それのロシア語のための特別版を作りたい場合は、現在のコントローラ/ウィジェットのビューパスの下に `ru-RU` フォルダを作って、ロシア語のためのファイルを `views/site/ru-RU/index.php` として置きます。
そうすると、Yii は、現在の言語のためのファイルが存在する場合はそれをロードし、何も見つからなかった場合はオリジナルのビューファイルにフォールバックします。
> **Note**|注意: 言語が `en-US` と指定されている場合、対応するビューが無いと、Yii は `en` の下でビューを探して、そこにも無ければ、オリジナルのビューを使います。
数値と日付の値を書式設定する
----------------------------
詳細は [データフォーマッタ](output-formatter.md) の節を参照してください。
PHP 環境をセットアップする <a name="setup-environment"></a>
--------------------------
Yii は、[[yii\i18n\Formatter]] クラスの数値や日付の書式設定や、[[yii\i18n\MessageFormatter]] を使うメッセージのフォーマッティングなど、ほとんどの国際化機能を提供するために [PHP intl 拡張](http://php.net/manual/ja/book.intl.php) を使います。
この二つのクラスは、`intl` がインストールされていない場合に備えて基本的な機能を提供するフォールバックを実装しています。
だだし、このフォールバックの実装は、英語のサイトでのみ十分に機能するものであり、たとえ英語のサイトであっても、PHP intl 拡張によって利用可能になる一連の豊かな機能を提供できるものではありません。
従って、PHP intl 拡張のインストールが強く推奨されます。
[PHP intl 拡張](http://php.net/manual/ja/book.intl.php) は、さまざまに異なる全てのロケールについて知識と書式の規則を提供する [ICU ライブラリ](http://site.icu-project.org/) に基礎を置いています。
この事実により、日付や数値の書式設定、また、メッセージのフォーマッティングで利用できる構文は、PHP バイナリとともにコンパイルされる ICU ライブラリのバージョンの違いによって異なってきます。
あなたのウェブサイトが全ての環境で同じ出力をすることを確実にするために、全ての環境において PHP intl 拡張をインストールし、PHP とともにコンパイルされた ICU ライブラリのバージョンが同一であることを確認することが推奨されます。
どのバージョンの ICU が PHP によって使われているかを知るために、次のスクリプトを走らせることが出来ます。
このスクリプトは、使用されている PHP と ICU のバージョンを出力します。
```php
<?php
echo "PHP: " . PHP_VERSION . "\n";
echo "ICU: " . INTL_ICU_VERSION . "\n";
```
このドキュメントで説明されている全ての機能を使うことが出来るように、ICU のバージョンが 49 以上であることを推奨します。
49 未満のバージョンに欠落している主要な機能の一つが、複数形規則における `#` プレースホルダです。
入手できる ICU バージョン については、<http://site.icu-project.org/download> を参照してください。
バージョン番号の採番方式が 4.8 リリースの後に変更されて、最初の二つの数字が結合されたことに注意してください。
すなわち、ICU 4.8、ICU 49、ICU 50 という順序です。
これに加えて、ICU ライブラリとともに出荷されるタイムゾーンデータベースの情報も古くなっている可能性があります。
タイムゾーンデータベースの更新に関する詳細は [ICU マニュアル](http://userguide.icu-project.org/datetime/timezone#TOC-Updating-the-Time-Zone-Data) を参照してください。
出力の書式設定には ICU タイムゾーンデータベースが使用されますが、PHP によって使われるタイムゾーンデータベースも影響する可能性があります。
PHP のタイムゾーンデータベースは、[`timezonedb` pecl パッケージ](http://pecl.php.net/package/timezonedb) の最新版をインストールすることによって更新することが出来ます。
docs/guide-ja/tutorial-mailing.md 0 → 100644
メール送信
==========
> Note|注意: この節はまだ執筆中です。
Yii は電子メールの作成と送信をサポートしています。
ただし、フレームワークのコアは内容作成の機能と基本的なインタフェイスだけを提供します。
実際のメール送信メカニズムはエクステンションによって提供されるべきです。
と言うのは、メール送信はプロジェクトが異なるごとに異なる実装が必要とされるでしょうし、通常、外部のサービスやライブラリに依存するものだからです。
ごく一般的な場合であれば、[yii2-swiftmailer](https://github.com/yiisoft/yii2/tree/master/extensions/swiftmailer) 公式エクステンションを使用することが出来ます。
構成
----
メールコンポーネントの構成は、あなたが選んだエクステンションに依存します。
一般的には、アプリケーションの構成情報は次のようなものになる筈です。
```php
return [
//....
'components' => [
'mailer' => [
'class' => 'yii\swiftmailer\Mailer',
],
],
];
```
基本的な使用方法
----------------
いったん `mailer` コンポーネントを構成すれば、次のコードを使って電子メールのメッセージを送信することが出来るようになります。
```php
Yii::$app->mailer->compose()
->setFrom('from@domain.com')
->setTo('to@domain.com')
->setSubject('メッセージの題')
->setTextBody('プレーンテキストのコンテント')
->setHtmlBody('<b>HTML のコンテント</b>')
->send();
```
上の例では、`compose()` メソッドでメールメッセージのインスタンスを作成し、それに値を投入して送信しています。
必要であれば、このプロセスにもっと複雑なロジックを置くことも可能です。
```php
$message = Yii::$app->mailer->compose();
if (Yii::$app->user->isGuest) {
$message->setFrom('from@domain.com')
} else {
$message->setFrom(Yii::$app->user->identity->email)
}
$message->setTo(Yii::$app->params['adminEmail'])
->setSubject('メッセージの題')
->setTextBody('プレーンテキストのコンテント')
->send();
```
> Note|注意: すべての 'mailer' エクステンションは、二つの主要なクラス、すなわち、'Mailer' と 'Message' のセットとして提供されます。
'Mailer' は常に 'Message' のクラス名と仕様を知っています。
'Message' オブジェクトのインスタンスを直接に作成しようとしてはいけません。常に `compose()` メソッドを使って作成してください。
いくつかのメッセージを一度に送信することも出来ます。
```php
$messages = [];
foreach ($users as $user) {
$messages[] = Yii::$app->mailer->compose()
// ...
->setTo($user->email);
}
Yii::$app->mailer->sendMultiple($messages);
```
几帳面なメールエクステンションの中には、単一のネットワークメッセージを使うなどして、この手法から利益を得るものもあるかもしれません。
メールのコンテントを作成する
----------------------------
Yii は実際のメールメッセージを特別なビューファイルによって作成することを許容しています。
デフォルトでは、それらのファイルは '@app/mail' というパスに配置されなければなりません。
以下はメールビューファイルの内容の例です。
```php
<?php
use yii\helpers\Html;
use yii\helpers\Url;
/* @var $this \yii\web\View ビューコンポーネントのインスタンス */
/* @var $message \yii\mail\BaseMessage 新しく作成されたメールメッセージのインスタンス */
?>
<h2>ワンクリックで私たちのサイトのホームページを訪問することが出来ます</h2>
<?= Html::a('ホームページへ', Url::home('http')) ?>
```
ビューファイルによってメッセージを作成するためには、単に `compose()` メソッドにビューの名前を渡すだけで十分です。
```php
Yii::$app->mailer->compose('home-link') // ここでビューのレンダリング結果がメッセージのボディになります
->setFrom('from@domain.com')
->setTo('to@domain.com')
->setSubject('メッセージの題')
->send();
```
ビューファイルの中で利用できる追加のビューパラメータを `compose()` メソッドに渡すことができます。
```php
Yii::$app->mailer->compose('greetings', [
'user' => Yii::$app->user->identity,
'advertisement' => $adContent,
]);
```
HTML とプレーンテキストのメッセージコンテントに違うビューを指定することが出来ます。
```php
Yii::$app->mailer->compose([
'html' => 'contact-html',
'text' => 'contact-text',
]);
```
ビュー名をスカラーの文字列として渡した場合は、そのレンダリング結果は HTML ボディとして使われ、プレーンテキストのボディは HTML のボディから全ての HTML 要素を削除することによって作成されます。
ビューのレンダリング結果はレイアウトで包むことが出来ます。
レイアウトは、[[yii\mail\BaseMailer::htmlLayout]] と [[yii\mail\BaseMailer::textLayout]] を使ってセットアップすることが可能です。
レイアウトは、通常のウェブアプリケーションのレイアウトと同じように働きます。
レイアウトは、メールの CSS スタイルや、その他の共有されるコンテントをセットアップするために使うことが出来ます。
```php
<?php
use yii\helpers\Html;
/* @var $this \yii\web\View ビューコンポーネントのインスタンス */
/* @var $message \yii\mail\MessageInterface 作成されるメッセージ */
/* @var $content string メインビューのレンダリング結果 */
?>
<?php $this->beginPage() ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=<?= Yii::$app->charset ?>" />
<style type="text/css">
.heading {...}
.list {...}
.footer {...}
</style>
<?php $this->head() ?>
</head>
<body>
<?php $this->beginBody() ?>
<?= $content ?>
<div class="footer">よろしくお願いします。<?= Yii::$app->name ?> チーム</div>
<?php $this->endBody() ?>
</body>
</html>
<?php $this->endPage() ?>
```
ファイルの添付
--------------
`attach()` メソッド、`attachContent()` メソッドを使って、メッセージにファイルを添付することが出来ます。
```php
$message = Yii::$app->mailer->compose();
// ローカルファイルシステムからファイルを添付する
$message->attach('/path/to/source/file.pdf');
// 添付ファイルをその場で生成する
$message->attachContent('添付される内容', ['fileName' => 'attach.txt', 'contentType' => 'text/plain']);
```
画像の埋め込み
--------------
`embed()` メソッドを使って、メッセージのコンテントに画像を埋め込むことが出来ます。
このメソッドは添付されるファイルのコンテント ID を返しますので、それを 'img' タグで使わなければなりません。
このメソッドはビューファイルによってメッセージのコンテントを作成するときに簡単に使うことが出来ます。
```php
Yii::$app->mailer->compose('embed-email', ['imageFileName' => '/path/to/image.jpg'])
// ...
->send();
```
そして、ビューファイルの中では、次のコードを使うことが出来ます。
```php
<img src="<?= $message->embed($imageFileName); ?>">
```
テストとデバッグ
----------------
開発者は、実際にどのようなメールがアプリケーションによって送信されたか、その内容はどのようなものであったか、等をチェックしなければならないことが多くあります。
Yii は、そのようなチェックが出来ることを `yii\mail\BaseMailer::useFileTransport` によって保証しています。
このオプションを有効にすると、メールのメッセージデータが、通常のように送信される代りに、ローカルファイルに強制的に保存されます。
ファイルは、`yii\mail\BaseMailer::fileTransportPath`、デフォルトでは '@runtime/mail' の下に保存されます。
> Note|注意: メッセージをファイルに保存するか、実際の受信者に送信するか、どちらかを選ぶことが出来ますが、両方を同時に実行することは出来ません。
メールメッセージのファイルは通常のテキストエディタで開くことが出来ますので、実際のメッセージヘッダやコンテントなどを閲覧することが出来ます。
このメカニズムは、アプリケーションのデバッグやユニットテストを実行する際に、真価を発揮するでしょう。
> Note|注意: メールメッセーのファイルの内容は `\yii\mail\MessageInterface::toString()` によって作成されますので、あなたのアプリケーションで使用している実際のメールエクステンションに依存したものになります。
あなた自身のメールソリューションを作成する
------------------------------------------
あなた自身のカスタムメールソリューションを作成するためには、二つのクラスを作成する必要があります。
すなわち、一つは 'Mailer' であり、もう一つは 'Message' です。
`yii\mail\BaseMailer` と `yii\mail\BaseMessage` をあなたのソリューションの基底クラスとして使うことが出来ます。
これらのクラスが、このガイドで説明された基本的なロジックを既に持っています。
しかし、それを使用することは強制されていません。
`yii\mail\MailerInterface` と `yii\mail\MessageInterface` のインタフェイスを実装すれば十分です。
そして、あなたのソリューションをビルドするために、全ての抽象メソッドを実装しなければなりません。
docs/guide-ru/start-hello.md
......@@ -76,7 +76,7 @@ use yii\helpers\Html;
```
Представление `say` должно быть сохранено в файле `views/site/say.php`. Когда метод [[yii\web\Controller::render()|render()]]
вызывается в действии, он будет искать PHP файл с именем вида `views/ControllerID/ActionID/ViewName.php`.
вызывается в действии, он будет искать PHP файл с именем вида `views/ControllerID/ViewName.php`.
Стоит отметить, что в коде выше параметр `message` [[yii\helpers\Html::encode()|экранируется для HTML]] перед выводом.
Это обязательно так как параметр приходит от пользователя, который может попытаться провести
......
docs/guide/db-active-record.md
......@@ -99,7 +99,7 @@ $customer->save();
> Note: Obviously, because column names become attribute names of the active record class directly, you
> get attribute names with underscores if you have that kind of naming schema in your database. For example
> a column `user_name` will be accessed as `$user->user_name` on the active record object. If you are concerned about code style
> you should adopt your database naming schema to use camelCase too. However, camelCase if not a requirement, Yii can work
> you should adopt your database naming schema to use camelCase too. However, camelCase is not a requirement, Yii can work
> well with any other naming style.
......
docs/guide/test-fixtures.md
......@@ -227,7 +227,6 @@ Summary
> Note: This section is under development.
Fixtures are important part of testing. Their main purpose is to set up the environment in a fixed/known state
In the above, we have described how to define and use fixtures. Below we summarize the typical workflow
of running unit tests related with DB:
......
docs/guide/tutorial-i18n.md
......@@ -16,13 +16,13 @@ Locale and Language
There are two languages defined in the Yii application: [[yii\base\Application::$sourceLanguage|source language]] and
[[yii\base\Application::$language|target language]].
Source language is the language original application messages are written in directly in the code such as:
The source language is the language in which the original application messages are written directly in the code such as:
```php
echo \Yii::t('app', 'I am a message!');
```
The target language is the language that should be used to display the current page i.e. the language that original messages need
The target language is the language that should be used to display the current page, i.e. the language that original messages need
to be translated to. It is defined in the application configuration like the following:
```php
......@@ -39,7 +39,7 @@ return [
> recommended to keep this value. The reason is that it's easier to find people translating from
> English to any language than from non-English to non-English.
You may set the application language at runtime to set it to a language the user has chosen.
You may set the application language at runtime to the language that the user has chosen.
This has to be done at a point before any output is generated so that it affects all the output correctly.
Therefor just change the application property to the desired value:
......@@ -57,7 +57,7 @@ The format for the language/locale is `ll-CC` where `ll` is a two- or three-lett
Message translation
-------------------
Message translation is used to translate messages that are output by an application to different languages
Message translation is used to translate the messages that are output by an application to different languages
so that users from different countries can use the application in their native language.
The message translation feature in Yii works simply as finding a
......@@ -98,14 +98,14 @@ In the above `app*` is a pattern that specifies which categories are handled by
handling everything that begins with `app`. Message files are located in `@app/messages`, the `messages` directory
in your application directory. The [[yii\i18n\PhpMessageSource::fileMap|fileMap]] array
defines which file is to be used for which category.
Instead of configuring `fileMap` you can rely on convention which is to use the category name as the file name
Instead of configuring `fileMap` you can rely on the convention which is to use the category name as the file name
(e.g. category `app/error` will result in the file name `app/error.php` under the [[yii\i18n\PhpMessageSource::basePath|basePath]].
When translating the message for `\Yii::t('app', 'This is a string to translate!')` and an application language `ru-RU`, Yii
When translating the message for `\Yii::t('app', 'This is a string to translate!')` with the application language being `ru-RU`, Yii
will first look for a file `@app/messages/ru-RU/app.php` to retrieve the list of available translations.
If there is file `ru-RU` it will try `ru` as well before failing.
If there is no such file under `ru-RU`, it will try `ru` as well before failing.
Beside storing messages in PHP files (using [[yii\i18n\PhpMessageSource|PhpMessageSource]]) Yii provides two other
Beside storing the messages in PHP files (using [[yii\i18n\PhpMessageSource|PhpMessageSource]]), Yii provides two other
classes:
- [[yii\i18n\GettextMessageSource]] that uses GNU Gettext MO or PO files.
......@@ -133,15 +133,15 @@ $sum = 42;
echo \Yii::t('app', 'Balance: {0}', $sum);
```
> **Tip**: Try keep message strings meaningful and avoid using too many positional parameters. Remember that
> translator has source string only so it should be obvious about what will replace each placeholder.
> **Tip**: Try to keep the message strings meaningful and avoid using too many positional parameters. Remember that
> the translator has only the source string, so it should be obvious about what will replace each placeholder.
### Advanced placeholder formatting
In order to use advanced features you need to install and enable the [intl PHP extension](http://www.php.net/manual/en/intro.intl.php).
After installing and enabling it you will be able to use extended syntax for placeholders. Either short form
`{placeholderName, argumentType}` that means default setting or full form `{placeholderName, argumentType, argumentStyle}`
that allows you to specify formatting style.
In order to use the advanced features you need to install and enable the [intl PHP extension](http://www.php.net/manual/en/intro.intl.php).
After installing and enabling it you will be able to use the extended syntax for placeholders: either the short form
`{placeholderName, argumentType}` that uses the default style, or the full form `{placeholderName, argumentType, argumentStyle}`
that allows you to specify the formatting style.
A complete reference is available at the [ICU website](http://icu-project.org/apiref/icu4c/classMessageFormat.html) but we will show some examples in the following.
......@@ -234,7 +234,7 @@ Will produce "You are here for 47 sec. already!".
#### Plurals
Different languages have different ways to inflect plurals. Yii provides a convenient way for translating messages in
different plural forms that works well even for very complex rules. Instead of dealing with the inflection rules directly
different plural forms that works well even for very complex rules. Instead of dealing with the inflection rules directly,
it is sufficient to provide the translation of inflected words in certain situations only.
```php
......@@ -247,7 +247,7 @@ Will give us
- "There is one cat!" for `$n = 1`,
- and "There are 42 cats!" for `$n = 42`.
In the plural rule arguments above `=0` means exactly zero, `=1` stands for exactly one, and `other` is for any other number.
In the plural rule arguments above, `=0` means exactly zero, `=1` stands for exactly one, and `other` is for any other number.
`#` is replaced with the value of `n`. It's not that simple for languages other than English. Here's an example
for Russian:
......@@ -258,11 +258,11 @@ for Russian:
In the above it's worth mentioning that `=1` matches exactly `n = 1` while `one` matches `21` or `101`.
Note, that you can not use the Russian example in `Yii::t()` directly if your
[[yii\base\Application::$sourceLanguage|source language]] isn't set to `ru_RU`. This however is not recommended, instead such
strings should go into message files or message database (in case DB source is used). Yii uses plural rules of the
translated language strings and is falling back to plural rules of source language if translation isn't available.
[[yii\base\Application::$sourceLanguage|source language]] isn't set to `ru-RU`. This however is not recommended, instead such
strings should go into message files or message database (in case DB source is used). Yii uses the plural rules of the
translated language strings and is falling back to the plural rules of the source language if the translation isn't available.
To learn which inflection forms you should specify for your language you can referrer to the
To learn which inflection forms you should specify for your language, you can refeer to the
[rules reference at unicode.org](http://unicode.org/repos/cldr-tmp/trunk/diff/supplemental/language_plural_rules.html).
#### Selections
......@@ -271,16 +271,16 @@ You can select phrases based on keywords. The pattern in this case specifies how
provides a default phrase.
```php
echo \Yii::t('app', '{name} is {gender} and {gender, select, female{she} male{he} other{it}} loves Yii!', [
echo \Yii::t('app', '{name} is a {gender} and {gender, select, female{she} male{he} other{it}} loves Yii!', [
'name' => 'Snoopy',
'gender' => 'dog',
]);
```
Will produce "Snoopy is dog and it loves Yii!".
Will produce "Snoopy is a dog and it loves Yii!".
In the expression `female` and `male` are possible values. `other` handles values that do not match. Strings inside
brackets are sub-expressions so could be just a string or a string with more placeholders.
In the expression above, `female` and `male` are possible values, while `other` handles values that do not match. A string inside
the brackets is a sub-expression, so it could be a plain string or a string with nested placeholders in it.
### Specifying default translation
......@@ -306,11 +306,11 @@ Messages for the category will be loaded from a file under the default translati
echo Yii::t('not_specified_category', 'message from unspecified category');
```
Message will be loaded from `@app/messages/<LanguageCode>/not_specified_category.php`.
The message will be loaded from `@app/messages/<LanguageCode>/not_specified_category.php`.
### Translating module messages
If you want to translate messages for a module and avoid using a single translation file for all messages, you can do it like the following:
If you want to translate the messages for a module and avoid using a single translation file for all the messages, you can do it like the following:
```php
<?php
......@@ -351,8 +351,9 @@ class Module extends \yii\base\Module
}
```
In the example above we are using wildcard for matching and then filtering each category per needed file. Instead of using `fileMap` you can simply
use convention of category mapping to the same named file and use `Module::t('validation', 'your custom validation message')` or `Module::t('form', 'some form label')` directly.
In the example above we are using wildcard for matching and then filtering each category per needed file. Instead of using `fileMap`, you can simply
use the convention of the category mapping to the same named file.
Now you can use `Module::t('validation', 'your custom validation message')` or `Module::t('form', 'some form label')` directly.
### Translating widgets messages
......@@ -401,16 +402,17 @@ class Menu extends Widget
}
```
Instead of using `fileMap` you can simply use convention of category mapping to the same named file and use `Menu::t('messages', 'new messages {messages}', ['{messages}' => 10])` directly.
Instead of using `fileMap` you can simply use the convention of the category mapping to the same named file.
Now you can use `Menu::t('messages', 'new messages {messages}', ['{messages}' => 10])` directly.
> **Note**: For widgets you also can use i18n views, same rules as for controllers are applied to them too.
> **Note**: For widgets you also can use i18n views, with the same rules as for controllers being applied to them too.
### Translating framework messages
Yii comes with default translation messages for validation errors and some other strings. These messages are all
in the category `yii`. Sometimes you want to correct default framework message translation for your application.
In order to do so configure the `i18n` [application component](structure-application-components.md) like the following:
Yii comes with the default translation messages for validation errors and some other strings. These messages are all
in the category `yii`. Sometimes you want to correct the default framework message translation for your application.
In order to do so, configure the `i18n` [application component](structure-application-components.md) like the following:
```php
'i18n' => [
......@@ -428,13 +430,13 @@ Now you can place your adjusted translations to `@app/messages/<language>/yii.ph
### Handling missing translations
If the translation is missing at the source, Yii displays the requested message content. Such behavior is very convenient
Even if the translation is missing from the source, Yii will display the requested message content. Such behavior is very convenient
in case your raw message is a valid verbose text. However, sometimes it is not enough.
You may need to perform some custom processing of the situation, when requested translation is missing at the source.
You may need to perform some custom processing of the situation, when the requested translation is missing from the source.
This can be achieved using the [[yii\i18n\MessageSource::EVENT_MISSING_TRANSLATION|missingTranslation]]-event of [[yii\i18n\MessageSource]].
For example to mark all missing translations with something notable, so they can be easily found at the page we
first we need to setup event handler. This can be done in the application configuration:
For example, let us mark all the missing translations with something notable so that they can be easily found at the page.
First we need to setup an event handler. This can be done in the application configuration:
```php
'components' => [
......@@ -473,8 +475,8 @@ class TranslationEventHandler
If [[yii\i18n\MissingTranslationEvent::translatedMessage]] is set by the event handler it will be displayed as the translation result.
> Attention: each message source handles its missing translations separately. If you are using several message sources
> and wish them treat missing translation in the same way, you should assign corresponding event handler to each of them.
> Note: each message source handles its missing translations separately. If you are using several message sources
> and wish them to treat the missing translations in the same way, you should assign the corresponding event handler to each of them.
Views
......@@ -482,8 +484,8 @@ Views
Instead of translating messages as described in the last section,
you can also use `i18n` in your views to provide support for different languages. For example, if you have a view `views/site/index.php` and
you want to create a special version for russian language of it, you create a `ru-RU` folder under the view path of the current controller/widget and
put the file for russian language as follows `views/site/ru-RU/index.php`. Yii will then load the file for the current language if it exists
you want to create a special version for the Russian language, you create a `ru-RU` folder under the view path of the current controller/widget and
put the file for the Russian language as `views/site/ru-RU/index.php`. Yii will then load the file for the current language if it exists
and fall back to the original view file if none was found.
> **Note**: If language is specified as `en-US` and there are no corresponding views, Yii will try views under `en`
......@@ -501,8 +503,8 @@ Setting up your PHP environment <a name="setup-environment"></a>
Yii uses the [PHP intl extension](http://php.net/manual/en/book.intl.php) to provide most of its internationalization features
such as the number and date formatting of the [[yii\i18n\Formatter]] class and the message formatting using [[yii\i18n\MessageFormatter]].
Both classes provides a fallback implementation that provides basic functionality in case intl is not installed.
This fallback implementation however only works well for sites in english language and even there can not provide the
Both classes provides a fallback implementation that provides basic functionality in case `intl` is not installed.
This fallback implementation however only works well for sites in English language and even there can not provide the
rich set of features that is available with the PHP intl extension, so its installation is highly recommended.
The [PHP intl extension](http://php.net/manual/en/book.intl.php) is based on the [ICU library](http://site.icu-project.org/) which
......
docs/guide/tutorial-mailing.md
......@@ -97,14 +97,14 @@ use yii\helpers\Url;
/* @var $message \yii\mail\BaseMessage instance of newly created mail message */
?>
<h2>This message allows you to visit out site home page by one click</h2>
<h2>This message allows you to visit our site home page by one click</h2>
<?= Html::a('Go to home page', Url::home('http')) ?>
```
In order to compose message content via view file simply pass view name to the `compose()` method:
```php
Yii::$app->mailer->compose('home-link') // message body becomes a view rendering result here
Yii::$app->mailer->compose('home-link') // a view rendering result becomes the message body here
->setFrom('from@domain.com')
->setTo('to@domain.com')
->setSubject('Message subject')
......@@ -183,8 +183,8 @@ $message->attachContent('Attachment content', ['fileName' => 'attach.txt', 'cont
```
Embed images
------------
Embedding images
----------------
You can embed images into the message content using `embed()` method. This method returns the attachment id,
which should be then used at 'img' tag.
......@@ -196,7 +196,7 @@ Yii::$app->mailer->compose('embed-email', ['imageFileName' => '/path/to/image.jp
->send();
```
Then inside view file you can use following code:
Then inside the view file you can use the following code:
```php
<img src="<?= $message->embed($imageFileName); ?>">
......@@ -206,17 +206,17 @@ Then inside view file you can use following code:
Testing and debugging
---------------------
Developer often a to check, what actual emails are sent by application, what was their content and so on.
A developer often has to check, what actual emails are sent by the application, what was their content and so on.
Such ability is granted by Yii via `yii\mail\BaseMailer::useFileTransport`. If enabled, this option enforces
saving mail message data into the local files instead of regular sending. These files will be saved under
`yii\mail\BaseMailer::fileTransportPath`, which is '@runtime/mail' by default.
> Note: you can either save messages to the file or send them to actual recipients, but can not do both simultaneously.
> Note: you can either save the messages to the files or send them to the actual recipients, but can not do both simultaneously.
Mail message file can be opened by regular text file editor, so you can browse actual message headers, content and so on.
This mechanism amy prove itself, while debugging application or running unit test.
A mail message file can be opened by a regular text file editor, so you can browse the actual message headers, content and so on.
This mechanism may prove itself, while debugging application or running unit test.
> Note: mail message file content is composed via `\yii\mail\MessageInterface::toString()`, so it depends on actual
> Note: the mail message file content is composed via `\yii\mail\MessageInterface::toString()`, so it depends on the actual
mail extension you are using in your application.
......@@ -225,7 +225,7 @@ Creating your own mail solution
In order to create your own custom mail solution, you need to create 2 classes: one for the 'Mailer' and
another one for the 'Message'.
You can use `yii\mail\BaseMailer` and `yii\mail\BaseMessage` as a base classes for your solution. These classes
already contains basic logic, which is described in this guide. However, their usage is not mandatory, it is enough
You can use `yii\mail\BaseMailer` and `yii\mail\BaseMessage` as the base classes for your solution. These classes
already contain the basic logic, which is described in this guide. However, their usage is not mandatory, it is enough
to implement `yii\mail\MailerInterface` and `yii\mail\MessageInterface` interfaces.
Then you need to implement all abstract methods to build you solution.
Then you need to implement all the abstract methods to build your solution.
framework/db/ActiveQuery.php
......@@ -407,7 +407,7 @@ class ActiveQuery extends Query implements ActiveQueryInterface
* Inner joins with the specified relations.
* This is a shortcut method to [[joinWith()]] with the join type set as "INNER JOIN".
* Please refer to [[joinWith()]] for detailed usage of this method.
* @param array $with the relations to be joined with
* @param string|array $with the relations to be joined with
* @param boolean|array $eagerLoading whether to eager loading the relations
* @return static the query object itself
* @see joinWith()
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment