Merge remote-tracking branch 'ja-translation/ja'

Conflicts:
	doc/language.json

Author: ZhangYiJiang

.gitignore

@@ -10,5 +10,6 @@
 /site/fi
 /site/pl
 /site/tr
+/site/ja
 *.md~
 *.src.md

build.js

@@ -1,5 +1,5 @@
 var fs = require('fs'),
-    path = require('path');
+    path = require('path'),
     jade = require('jade'),
     md = require('node-markdown'),
     Class = require('neko').Class;
@@ -28,10 +28,10 @@ var Garden = Class(function(options) {
 
             if (that.loadIndex()) {
                 that.languages[lang] = that.lang;
-                that.log('    Done.')
+                that.log('    Done.');
 
             } else {
-                that.log('    Error: Could not find "index.json"!')
+                that.log('    Error: Could not find "index.json"!');
             }
         }
     });

doc/ja/array/constructor.md

@@ -0,0 +1,25 @@
+## `Array`コンストラクター
+
+`Array`コンストラクターはそのパラメーターの扱い方が曖昧なので、新しい配列を作る時には、常に配列リテラル - `[]`記法 - を使用する事を強くお勧めします。
+
+    [1, 2, 3]; // 結果: [1, 2, 3]
+    new Array(1, 2, 3); // 結果: [1, 2, 3]
+
+    [3]; // Result: [3]
+    new Array(3); // 結果: []
+    new Array('3') // 結果: ['3']
+
+このケースの場合、`Array`コンストラクターに渡される引数は一つだけですが、その引数は`Number`になります。コンストラクターは、引数に値がセットされた`length`プロパティを伴った新しい*疎*配列を返します。特筆すべきなのは、新しい配列の`length`プロパティ**のみ**が、このようにセットされるという事です。実際の配列のインデックスは初期化されません。
+
+    var arr = new Array(3);
+    arr[1]; // undefined
+    1 in arr; // false, インデックスがセットされていない
+
+配列の長さが先行してセットされるという振舞いは、いくつかの場合に便利です。例えば、文字の繰り返しや、`for loop`を使用したコードの回避などの場合です。
+
+    new Array(count + 1).join(stringToRepeat);
+
+### 終わりに
+
+`Array`コンストラクターの使用は出来る限り避けてください。リテラルが当然望ましい形です。それらは、短かく明快な文法にもってるいる為に、コードの可読性を高めてくれます。
+

doc/ja/array/general.md

