Merge pull request #6699 from softark/docs-guide-ja-tool

docs/guide-ja/README.md

@@ -142,8 +142,8 @@ RESTful ウェブサービス
 開発ツール
 ----------
 
-* **翻訳未着手** [デバッグツールバーとデバッガ](tool-debugger.md)
-* **翻訳未着手** [Gii を使ってコードを生成する](tool-gii.md)
+* [デバッグツールバーとデバッガ](tool-debugger.md)
+* [Gii を使ってコードを生成する](tool-gii.md)
 * **TBD** [API ドキュメントを生成する](tool-api-doc.md)
 
 

docs/guide-ja/security-best-practices.md

@@ -148,16 +148,16 @@ TBD: how CSRF protection works
 そういう場合には、`web` 以外の全てに対してアクセスを拒否することを忘れないでください。
 それも出来ない場合は、アプリケーションを別の場所でホストすることを検討してください。
 
-実運用環境ではデバッグ情報とデバッグツールを無効にする
-------------------------------------------------------
+本番環境ではデバッグ情報とデバッグツールを無効にする
+----------------------------------------------------
 
 デバッグモードでは、Yii は極めて多くのエラー情報を出力します。これは確かに開発には役立つものです。
 しかし、実際の所、これらの饒舌なエラー情報は、攻撃者にとっても、データベース構造、構成情報の値、コードの断片などを曝露してくれる重宝なものです。
-実運用のアプリケーションにおいては、決して `index.php` の `YII_DEBUG` を `true` にして走らせてはいけません。
+本番でのアプリケーションにおいては、決して `index.php` の `YII_DEBUG` を `true` にして走らせてはいけません。
 
-実運用環境では Gii を決して有効にしてはいけません。
+本番環境では Gii を決して有効にしてはいけません。
 Gii を使うと、データベース構造とコードに関する情報を得ることが出来るだけでなく、コードを Gii によって生成したもので書き換えることすら出来てしまいます。
 
-デバッグツールバーは本当に必要でない限り実運用環境では使用を避けるべきです。
+デバッグツールバーは本当に必要でない限り本番環境では使用を避けるべきです。
 これはアプリケーションと構成情報の全ての詳細を曝露することが出来ます。
 どうしても必要な場合は、あなたの IP だけに適切にアクセス制限されていることを再度チェックしてください。

docs/guide-ja/start-installation.md

@@ -53,7 +53,7 @@ Composer がインストールされたら、ウェブからアクセスでき
 >
 >     composer create-project --prefer-dist --stability=dev yiisoft/yii2-app-basic basic
 >
-> 開発バージョンは動いているあなたのコードを動かなくするかもしれませんので、実運用環境では使うべきでないことに注意してください。
+> 開発バージョンは動いているあなたのコードを動かなくするかもしれませんので、本番環境では使うべきでないことに注意してください。
 
 
 アーカイブファイルからインストールする<a name="installing-from-archive-file"></a>
@@ -123,14 +123,14 @@ Yii の最低必要条件を満たすように PHP のインストールを構
 ウェブサーバを構成する<a name="configuring-web-servers"></a>
 ----------------------
 
