Merge pull request #6541 from softark/docs-guide-ja-inpt-file-upload

docs/guide-ja/README.md

@@ -89,7 +89,7 @@ All Rights Reserved.
 
 * [フォームを作成する](input-forms.md)
 * [入力を検証する](input-validation.md)
-* **翻訳中** [ファイルをアップロードする](input-file-upload.md)
+* [ファイルをアップロードする](input-file-upload.md)
 * **TBD** [複数モデルのためのデータ取得](input-multiple-models.md)
 
 
@@ -112,7 +112,7 @@ All Rights Reserved.
 * **翻訳未着手** [権限](security-authorization.md)
 * **翻訳未着手** [パスワードを扱う](security-passwords.md)
 * **TBD** [Auth クライアント](security-auth-clients.md)
-* **翻訳未着手** [最善の慣行](security-best-practices.md)
+* **翻訳未着手** [ベストプラクティス](security-best-practices.md)
 
 
 キャッシュ
@@ -184,8 +184,8 @@ RESTful ウェブサービス
 * Menu: **TBD** link to demo page
 * LinkPager: **TBD** link to demo page
 * LinkSorter: **TBD** link to demo page
-* [Bootstrap ウィジェット](widget-bootstrap.md)
-* [Jquery UI ウィジェット](widget-jui.md)
+* **翻訳未着手** [Bootstrap ウィジェット](widget-bootstrap.md)
+* **翻訳未着手** [Jquery UI ウィジェット](widget-jui.md)
 
 
 ヘルパ

docs/guide-ja/db-active-record.md