@@ -0,0 +1,41 @@
+## 配列の繰り返しとプロパティ
+
+JavaScriptの配列もまたオブジェクトですので[`for in ループ`](#object.forinloop)を配列の繰り返しで使用するような理由はありません。実際、配列に`for in`を使用**しない**為の正当な理由はたくさんあります。
+
+> **注意:** JavaScriptの配列は*連想配列*では**ありません**。JavaScriptは[objects](#object.general)だけがキーバリューをマッピングするものです。
+> また、連想配列は順序を**保持**しますが、オブジェクトは**保持しません**。
+
+`for in`ループはプロトタイプチェーン上の全てのプロパティを列挙するため、[`hasOwnProperty`](#object.hasownproperty)をそれらのプロパティの存在判定に使います。この為、通常の`for`ループよりも**20倍**遅くなります。
+
+### 繰り返し
+
+配列の要素を繰り返すとのに、最高のパフォーマンスを出したければ昔ながらの`for`ループを使うのが一番です。
+
+    var list = [1, 2, 3, 4, 5, ...... 100000000];
+    for(var i = 0, l = list.length; i < l; i++) {
+        console.log(list[i]);
+    }
+
+上記の例では一つ余分に変数がありますが、それは配列の長さを取るための`l = list.length`の部分です。
+
+また、`length`プロパティは配列自身に定義されていますが、ループのそれぞれの繰り返しで探索する為のオーバーヘッドがまだあります。最近のJavaScriptエンジンはこのような場合に最適化する**はず**です。新しいエンジンか古いエンジンで実行されるかどうかをコードが知る方法はありません。
+
+実際には、キャッシュを抜きにするとループの結果はキャッシュされたものに比べて、**半分だけ高速**になっています。
+
+### `length`プロパティ
+
+`length`プロパティの*ゲッター*は単に配列に含まれる要素の数を返すだけにも関わらず、*セッター*は配列を**トランケート**する為にも使用できます。
+
+    var foo = [1, 2, 3, 4, 5, 6];
+    foo.length = 3;
+    foo; // [1, 2, 3]
+
+    foo.length = 6;
+    foo; // [1, 2, 3]
+
+より小さいlengthを割り当てると配列をトランケートしますが、lengthが大きくなっても配列には何も影響しません。
+
+### 終わりに
+
+最高のパフォーマンスの為には、常に`for`ループを使用し、`length`プロパティをキャッシュする事をお勧めします。`for in`ループを配列で使用するのは、バグや最低のパフォーマンスの傾向があるコードを書く前兆になります。
+

doc/ja/core/eval.md

@@ -0,0 +1,39 @@
+## なぜ、`eval`を使ってはいけないのか
+
+`eval`関数はローカルスコープ中のJavaScriptコードの文字列を実行します。
+
+    var foo = 1;
+    function test() {
+        var foo = 2;
+        eval('foo = 3');
+        return foo;
+    }
+    test(); // 3
+    foo; // 1
+
+しかし、`eval`は**直接**ローカルスコープから呼ばれて、*かつ*呼んだ関数の名前が実際の`eval`でないと実行しません。
+
+    var foo = 1;
+    function test() {
+        var foo = 2;
+        var bar = eval;
+        bar('foo = 3');
+        return foo;
+    }
+    test(); // 2
+    foo; // 3
+
+`eval`の使用は**全てのコスト**を払ってでも回避するべきです。その「使用法」の99.9%で、これ**無し**でも実装できます。
+
+### 偽装された`eval`
+
+[timeout functions](#other.timeouts)である`setTimeout`と`setInterval`はどちらも最初の引数として文字列を取る事ができます。この文字列は`eval`がこの場合直接呼ばれていないので、**常に**グローバルスコープで実行されてしまいます。
+
+### セキュリティの問題
+
+`eval`はまたセキュリティの問題もあります。なぜなら、**どんな**コードを与えられても実行してしまうからで、**絶対**に不明または信頼できない発行元の文字列は使ってはいけません。
+
+### 終わりに
+
+`eval`は絶対に使用しないでください。これを使用しているどんなコードも、その働き、パフォーマンスやセキュリティについて問われてしまいます。`eval`が必要な場合でも、最初の段階で使用**しない**でください。*より良いデザイン*を使用するべきで、それには`eval`を使う必要性はありません。
+

doc/ja/core/semicolon.md

@@ -0,0 +1,101 @@
+## セミコロン自動挿入
+
+JavaScriptはC言語スタイルのシンタックスを持っていますが、これはソースコードの中でセミコロンの使用を強制している事には**ならない**ので、これらを省略する事も可能です。
+
+JavaScriptはセミコロン無しの言語ではありません。実際に、ソースコードを理解する為にもセミコロンは必要になります。ですので、JavaScriptのパーサーはセミコロンが無い事によるパースエラーを検出する度に、**自動的**にセミコロンを挿入します。
+
+    var foo = function() {
+    } // セミコロンが入っている事が期待されるので、パースエラーになる
+    test()
+
+挿入が起こると、パーサーはもう一度パースします。
+
+    var foo = function() {
+    }; // エラーが無いので、パーサーは次の解析をする
+    test()
+
+セミコロンの自動挿入は、コードの振る舞いを変えられる為に、言語の**最大**の欠陥の内の一つと考えられています。
+
+### どのように動くか
+
+以下のコードはセミコロン無いので、パーサーはどこに挿入するか決めなくてはなりません。
+
+    (function(window, undefined) {
+        function test(options) {
+            log('testing!')
+
+            (options.list || []).forEach(function(i) {
+
+            })
+
+            options.value.test(
+                'long string to pass here',
+                'and another long string to pass'
+            )
+
+            return
+            {
+                foo: function() {}
+            }
+        }
+        window.test = test
+
+    })(window)
+
+    (function(window) {
+        window.someLibrary = {}
+
+    })(window)
+
+下記がパーサーの「推測」ゲームの結果になります。
+
+    (function(window, undefined) {
+        function test(options) {
+
+            // 行がマージされて、挿入されない
+            log('testing!')(options.list || []).forEach(function(i) {
+
+            }); // <- 挿入
+
+            options.value.test(
+                'long string to pass here',
+                'and another long string to pass'
+            ); // <- 挿入
+
+            return; // <- inserted, breaks the return statement
+            { // ブロックとして扱われる
+
+                // a label and a single expression statement
+                foo: function() {} 
+            }; // <- 挿入
+        }
+        window.test = test; // <- 挿入
+
+    // 再度行がマージされる
+    })(window)(function(window) {
+        window.someLibrary = {}; // <- 挿入
+
+    })(window); //<- 挿入
+
+> **注意点:** JavaScriptパーサーは新しい行のreturn文を「正しく」返してはいないですが、
+> これは必要という訳では無いので自動セミコロン挿入の障害になります。
+> このお陰で不必要な副作用を無くす事にもなります。
+
+パーサーは上記のコードの振舞いを劇的に変化させます。あるケースにおいては、**間違っている事**にもなってしまいます。
+
+### 先頭の括弧
+
+先頭に括弧がある場合、パーサーはセミコロンを挿入**しません**。
+
+    log('testing!')
+    (options.list || []).forEach(function(i) {})
+
+このコードは1つの行に変形します。
+
+    log('testing!')(options.list || []).forEach(function(i) {})
+
+`log`が関数を返さ**ない**確率は**とても**高いです。しかし、上記では`undefined is not a function`という`TypeError`が繰り返されます。
+
+### 終わりに
+
+セミコロンを省略するのは**絶対**にお勧めしません。この事はまた括弧をその終端と一緒の行に書く事が推奨されてますし、1つの`if`や`else`文を絶対に省略してはなりません。これら両方の処理がコードの整合性を高めてくれる上、JavaScriptパーサーの振舞いを変えてしまうのを防いでくれるでしょう。

doc/ja/core/undefined.md

@@ -0,0 +1,53 @@
+## `undefined`と`null`
+
+JavaScriptは`nothing`を表す2つの別個の値を持っています。`undefined`はこれら2つの内より便利な存在です。
+
+### `undefined`の値
+
+`undefined`はただ1つの値`undefined`を持つ型です。
+
+この言語はまた、`undefined`の値を持つグローバル変数を定義しています。この値もまた`undefined`と呼ばれています。しかし、この変数は **どちらも** 言語のキーワードではなく、定数です。この事はこの*値*は簡単に上書きされてしまうという事になります。
+
+> **ES5での注意点:** ECMAScript 5での`undefined`は **もはや** strict modeでは *書き変えられない*
+> ようになっています。しかし、この名前は`undefined`という名前の関数の例に痕跡が見られるだけです。
+
+`undefined`が帰される時の例をいくつか挙げます。
+
+ - (未定義の)グローバル変数`undefined`にアクセスした時
+ - `return`文が無い為に、暗黙のうちに関数が返された時
+ - 何も返されない`return`がある時
+ - 存在しないプロパティを探索する時
+ - 関数のパラメーターで明示的な値が何も無い時
+ - 全ての`undefined`が設定された値
+
+### `undefined`の値に変更する処理
+
+グローバル変数`undefined`のみが実際の`undefined`の*値*のコピーを保持するので、これに新しい値を代入しても`undefined`の*型* の値が変更される事は**ありません**。
+
+まだ、`undefined`の値に対して何かしらの比較をしないといけない場合は、最初に`undefined`の値を取得する必要があります。
+
+コードの`undefined`の変数の上書きを可能な限りしないよう保護する為には、一般的なテクニックとして[anonymous wrapper](#function.scopes)の引数にパラメーターを追加するというものがあります。
+
+    var undefined = 123;
+    (function(something, foo, undefined) {
+        // ローカルスコープではundefined。
+        // ここで値に対して参照がされる
+
+    })('Hello World', 42);
+
+同じ効果を得る事ができる別の方法として、ラッパーの内部での宣言を使うものがあります。
+
+    var undefined = 123;
+    (function(something, foo) {
+        var undefined;
+        ...
+
+    })('Hello World', 42);
+
+これらの唯一の違いは、こちらのバージョンの方が4バイト余計に短縮できるという物です。また、他に`var`ステートメントは匿名ラッパーの中にはありません。
+
+### `null`の使用
+
+JavaScriptというプログラム言語のコンテキストの中では、`undefined`は主に伝統的な意味での*null*の意味で使用される事が多いです。実際の`null`(リテラルも型も両方)は多かれ少なかれ、単なるデータ型です。
+
+それはJavaScriptの内部でいくつか使われています(プロトタイプチェーンの終わりに`Foo.prototype = null`という宣言をするようなもの)が、ほとんど全てのケースで、`undefined`に置き替える事が可能です。

doc/ja/function/arguments.md

@@ -0,0 +1,98 @@
+## オブジェクトの`arguments`
+
+JavaScriptの全ての関数スコープは`arguments`と呼ばれる特別な変数にアクセスできます。この変数は関数が受け取った全ての引数を保持する変数です。
+
+> **注意:** `arguments`が既に`var`や正式なパラメーターにより
+> 関数のスコープが定義されている場合は
+> `arguments`オブジェクトは作られません。
+
+`arguments`オブジェクトは`Array`では**ありません**。これは配列と同じような -`length`プロパティと名付けられています- 文法を持っていますが、`Array.prototype`を継承している訳では無いので、実際`Object`になります。
+
+この為、`arguments`で`push`や`pop`、`slice`といった通常の配列メソッドは使用する事が**出来ません**。プレーンな`for`ループのような繰り返しでは上手く動作しますが、通常の`Array`メソッドを使いたい場合は本当の`Array`に変換しなければなりません。
+
+### 配列への変換
+
+下のコードは`arguments`オブジェクトの全ての要素を含んだ新しい`Array`を返します。
+
+    Array.prototype.slice.call(arguments);
+
+この変換は**遅い**です。コードのパフォーマンスに関わる重要な部分での使用は**推奨しません**。
+
+### 引き数の受け渡し
+
+下記の例はある関数から別の関数に引数を引き渡す際に推奨される方法です。
+
+    function foo() {
+        bar.apply(null, arguments);
+    }
+    function bar(a, b, c) {
+        // do stuff here
+    }
+
+他のテクニックとして、高速で非結合のラッパーとして`call`と`apply`両方を一緒に使用するという物があります。
+
+    function Foo() {}
+
+    Foo.prototype.method = function(a, b, c) {
+        console.log(this, a, b, c);
+    };
+
+    // "メソッド"の非結合バージョンを作成する
+    // このメソッドはthis, arg1, arg2...argNのパラメーターを持っている
+    Foo.method = function() {
+
+        // 結果: Foo.prototype.method.call(this, arg1, arg2... argN)
+        Function.call.apply(Foo.prototype.method, arguments);
+    };
+
+
+### 仮パラメーターと引数のインデックス
+
+`arguments`オブジェクトは*ゲッター*と*セッター*機能を自身のプロパティと同様に関数の仮パラメーターとして作成します。
+
+結果として、仮パラメーターを変更すると`arguments`の対応する値も変更されますし、逆もしかりです。
+
+    function foo(a, b, c) {
+        arguments[0] = 2;
+        a; // 2
+
+        b = 4;
+        arguments[1]; // 4
+
+        var d = c;
+        d = 9;
+        c; // 3
+    }
+    foo(1, 2, 3);
+
+### パフォーマンスの神話と真実
+
+`arguments`オブジェクトは、関数の内部の名前宣言と仮パラメーターという2つの例外を常に持ちながら生成されます。これは、使用されているかどうかは関係がありません。
+
+*ゲッター*と*セッター*は両方とも**常に**生成されます。その為これを使用してもパフォーマンスに影響は全くといって言い程ありません。`arguments`オブジェクトのパラメーターに単純にアクセスしているような、実際のコードであれば尚更です。
+
+> **ES5での注意:** strictモードでは、これら*ゲッター*と*セッター*は生成されません。
+
+しかし、一つだけモダンJavaScriptエンジンにおいて劇的にパフォーマンスが低下するケースがあります。そのケースとは`arguments.callee`を使用した場合です。
+
+    function foo() {
+        arguments.callee; // この関数オブジェクトで何かする
+        arguments.callee.caller; // そして関数オブジェクトを呼び出す
+    }
+
+    function bigLoop() {
+        for(var i = 0; i < 100000; i++) {
+            foo(); // 通常はインライン展開する
+        }
+    }
+
+上記のコードでは、`foo`は自身と自身の呼び出し元の両方を知らないと[インライン展開][1]の対象になる事が出来ません。この事は、インライン展開によるパフォーマンスの向上の機会を失くす事になり、また、特定のコンテクストの呼び出しに依存する関数のせいで、カプセル化が解除されてしまいます。
+
+この為に`arguments.callee`を使用または、そのプロパティを**決して**使用しない事を**強く推奨**します。
+
+> **ES5での注意:** strictモードでは、`arguments.callee`は推奨されていない為に
+> `Typeerror`が返るようになっています。
+
+[1]: http://en.wikipedia.org/wiki/Inlining
+
+