added japanese docs

docs/ja/build.md

@@ -0,0 +1,30 @@
+アセットのビルドとダンプ
+---------------------------
+
+Asseticを使う一番単純な方法は、次の2ステップからなります。
+
+ 1. 公開領域内にPHPスクリプトを作成し、Assetic OOP APIを使用してアセットの作成・出力を行う
+ 2. テンプレートから上記のファイルを参照する
+
+例えば、公開領域内に`assets/javascripts.php`ファイルを作成し、
+下記のようなコードを記述します。
+
+    use Assetic\Asset\AssetCollection;
+    use Assetic\Asset\FileAsset;
+    use Assetic\Filter\Yui\JsCompressorFilter as YuiCompressorFilter;
+
+    $js = new AssetCollection(array(
+        new FileAsset(__DIR__.'/jquery.js'),
+        new FileAsset(__DIR__.'/application.js'),
+    ), array(
+        new YuiCompressorFilter('/path/to/yuicompressor.jar'),
+    ));
+
+    header('Content-Type: application/js');
+    echo $js->dump();
+
+HTMLテンプレート側では、単に`<script>`タグを用いて、生成されたJavascriptをインクルードすることになります。
+
+    <script src="/assets/javascripts.php"></script>
+
+Next: [コンセプト](concepts.md)

docs/ja/concepts.md