@@ -29,7 +29,7 @@ $db->createCommand('INSERT INTO customer (name) VALUES (:name)', [
 * MySQL 4.1 以降: [[yii\db\ActiveRecord]] による。
 * PostgreSQL 7.3 以降: [[yii\db\ActiveRecord]] による。
 * SQLite 2 および 3: [[yii\db\ActiveRecord]] による。
-* Microsoft SQL Server 2010 以降: [[yii\db\ActiveRecord]] による。
+* Microsoft SQL Server 2008 以降: [[yii\db\ActiveRecord]] による。
 * Oracle: [[yii\db\ActiveRecord]] による。
 * CUBRID 9.3 以降: [[yii\db\ActiveRecord]] による。(cubrid PDO 拡張の [バグ](http://jira.cubrid.org/browse/APIS-658)
   のために、値を引用符で囲む機能が動作しません。そのため、サーバだけでなくクライアントも CUBRID 9.3 が必要になります)
@@ -166,7 +166,7 @@ $customers = Customer::findBySql($sql)->all();
 ```
 
 > Tip|ヒント: 上記のコードでは、`Customer::STATUS_ACTIVE` は `Customer` で定義されている定数です。
-  コードの中で、ハードコードされた文字列や数字ではなく、意味が分かる名前の定数を使用することは良い慣行です。
+  コードの中で、ハードコードされた文字列や数字ではなく、意味が分かる名前の定数を使用することは良いプラクティスです。
 
 
 プライマリキーの値または一連のカラムの値に合致するアクティブレコードのインスタンスを返すためのショートカットメソッドが二つ提供されています。
@@ -414,7 +414,7 @@ class Order extends \yii\db\ActiveRecord
  - `$class`: 関連するモデルのクラス名。これは完全修飾のクラス名でなければなりません。
  - `$link`: 二つのテーブルに属するカラム間の関係。これは配列として与えられなければなりません。
    配列のキーは、`$class` と関連付けられるテーブルにあるカラムの名前であり、配列の値はリレーションを宣言しているクラスのテーブルにあるカラムの名前です。
-   リレーションをテーブルの外部キーに基づいて定義するのが望ましい慣行です。
+   リレーションをテーブルの外部キーに基づいて定義するのが望ましいプラクティスです。
 
 リレーションを宣言した後は、リレーショナルデータを取得することは、対応するゲッターメソッドで定義されているコンポーネントのプロパティを取得するのと同じように、とても簡単なことになります。
 
@@ -467,13 +467,13 @@ $orders = $customer->getBigOrders(200)->all();
 例えば、`$customer->getOrders()` は `ActiveQuery` のインスタンスを返し、`$customer->orders` は `Order` オブジェクトの配列 (またはクエリ結果が無い場合は空の配列) を返します。
 
 
-連結テーブルを使うリレーション
+中間テーブルを使うリレーション
 ------------------------------
 
-場合によっては、二つのテーブルが [連結テーブル][] と呼ばれる中間的なテーブルによって関連付けられていることがあります。
+場合によっては、二つのテーブルが [中間テーブル][] と呼ばれる中間的なテーブルによって関連付けられていることがあります。
 そのようなリレーションを宣言するために、[[yii\db\ActiveQuery::via()|via()]] または [[yii\db\ActiveQuery::viaTable()|viaTable()]] メソッドを呼んで、[[yii\db\ActiveQuery]] オブジェクトをカスタマイズすることが出来ます。
 
-例えば、テーブル `order` とテーブル `item` が連結テーブル `order_item` によって関連付けられている場合、`Order` クラスにおいて `items` リレーションを次のように宣言することが出来ます。
+例えば、テーブル `order` とテーブル `item` が中間テーブル `order_item` によって関連付けられている場合、`Order` クラスにおいて `items` リレーションを次のように宣言することが出来ます。
 
 ```php
 class Order extends \yii\db\ActiveRecord
@@ -505,7 +505,7 @@ class Order extends \yii\db\ActiveRecord
 }
 ```
 
-[連結テーブル]: https://en.wikipedia.org/wiki/Junction_table "Junction table on Wikipedia"
+[中間テーブル]: https://en.wikipedia.org/wiki/Junction_table "Junction table on Wikipedia"
 
 
 レイジーローディングとイーガーローディング
@@ -560,7 +560,7 @@ foreach ($customers as $customer) {
 ご覧のように、同じ仕事をするのに必要な SQL クエリがたった二つになります。
 
 > Info|情報: 一般化して言うと、`N` 個のリレーションのうち `M` 個のリレーションが `via()` または `viaTable()` によって定義されている場合、この `N` 個のリレーションをイーガーロードしようとすると、合計で `1+M+N` 個の SQL クエリが実行されます。
-> 主たるテーブルの行を返すために一つ、`via()` または `viaTable()` の呼び出しに対応する `M` 個の連結テーブルのそれぞれに対して一つずつ、そして、`N` 個の関連テーブルのそれぞれに対して一つずつ、という訳です。
+> 主たるテーブルの行を返すために一つ、`via()` または `viaTable()` の呼び出しに対応する `M` 個の中間テーブルのそれぞれに対して一つずつ、そして、`N` 個の関連テーブルのそれぞれに対して一つずつ、という訳です。
 
 > Note|注意: イーガーローディングで `select()` をカスタマイズしようとする場合は、関連モデルにリンクするカラムを必ず含めてください。
 > そうしないと、関連モデルは読み出されません。例えば、

docs/guide-ja/db-dao.md

@@ -18,7 +18,7 @@ Yii はデフォルトで下記の DBMS をサポートしています。
 - [CUBRID](http://www.cubrid.org/): バージョン 9.3 以上。(cubrid PDO 拡張の [バグ](http://jira.cubrid.org/browse/APIS-658)
   のために、値を引用符で囲む機能が動作しません。そのため、サーバだけでなくクライアントも CUBRID 9.3 が必要になります)
 - [Oracle](http://www.oracle.com/us/products/database/overview/index.html)
-- [MSSQL](https://www.microsoft.com/en-us/sqlserver/default.aspx): バージョン 2005 以上。
+- [MSSQL](https://www.microsoft.com/en-us/sqlserver/default.aspx): バージョン 2008 以上。
 
 
 構成

docs/guide-ja/input-file-upload.md

+ファイルをアップロードする
+==========================
+
+Yii におけるファイルのアップロードは、フォームモデル、その検証規則、そして、いくらかのコントローラコードによって行われます。
+アップロードを適切に処理するために何が必要とされるのか、見ていきましよう。
+
+
+一つのファイルをアップロードする
+--------------------------------
+
+まず最初に、ファイルのアップロードを処理するモデルを作成する必要があります。
+次の内容を持つ `models/UploadForm.php` を作って作成してください。
+
+```php
+namespace app\models;
+
+use yii\base\Model;
+use yii\web\UploadedFile;
+
+/**
+ * UploadForm がアップロードのフォームの背後にあるモデルである。
+ */
+class UploadForm extends Model
+{
+    /**
+     * @var UploadedFile file 属性
+     */
+    public $file;
+
+    /**
+     * @return array 検証規則
+     */
+    public function rules()
+    {
+        return [
+            [['file'], 'file'],
+        ];
+    }
+}
+```
+
+上記のコードにおいて作成した `UploadForm` というモデルは、HTML フォームで `<input type="file">` となる `$file` という属性を持ちます。
+この属性は [[yii\validators\FileValidator|FileValidator]] を使用する `file` という検証規則を持ちます。
+
+### フォームのビュー
+
+次に、フォームを表示するビューを作成します。
+
+```php
+<?php
+use yii\widgets\ActiveForm;
+?>
+
+<?php $form = ActiveForm::begin(['options' => ['enctype' => 'multipart/form-data']]) ?>
+
+<?= $form->field($model, 'file')->fileInput() ?>
+
+<button>送信</button>
+
+<?php ActiveForm::end() ?>
+```
+
+ファイルのアップロードを可能にする `'enctype' => 'multipart/form-data'` は不可欠です。
+`fileInput()` がフォームの入力フィールドを表します。
+
+### コントローラ
+
+そして、フォームとモデルを結び付けるコントローラを作成します。
+
+```php
+namespace app\controllers;
+
+use Yii;
+use yii\web\Controller;
+use app\models\UploadForm;
+use yii\web\UploadedFile;
+
+class SiteController extends Controller
+{
+    public function actionUpload()
+    {
+        $model = new UploadForm();
+
+        if (Yii::$app->request->isPost) {
+            $model->file = UploadedFile::getInstance($model, 'file');
+
+            if ($model->file && $model->validate()) {                
+                $model->file->saveAs('uploads/' . $model->file->baseName . '.' . $model->file->extension);
+            }
+        }
+
+        return $this->render('upload', ['model' => $model]);
+    }
+}
+```
+
+`model->load(...)` の代りに `UploadedFile::getInstance(...)` を使っています。
+[[\yii\web\UploadedFile|UploadedFile]] はモデルの検証を実行せず、アップロードされたファイルに関する情報を提供するだけです。
+そのため、`$model->validate()` を手作業で実行して、[[yii\validators\FileValidator|FileValidator]] を起動する必要があります。
+[[yii\validators\FileValidator|FileValidator]] は、下記のコアコードが示しているように、属性がファイルであることを要求します。
+
+```php
+if (!$file instanceof UploadedFile || $file->error == UPLOAD_ERR_NO_FILE) {
+    return [$this->uploadRequired, []];  // "ファイルをアップロードしてください。" というエラーメッセージ
+}
+```
+
+検証が成功したら、ファイルを保存します。
+
+```php
+$model->file->saveAs('uploads/' . $model->file->baseName . '.' . $model->file->extension);
+```
+
+「ベーシック」アプリケーションテンプレートを使っている場合は、`uploads` フォルダを `web` の下に作成しなければなりません。
+
+以上です。ページをロードして、アップロードを試して見てください。ファイルは `basic/web/uploads` にアップロードされます。
+
+検証
+----
+
+たいていの場合、検証規則を調整して、特定のファイルだけを受け取るようにしたり、アップロードを必須としたりする必要があります。
+下記で、よく使われる規則の構成を見てみましよう。
+
+### Required
+
+ファイルのアップロードを必須とする必要がある場合は、次のように `skipOnEmpty` を `false` に設定します。
+
+```php
+public function rules()
+{
+    return [
+        [['file'], 'file', 'skipOnEmpty' => false],
+    ];
+}
+```
+
+### MIME タイプ
+
+アップロードされるファイルのタイプを検証することは賢明なことです。
+`FileValidator` はこの目的のための `extensions` プロパティを持っています。
+
+```php
+public function rules()
+{
+    return [
+        [['file'], 'file', 'extensions' => 'gif, jpg',],
+    ];
+}
+```
+
+ただし、ファイル拡張子が検証されるだけで、実際のファイルの中身は検証されないことを憶えておいてください。
+ファイルの中身も検証するためには、`FileValidator` の `mimeType` プロパティを使います。
+
+```php
+public function rules()
+{
+    return [
+        [['file'], 'file', 'extensions' => 'jpg, png', 'mimeTypes' => 'image/jpeg, image/png',],
+    ];
+}
+```
+
+[一般的なメディアタイプの一覧表](http://en.wikipedia.org/wiki/Internet_media_type#List_of_common_media_types)
+
+### 画像のプロパティ
+
+画像をアップロードするときは、[[yii\validators\ImageValidator|ImageValidator]] が重宝するでしょう。
+このバリデータは、属性が有効な画像を受け取ったか否かを検証します。
+その画像は、[Imagine エクステンション](https://github.com/yiisoft/yii2/tree/master/extensions/imagine) によって、保存するか、または、処理することが出来ます。
+
+複数のファイルをアップロードする
+--------------------------------
+
+複数のファイルを一度にアップロードする必要がある場合は、少し修正が必要になります。
+ 
+モデル:
+
+```php
+class UploadForm extends Model
+{
+    /**
+     * @var UploadedFile|Null ファイル属性
+     */
+    public $file;
+
+    /**
+     * @return array 検証規則
+     */
+    public function rules()
+    {
+        return [
+            [['file'], 'file', 'maxFiles' => 10], // <--- ここ !
+        ];
+    }
+}
+```
+
+ビュー:
+
+```php
+<?php
+use yii\widgets\ActiveForm;
+
+$form = ActiveForm::begin(['options' => ['enctype' => 'multipart/form-data']]);
+?>
+
+<?= $form->field($model, 'file[]')->fileInput(['multiple' => true]) ?>
+
+    <button>送信</button>
+
+<?php ActiveForm::end(); ?>
+```
+
+違いがあるのは、次の行です。
+
+```php
+<?= $form->field($model, 'file[]')->fileInput(['multiple' => true]) ?>
+```
+
+コントローラ:
+
+```php
+namespace app\controllers;
+
+use Yii;
+use yii\web\Controller;
+use app\models\UploadForm;
+use yii\web\UploadedFile;
+
+class SiteController extends Controller
+{
+    public function actionUpload()
+    {
+        $model = new UploadForm();
+
+        if (Yii::$app->request->isPost) {
+            $model->file = UploadedFile::getInstances($model, 'file');
+            
+            if ($model->file && $model->validate()) {
+                foreach ($model->file as $file) {
+                    $file->saveAs('uploads/' . $file->baseName . '.' . $file->extension);
+                }
+            }
+        }
+
+        return $this->render('upload', ['model' => $model]);
+    }
+}
+```
+
+単一のファイルのアップロードとは、二つの点で異なります。
+最初の違いは、`UploadedFile::getInstance($model, 'file');` の代りに `UploadedFile::getInstances($model, 'file');` が使用されることです。
+前者が一つのインスタンスを返すだけなのに対して、後者はアップロードされた **全ての** ファイルのインスタンスを返します。
+第二の違いは、`foreach` によって、全てのファイルをそれぞれ保存している点です。

docs/guide-ja/input-validation.md

@@ -294,7 +294,7 @@ Yii のリリースに含まれている [コアバリデータ](tutorial-core-v
 function ($attribute, $params)
 ```
 
-属性が健勝に失敗した場合は、メソッド/関数 は [[yii\base\Model::addError()]] を呼んでエラーメッセージをモデルに保存し、後で読み出してエンドユーザに示ことが出来るようにしなければなりません。
+属性が検証に失敗した場合は、メソッド/関数 は [[yii\base\Model::addError()]] を呼んでエラーメッセージをモデルに保存し、後で読み出してエンドユーザに示ことが出来るようにしなければなりません。
 
 下記にいくつかの例を示します。
 

docs/guide-ja/intro-yii.md

@@ -29,8 +29,8 @@ Yii を他のフレームワークと比べるとどうか?
 - 高性能であることは常に Yii の主たる目標です。
 
 Yii はワンマンショーではありません。Yii は [強力なコア開発チーム][] および Yii 開発に間断なく貢献してくれるプロフェッショナルの大きなコミュニティーに支えられたプロジェクトです。
-Yii 開発チームは最新のウェブ開発の潮流や、他のフレームワークやプロジェクトに見られる最善の慣行と機能から目を離しません。
-他のところで見出された関連性の高い最善の慣行と機能は、定期的にコアフレームワークに組み込まれ、シンプルかつエレガントなインターフェイスを通じて公開されます。
+Yii 開発チームは最新のウェブ開発の潮流や、他のフレームワークやプロジェクトに見られるベストプラクティスと機能から目を離しません。
+他のところで見出された関連性の高いベストプラクティスと機能は、定期的にコアフレームワークに組み込まれ、シンプルかつエレガントなインターフェイスを通じて公開されます。
 
 [強力なコア開発チーム]: http://www.yiiframework.com/about/
 

docs/guide-ja/runtime-routing.md

@@ -438,7 +438,7 @@ URL 規則のパターンには、ウェブサーバ名を含むことが出来
 > Tip|ヒント: URL が全てスラッシュで終るようにするためには、URL 接尾辞として `/` を設定することが出来ます。
 
 > Note|注意: URL 接尾辞を構成すると、リクエストされた URL が接尾辞を持たない場合は、認識できない URL であると見なされるようになります。
-  SEO の目的からも、これが推奨される慣行です。
+  SEO の目的からも、これが推奨されるプラクティスです。
 
 場合によっては、URL によって異なる接尾辞を使いたいことがあるでしょう。
 その目的は、個々の URL 規則の [[yii\web\UrlRule::suffix|suffix]] プロパティを構成することによって達成できます。

docs/guide-ja/structure-applications.md

@@ -305,7 +305,7 @@ if (YII_ENV_DEV) {
 #### [[yii\base\Application::params|params]] <a name="params"></a>
 
 このプロパティは、グローバルにアクセス可能なアプリケーションパラメータの配列を規定します。
-コードの中のいたる処でハードコードされた数値や文字列を使う代りに、それらをアプリケーションパラメータとして一ヶ所で定義し、必要な場所ではそのパラメータを使うというのが良い慣行です。
+コードの中のいたる処でハードコードされた数値や文字列を使う代りに、それらをアプリケーションパラメータとして一ヶ所で定義し、必要な場所ではそのパラメータを使うというのが良いプラクティスです。
 例えば、次のように、サムネール画像のサイズをパラメータとして定義することが出来ます。
 
 ```php

docs/guide-ja/structure-controllers.md

@@ -418,7 +418,7 @@ class SiteController extends Controller
 6. アプリケーションはアクションの結果を受け取り、それを [レスポンス](runtime-responses.md) に割り当てる。
 
 
-## 最善の慣行<a name="best-practices"></a>
+## ベストプラクティス<a name="best-practices"></a>
 
 良く設計されたアプリケーションでは、コントローラはたいてい非常に軽いものになり、それぞれのアクションは数行のコードしか含まないものになります。
 あなたのコントローラが少々複雑になっている場合、そのことは、通常、コントローラをリファクタして、コードの一部を他のクラスに移動すべきことを示すものです。

docs/guide-ja/structure-extensions.md

@@ -229,10 +229,10 @@ Composer が Bower または NPM のパッケージをインストールする
 例えば、上記の `autoload` の宣言は、`@yii/imagine` という名前のエイリアスに対応することになります。
 
 
-### 推奨される慣行 <a name="recommended-practices"></a>
+### 推奨されるプラクティス <a name="recommended-practices"></a>
 
 エクステンションは他の人々によって使われることを意図したものですから、多くの場合、追加の開発努力が必要になります。
-以下に、高品質のエクステンションを作成するときによく用いられ、また推奨される慣行のいくつかを紹介します。
+以下に、高品質のエクステンションを作成するときによく用いられ、また推奨されるプラクティスのいくつかを紹介します。
 
 
 #### 名前空間 <a name="namespaces"></a>
@@ -345,7 +345,7 @@ Yii はテストのサポートを提供しており、それよって、ユニ
 #### バージョン管理 <a name="versioning"></a>
 
 エクステンションのリリースごとにバージョン番号 (例えば `1.0.1`) を付けるべきです。
-どのようなバージョン番号を付けるべきかを決定するときは、[セマンティックバージョニング](http://semver.org) の慣行に従うことを推奨します。
+どのようなバージョン番号を付けるべきかを決定するときは、[セマンティックバージョニング](http://semver.org) のプラクティスに従うことを推奨します。
 
 
 #### リリース(公開) <a name="releasing"></a>

docs/guide-ja/structure-models.md

@@ -460,7 +460,7 @@ public function fields()
 > および `password_reset_token` を選んで除去しています。
 
 
-## 最善の慣行<a name="best-practices"></a>
+## ベストプラクティス<a name="best-practices"></a>
 
 モデルは、業務のデータ、規則、ロジックを表わす中心的なオブジェクトです。
 モデルは、さまざまな場所で再利用される必要がよくあります。

docs/guide-ja/structure-modules.md

@@ -236,7 +236,7 @@ class Module extends \yii\base\Module
 このリストには、直接の子と孫以下の両方のモジュールが含まれ、クラス名によってインデックスされています。
 
 
-## 最善の慣行 <a name="best-practices"></a>
+## ベストプラクティス <a name="best-practices"></a>
 
 モジュールは、それぞれ密接に関係する一連の機能を含む数個のグループに分割できるような、規模の大きなアプリケーションに最も適しています。
 そのような機能グループをそれぞれモジュールとして、特定の個人やチームによって開発することが出来ます。

docs/guide-ja/structure-views.md

@@ -680,7 +680,7 @@ http://localhost/index.php?r=site/page&view=about
 [[yii\web\ViewAction::viewPrefix]] を構成して、ビューを探すディレクトリを変更することが出来ます。
 
 
-## 最善の慣行 <a name="best-practices"></a>
+## ベストプラクティス <a name="best-practices"></a>
 
 ビューはエンドユーザが望む形式でモデルを表現することに対して責任を持ちます。一般的に、ビューは
 

docs/guide-ja/structure-widgets.md

@@ -172,7 +172,7 @@ public function run()
 [[yii\base\Widget::getViewPath()]] メソッドをオーバーライドして、ウィジェットのビューファイルを含むディレクトリをカスタマイズすることが出来ます。
 
 
-## 最善の慣行 <a name="best-practices"></a>
+## ベストプラクティス <a name="best-practices"></a>
 
 ウィジェットはビューのコードを再利用するためのオブジェクト指向の方法です。