-> Info|情報: もし Yii の試運転をしているだけで、実運用のサーバに配置する意図がないのであれば、当面、この項は飛ばしても構いません。
+> Info|情報: もし Yii の試運転をしているだけで、本番サーバに配置する意図がないのであれば、当面、この項は飛ばしても構いません。
 
 上記の説明に従ってインストールされたアプリケーションは、[Apache HTTP サーバ](http://httpd.apache.org/) と [Nginx HTTP サーバ](http://nginx.org/) のどちらでも、
 また、Windows、Mac OS X、Linux のどれでも、PHP 5.4 以上を走らせている環境であれば、そのままの状態で動作するはずです。
 Yii 2.0 は、また、facebook の [HHVM](http://hhvm.com/) とも互換性があります。
 ただし HHVM がネイティブの PHP とは異なる振舞いをする特殊なケースもいくつかありますので、HHVM を使うときはいくらか余分に注意を払う必要があります。
 
-実運用のサーバでは、`http://www.example.com/basic/web/index.php` の代りに `http://www.example.com/index.php` という URL
+本番用のサーバでは、`http://www.example.com/basic/web/index.php` の代りに `http://www.example.com/index.php` という URL
 でアプリケーションにアクセス出来るようにウェブサーバを設定したいと思うかもしれません。
 そういう設定をするためには、ウェブサーバのドキュメントルートを `basic/web` フォルダに向けることが必要になります。
 また、[ルーティングと URL 生成](runtime-routing.md) の節で述べられているように、URL から `index.php` を隠したいと思うかも知れません。

docs/guide-ja/structure-assets.md

@@ -440,7 +440,7 @@ return [
 HTTP リクエストの数とこれらのファイルの全体としてのダウンロードサイズを削減するためによく用いられる方法は、複数の CSS/JavaScript ファイルを結合して圧縮し、一つまたはごく少数のファイルにまとめることです。
 そして、ウェブページでは元のファイルをインクルードする代りに、圧縮されたファイルをインクルードする訳です。
  
-> Info|情報: アセットの結合と圧縮は、通常はアプリケーションが実運用モードにある場合に必要になります。
+> Info|情報: アセットの結合と圧縮は、通常はアプリケーションが本番モードにある場合に必要になります。
   開発モードにおいては、たいていは元の CSS/JavaScript ファイルを使う方がデバッグのために好都合です。
 
 次に、既存のアプリケーションコードを修正する必要なしに、アセットファイルを結合して圧縮する方法を紹介します。
@@ -526,7 +526,7 @@ return [
 ];
 ```
 
-つまり、アセットバンドルの構成情報配列は、実運用モードのためのものは `assets-prod.php` に保存し、開発モードのためのものは `assets-dev.php` に保存するという訳です。
+つまり、アセットバンドルの構成情報配列は、本番モードのものは `assets-prod.php` に保存し、開発モードのものは `assets-dev.php` に保存するという訳です。
 
 
 ### `asset` コマンドを使う <a name="using-asset-command"></a>

docs/guide-ja/structure-entry-scripts.md

@@ -92,7 +92,7 @@ Yii は下記の三つの定数をサポートしています:
   `YII_DEBUG` の既定値は false です。
 * `YII_ENV`: どういう環境でアプリケーションが走るかを規定します。
   詳細については、[構成情報](concept-configurations.md#environment-constants) の節で説明されます。
-  `YII_ENV` の既定値は `'prod'` です。これはアプリケーションが実運用環境で走ることを意味します。
+  `YII_ENV` の既定値は `'prod'` です。これはアプリケーションが本番環境で走ることを意味します。
 * `YII_ENABLE_ERROR_HANDLER`: Yii によって提供されるエラーハンドラを有効にするかどうかを規定します。
   この定数の既定値は true です。
 

docs/guide-ja/tool-api-doc.md

+API ドキュメントを生成する
+==========================
+
+> Note|注意: この節はまだ執筆中です。
+>
+> まだ内容がありません。

docs/guide-ja/tool-debugger.md

+デバッグツールバーとデバッガ
+============================
+
+> Note|注意: この節はまだ執筆中です。
+
+Yii2 には、アプリケーションの迅速な開発とデバッグのために、便利なツールバーと内蔵のデバッガが付いています。
+ツールバーは現在開かれているページに関する情報を表示します。
+そして、デバッガはそれまでに収集したデータを分析する (すなわち、変数の値を確認する) のに使用できます。
+
+これらのツールは、特別な設定をしなくても、次のことを可能にしてくれます。
+
+- フレームワークのバージョン、PHP バージョン、レスポンスステータス、現在のコントローラとアクション、パフォーマンス情報、その他をツールバーによって素速く取得
+- アプリケーションと PHP の構成の閲覧
+- リクエストデータ、リクエストとレスポンスのヘッダ、セッションデータ、そして環境変数の閲覧
+- ログの閲覧、検索、フィルタリング
+- プロファイリング結果の閲覧
+- ページによって実行されたデータベースクエリの閲覧
+- アプリケーションから送信されたメールの閲覧
+
+これらの情報の全てはリクエストごとに閲覧できますが、過去のリクエストに遡って情報を閲覧することも可能です。
+
+
+インストールと構成
+------------------
+
+これらの機能を有効にするためには、構成情報ファイルに以下の行を追加してデバッグモジュールを有効にします。
+
+```php
+'bootstrap' => ['debug'],
+'modules' => [
+    'debug' => 'yii\debug\Module',
+]
+```
+
+デフォルトでは、デバッグモジュールはウェブサイトをローカルホストから閲覧した場合にだけ動作します。
+これをリモートサーバ (ステージングサーバ) で使いたい場合は、パラメータ `allowedIPs` を構成情報に追加して、あなたの IP をホワイトリストに加えてください。
+
+```php
+'bootstrap' => ['debug'],
+'modules' => [
+    'debug' => [
+        'class' => 'yii\debug\Module',
+        'allowedIPs' => ['1.2.3.4', '127.0.0.1', '::1']
+    ]
+]
+```
+
+URL マネージャで `enableStrictParsing` オプションを使っている場合は、`rules` に次の行を追加してください。
+
+```php
+'urlManager' => [
+    'enableStrictParsing' => true,
+    'rules' => [
+        // ...
+        'debug/<controller>/<action>' => 'debug/<controller>/<action>',
+    ],
+],
+```
+
+> Note|注意: デバッガは各リクエストに関する情報を `@runtime/debug` ディレクトリに保存します。
+> デバッガを使用するのに問題が生じたとき、例えば、デバッガを使おうとするとおかしなエラーメッセージが出たり、ツールバーが表示されなかったり、何も結果が表示されなかったりしたときは、ウェブサーバがこのディレクトリとその中に置かれるファイルに対して十分なアクセス権限を持っているかどうかを確認してください。
+
+
+### ロギングとプロファイリングのための追加の構成
+
+ロギングとプロファイリングは、フレームワークとアプリケーションの両方の実行フローを理解するのを助けてくれる、単純ながら強力なツールです。これらのツールは、開発環境でも本番環境でも役に立ちます。
+
+本番環境では、[ロギング](logging.md) のガイドの節で説明されているように、著しく重要なメッセージを手動でログに取るだけにとどめるべきです。
+本番環境で全てのメッセージをログに取り続けるのは、パフォーマンスへの損害が大きすぎます。
+
+開発環境では、ログは多く取れば取るほど良いでしょう。とりわけ、実行トレースの記録は有用です。
+
+フレームワークのフードの下で何が起っているかを理解する手助けとなるトレースメッセージを見るためには、構成情報ファイルでトレースレベルを設定する必要があります。
+
+```php
+return [
+    // ...
+    'components' => [
+        'log' => [
+            'traceLevel' => YII_DEBUG ? 3 : 0, // <-- ここ
+```
+
+デフォルトでは、Yii がデバッグモードで走っている場合のトレースレベルは自動的に `3` に設定されます。
+デバッグモードは `index.php` ファイルに次の行が存在することによって決定されます。
+
+```php
+defined('YII_DEBUG') or define('YII_DEBUG', true);
+```
+
+> Note|注意: デバッグモードはパフォーマンスに著しい悪影響を及ぼし得ますので、本番環境では必ずデバッグモードを無効にしてください。
+更に、デバッグモードは公開すべきでない情報をエンドユーザに曝露することがあり得ます。
+
+
+あなた自身のパネルを作る
+------------------------
+
+ツールバーとデバッガは、ともに、高い構成可能性とカスタマイズ性を持っています。
+あなた自身のパネルを作成して、あなたが必要とする特定のデータを収集して表示することも出来ます。
+以下において、簡単なカスタムパネルを作るプロセスを説明します。このパネルは以下の機能を持つものとします。
+
+- リクエストの間にレンダリングされたビューを収集する
+- ツールバーにレンダリングされたビューの数を表示する
+- デバッガでビューの名前を確認することが出来る
+
+ベーシックアプリケーションテンプレートを使用しているものと仮定します。
+
+最初に、`panels/ViewsPanel.php` で `Panel` クラスを実装する必要があります。
+
+```php
+<?php
+namespace app\panels;
+
+use yii\base\Event;
+use yii\base\View;
+use yii\base\ViewEvent;
+use yii\debug\Panel;
+
+
+class ViewsPanel extends Panel
+{
+    private $_viewFiles = [];
+
+    public function init()
+    {
+        parent::init();
+        Event::on(View::className(), View::EVENT_BEFORE_RENDER, function (ViewEvent $event) {
+            $this->_viewFiles[] = $event->sender->getViewFile();
+        });
+    }
+
+
+    /**
+     * @inheritdoc
+     */
+    public function getName()
+    {
+        return 'Views';
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function getSummary()
+    {
+        $url = $this->getUrl();
+        $count = count($this->data);
+        return "<div class=\"yii-debug-toolbar-block\"><a href=\"$url\">ビュー数 <span class=\"label\">$count</span></a></div>";
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function getDetail()
+    {
+        return '<ol><li>' . implode('<li>', $this->data) . '</ol>';
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function save()
+    {
+        return $this->_viewFiles;
+    }
+}
+```
+
+上記のコードのワークフローは以下のとおりです。
+
+1. 全てのコントローラのアクションが走る前に `init` が実行されます。
+   コントローラのアクションが実行される間にデータを収集するハンドラをアタッチするには、このメソッドが最適の場所です。
+2. コントローラのアクションが実行された後に `save` が呼ばれます。
+   このメソッドによって返されたデータは、データファイルに保存されます。
+   このメソッドが何も返さなかった場合には、パネルは表示されません。
+3. データファイルからのデータは `$this->data` にロードされます。
+   ツールバーの場合は、これは常に最新のデータを表します。
+   デバッガの場合は、このプロパティを以前のデータファイルから読み出すようにセットされることもあります。
+4. ツールバーはその内容を `getSummary` から取得します。
+   そこではレンダリングされたビューの数を表示します。
+   デバッガは同じ目的のために `getDetail` を使用します。
+
+さあ、それでは、デバッガに新しいパネルを使うように教えましょう。
+`config/web.php` で、デバッガの構成を次のように変更します。
+
+```php
+if (YII_ENV_DEV) {
+    // configuration adjustments for 'dev' environment
+    $config['bootstrap'][] = 'debug';
+    $config['modules']['debug'] = [
+        'class' => 'yii\debug\Module',
+        'panels' => [
+            'views' => ['class' => 'app\panels\ViewsPanel'],
+        ],
+    ];
+
+// ...
+```
+
+以上です。これで、たいしてコードを書くこともなく、もう一つの便利なパネルを手に入れました。