@@ -0,0 +1,121 @@
+Assetic OOP APIを使用するためには、まず、[アセット」と「フィルタ」の2つの重要なコンセプトを理解する必要があります。
+
+### アセット
+
+アセットとは、読み込み、及びダンプが可能な、コンテンツとメタデータを内包しているオブジェクトの事を指します。
+大体の場合において3つのカテゴリー、すなわち、Javascriptとスタイルシート、画像のどれかに属することになるでしょう。
+読み込みの方法としては、ファイルシステムからがほとんどですが、
+HTTPやデータベース経由でも、文字列としてでも読み込みが可能で、事実上あらゆるものが読み込み可能です。
+Asseticのアセットインターフェースを満足させさえすれば良いのです。
+
+
+### フィルタ
+
+フィルタは、アセットが読み込まれる、かつ/もしくは、ダンプされる際に、
+アセットコンテンツに対して作用するオブジェクトです。
+アセットと同様に、Asseticのフィルタインターフェースを実装することで、
+どのような作用も可能になります。
+
+フィルタを用いて、アセットに適用できるツール群の一覧です。
+
+ * CoffeeScript
+ * CssEmbed
+ * CssMin
+ * Google Closure Compiler
+ * jpegoptim
+ * jpegtran
+ * Less
+ * LessPHP
+ * optipng
+ * Packager
+ * pngout
+ * SASS
+ * Sprockets (version 1)
+ * Stylus
+ * YUI Compressor
+
+
+### アセットとフィルタの使用
+
+まずはアセットオブジェクトを作成することから始まります。
+多くの場合は`FileAsset`をインスタンス化し、ファイルシステムのパスを第一引数に渡します。
+
+    $asset = new Assetic\Asset\FileAsset('/path/to/main.css');
+
+アセットオブジェクトを作成したら、`ensureFilter()`を呼び、フィルタを追加します。
+例えば、アセットコンテンツにYUI Compressorを適用してみましょう。
+
+    $yui = new Assetic\Filter\Yui\CssCompressorFilter('/path/to/yui.jar');
+    $asset->ensureFilter($yui);
+
+任意のフィルタを追加したら、完成したアセットをブラウザに出力してみましょう。
+
+    header('Content-Type: text/css');
+    echo $asset->dump();
+
+### アセットコレクション
+
+1つのファイルに同じ種類のアセットをまとめて、不要なHTTPリクエストを抑えてみるのも良いでしょう。
+Asseticでは`AsseticColletion`クラスを使用することで可能となります。
+Assetic内部的には、このクラス自体は他のアセットと同様に、アセットインターフェースを実装したものですが、
+複数のアセットを1つにまとめることが可能になります。
+
+    use Assetic\Asset\AssetCollection;
+
+    $asset = new AssetCollection(array(
+        new FileAsset('/path/to/js/jquery.js'),
+        new FileAsset('/path/to/js/jquery.plugin.js'),
+        new FileAsset('/path/to/js/application.js'),
+    ));
+
+### ネストしたアセットコレクション
+
+コレクションクラス自体がアセットインターフェースを実装し、コレクション内のアセットも同様に
+アセットインターフェースを実装しているので、簡単にネストすることができます。
+
+    use Assetic\Asset\AssetCollection;
+    use Assetic\Asset\GlobAsset;
+    use Assetic\Asset\HttpAsset;
+
+    $asset = new AssetCollection(array(
+        new HttpAsset('http://example.com/jquery.min.js'),
+        new GlobAsset('/path/to/js/*'),
+    ));
+
+`HttpAsset`は、HTTP経由でファイルを読み込むアセットクラス。
+`GlobAsset`は、ファイルシステムのglobを基にファイル群を読み込むアセットコレクションクラス。
+両者ともにアセットインターフェースを実装しています。
+
+このネストしたアセットコレクションという概念は、コレクションそれぞれに異なる
+フィルタ群を適用しようとしたときに、効果を発揮します。
+例えば、スタイルシートがSAASで記述されたものと、vanilla CSSを用いて記述されたものからなる
+アプリケーションを考えた場合、次のようにして、全てを1つのシームレスなCSSアセットにまとめることができます。
+
+    use Assetic\Asset\AssetCollection;
+    use Assetic\Asset\GlobAsset;
+    use Assetic\Filter\SassFilter;
+    use Assetic\Filter\Yui\CssCompressorFilter;
+
+    $css = new AssetCollection(array(
+        new GlobAsset('/path/to/sass/*.sass', array(new SassFilter())),
+        new GlobAsset('/path/to/css/*.css'),
+    ), array(
+        new YuiCompressorFilter('/path/to/yuicompressor.jar'),
+    ));
+
+上記の例では、1つにまとめられたCSSを、さらにYUI compressorフィルタを適用することで、全体を圧縮しています。
+
+### アセットコレクションのイテレーション
+
+アセットコレクションは、旧来のPHP配列のように、イテレートできます。
+
+    echo "Source paths:\n";
+    foreach ($collection as $asset) {
+        echo ' - '.$asset->getSourcePath()."\n";
+    }
+
+アセットコレクションのイテレーションは再帰的で、「葉」にあたるアセットの取得を行います。
+また、気の利いたフィルタを内蔵しているので、同じアセットがコレクション内に複数存在する場合でも、
+一度だけのインクルードが保証されます。
+
+Next: [アセットを「オンザフライ」で定義する](define.md)

docs/ja/define.md

@@ -0,0 +1,140 @@
+アセットの「オンザフライ」な定義
+----------------------------------------
+
+Asseticの使用方法二つ目は、独立したPHPファイルを使用する代わりに、
+テンプレートで「オンザフライ」にアセット定義をする方法です。
+このアプローチでは、PHPテンプレートは下記のようになります。
+
+    <script src="<?php echo assetic_javascripts('js/*', 'yui_js') ?>"></script>
+
+`assetic_javascripts()`の呼び出しは2つの目的を兼ねています。
+まず、「フォーミュラローダー」により走査され、アセットの構築、ダンプ、及び出力を行うための「フォーミュラ(処方箋)」が抽出されます。
+また、テンプレートのレンダー時にも実行され、アセットの出力パスが出力されます。
+
+Asseticには下記のようなヘルパー関数があります。
+
+ * `assetic_image()`
+ * `assetic_javascripts()`
+ * `assetic_stylesheets()`
+
+アセットをオンザフライに定義するということは、より高度なテクニックであり、
+そのため、重い仕事をするサービスに依存することになります。
+そのうちの重要なものがアセットファクトリです。
+
+### アセットファクトリ
+
+アセットファクトリは、アセットオブジェクトを、配列とスカラ値のみから、
+どのように作成するのか把握しています。
+`assetic_*`ヘルパー関数で使用する記法と同様のものとなります。
+
+    use Assetic\Factory\AssetFactory;
+
+    $factory = new AssetFactory('/path/to/web');
+    $js = $factory->createAsset(array(
+        'js/jquery.js',
+        'js/jquery.plugin.js',
+        'js/application.js',
+    ));
+
+### フィルタマネージャー
+
+ファクトリによって作成されたアセットに対しても、フィルタを適用することができます。
+そのためには、`FilterManager`を設定して、名前を定義しフィルタを構成します。
+
+    use Assetic\FilterManager;
+    use Assetic\Filter\GoogleClosure\ApiFilter as ClosureFilter;
+
+    $fm = new FilterManager();
+    $fm->set('closure', new ClosureFilter());
+    $factory->setFilterManager($fm);
+
+    $js = $factory->createAsset('js/*', 'closure');
+
+上記の例では、Google Closure Compilerフィルタをインスタンス化し、
+フィルタマネージャーを通じて`closure`という名前をつけています。
+このフィルタマネージャーをアセットファクトリに渡すことで、
+アセット作成時には、`closure`という名前でフィルタを使用できるようになります。
+
+### デバッグモード
+
+アセットファクトリは、デバッグモードというコンセプトも取り入れており、
+デバッグモードの設定により、ファクトリが作成するアセットから、
+特定のフィルタを除外することができます。
+
+たとえば、YUI Compressorは大変素晴らしいのですが、圧縮されたJavascriptを
+デバッグするのは大変難しく、プロダクション環境でのみの使用が適切でしょう。
+
+    use Asset\Factory\AssetFactory;
+
+    $factory = new AssetFactory('/path/to/web', true); // デバッグモードON
+    $factory->setFilterManager($fm);
+    $js = $factory->createAsset('js/*', '?closure');
+
+フィルタ名`closure`の前にクエスチョンマークを記述すると、ファクトリに対して、
+このフィルタはオプションであり、
+デバッグモードがOFFの時にのみ適用するように通知することができます。
+
+### アセットマネージャーとアセットリファレンス
+
+アセットファクトリにはもう一つ特別な記法があり、別の場所で定義した
+アセットを参照することができるようになります。
+これを「アセットリファレンス」と呼び、アセットマネージャーを通じて、
+フィルタマネージャーと同様の、名前によるアセットの構成が可能です。
+
+    use Assetic\AssetManager;
+    use Assetic\Asset\FileAsset;
+    use Assetic\Factory\AssetFactory;
+
+    $am = new AssetManager();
+    $am->set('jquery', new FileAsset('/path/to/jquery.js'));
+
+    $factory = new AssetFactory('/path/to/web');
+    $factory->setAssetManager($am);
+
+    $js = $factory->createAsset(array(
+        '@jquery',
+        'js/application.js',
+    ));
+
+### テンプレートからのアセット抽出
+
+テンプレート内でアセット群を定義したら、「フォーミュラローダー」サービスを使用して、
+アセットの定義を抽出します。
+
+    use Assetic\Factory\Loader\FunctionCallsFormulaLoader;
+    use Assetic\Factory\Resource\FileResource;
+
+    $loader = new FunctionCallsFormulaLoader($factory);
+    $formulae = $loader->load(new FileResource('/path/to/template.php'));
+
+これらのフォーミュラ自体は、それ自体で使途はあまりなく、
+アセットファクトリが目的のアセットオブジェクトを作成するに足る情報しか持っていません。
+`LazyAssetManager`でラップすることで有益なものとなります。
+
+### レイジーなアセットマネージャー
+
+このサービスは、アセットファクトリと、1つ以上のフォーミュラローダーから成っており、
+裏方のサービス間のグルとして動作しますが、表面上では、通常のアセットマネージャーと同じように使用することができます。
+
+    use Assetic\Asset\FileAsset;
+    use Assetic\Factory\LazyAssetManager;
+    use Assetic\Factory\Loader\FunctionCallsFormulaLoader;
+    use Assetic\Factory\Resource\DirectoryResource;
+
+    $am = new LazyAssetManager($factory);
+    $am->set('jquery', new FileAsset('/path/to/jquery.js'));
+    $am->setLoader('php', new FunctionCallsFormulaLoader($factory));
+    $am->addResource(new DirectoryResource('/path/to/templates', '/\.php$/'), 'php');
+
+### アセットライター
+
+作成したアセットマネージャーが、テンプレート内で定義した全てのアセットを把握したら、
+アセットライターを使用して、テンプレートが参照することになる実際のファイルを作成します。
+
+    use Assetic\AssetWriter;
+
+    $writer = new AssetWriter('/path/to/web');
+    $writer->writeManagerAssets($am);
+
+上記のスクリプトを実行すると、アセットマネージャー内のすべてのアセットがメモリに読み込まれ、
+指定したフィルタが適用された後、公開領域に静的ファイルとしてダンプされ、準備完了となります。

docs/ja/index.md

@@ -0,0 +1,7 @@
+目次
+-----
+
+ 1. [イントロダクション](introduction.md)
+ 2. [アセットの構築とダンプ](build.md)
+ 3. [コンセプト](concepts.md)
+ 4. [アセットを「オンザフライ」で定義する](define.md)

docs/ja/introduction.md

@@ -0,0 +1,18 @@
+Asseticとは
+-----------------
+
+Asseticは、PHP5.3用のアセット管理フレームワークです。
+Asseticを導入することで、Javascriptやスタイルシート、画像をコントロールする
+様々なサードパーティー製のツールを使用できるようになります。
+
+Asseticの使用方法
+---------------------
+
+2つの異なるアプローチがあります。
+
+ 1. アセットのビルド、ダンプ、出力をPHPファイルで行い、テンプレートからそのファイルを直接参照する方法
+ 2. テンプレート内でアセットを(「オンザフライ」に)定義し、抽出やダンプ、出力にローダーを使用する方法
+
+前者はいくらかシンプルである一方、後者は動的で柔軟性に富み、最適化が可能となります。
+
+Next: [アセットの構築とダンプ](build.md)