Merge branch 'master' of https://github.com/sanshi/JavaScript-Garden into zh-translation

Conflicts:
	doc/language.json

Author: ZhangYiJiang

README.md

@@ -1,33 +1,36 @@
-JavaScript Garden
+JavaScript 秘密花园
 =================
 
-**JavaScript Garden** is a growing collection of documentation about the most 
-quirky parts of the JavaScript programming language. It gives advice to 
-avoid common mistakes, subtle bugs, as well as performance issues and bad 
-practices that non-expert JavaScript programmers may encounter on their 
-endeavours into the depths of the language.
+**JavaScript 秘密花园**是一个不断更新的文档，主要关心 JavaScript 一些古怪用法。
+对于如何避免常见的错误，难以发现的问题，以及性能问题和不好的实践给出建议，
+初学者可以籍此深入了解 JavaScript 的语言特性。
 
-JavaScript Garden does **not** aim to teach you JavaScript. Former knowledge
-of the language is strongly recommended in order to understand the topics covered
-in this guide. In order to learn the basics of the language, please head over to 
-the excellent [guide][1] on the Mozilla Developer Network.
+JavaScript 秘密花园**不是**用来教你 JavaScript。为了更好的理解这篇文章的内容，
+你需要事先学习 JavaScript 的基础知识。在 Mozilla 开发者网络中有一系列非常棒的 JavaScript 学习[向导][1]。
 
-### The authors
+### 关于作者
 
-This guide is the work of two lovely Stack Overflow users, [Ivo Wetzel][6]
-(Writing) and [Zhang Yi Jiang][5] (Design).
+这篇文章的作者是两位 Stack Overflow 的用户, [Ivo Wetzel][6] （写作） 和 [Zhang Yi Jiang][5] （设计）。
 
-### Contributors
 
- - [Caio Romão][8] (Spelling corrections)
- - [Andreas Blixt][9] (Language corrections)
+### 贡献者
 
-### License
+ - [Caio Romão][8] （拼写检查）
+ - [Andreas Blixt][9] （语言修正）
+
+### 中文翻译
+
+ - [三生石上][29]
+
+此中文翻译由[三生石上][29]独立完成，[博客园][30]首发，转载请注明出处。
+ 
+
+### 许可
+
+JavaScript 秘密花园在 [MIT license][2] 许可协议下发布，并存放在开源社区 [GitHub][4]。
+如果你发现错误或者打字错误，请 [file an issue][3] 或者 pull request。
+你也可以在 Stack Overflow 的聊天室 [JavaScript room][10] 找到我们。
 
-JavaScript Garden is published under the [MIT license][2] and hosted on
-[GitHub][4]. If you find errors or typos please [file an issue][3] or a pull 
-request on the repository. You can also find us in the [JavaScript room][10] on
-Stack Overflow chat. 
 
 [1]: https://developer.mozilla.org/en/JavaScript/Guide
 [2]: https://github.com/BonsaiDen/JavaScript-Garden/blob/next/LICENSE
@@ -39,3 +42,6 @@ Stack Overflow chat.
 [9]: https://github.com/blixt
 [10]: http://chat.stackoverflow.com/rooms/17/javascript
 
+[29]: http://sanshi.me/
+[30]: http://cnblogs.com/sanshi/
+

doc/language.json

@@ -1,5 +1,5 @@
 {
     "default": "en",
-    "listed": ["en", "ru"]
+    "listed": ["en", "ru", "zh"]
 }
 

doc/zh/array/constructor.md

@@ -0,0 +1,38 @@
+## `Array` 构造函数
+
+由于 `Array` 的构造函数在如何处理参数时有点模棱两可，因此总是推荐使用数组的字面语法 - `[]` - 来创建数组。
+
+    [1, 2, 3]; // 结果: [1, 2, 3]
+    new Array(1, 2, 3); // 结果: [1, 2, 3]
+
+    [3]; // 结果: [3]
+    new Array(3); // 结果: [] 
+    new Array('3') // 结果: ['3']
+
+译者注：这里的模棱两可指的是数组的[两种构造函数语法][1]
+var arr1 = new Array(arrayLength);
+var arr2 = new Array(element0, element1, ..., elementN);
+	
+	// 译者注：因此下面的代码将会使人很迷惑
+	new Array(3, 4, 5); // 结果: [3, 4, 5] 
+    new Array(3) // 结果: []，此数组长度为 3
+	
+由于只有一个参数传递到构造函数中（译者注：指的是 `new Array(3);` 这种调用方式），并且这个参数是数字，构造函数会返回一个 `length` 属性被设置为此参数的空数组。
+需要特别注意的是，此时只有 `length` 属性被设置，真正的数组并没有生成。
+译者注：在 Firebug 中，你会看到 [undefined, undefined, undefined]，这其实是不对的。在上一节有详细的分析。
+
+    var arr = new Array(3);
+    arr[1]; // undefined
+    1 in arr; // false, 数组还没有生成
+
+这种优先于设置数组长度属性的做法只在少数几种情况下有用，比如需要循环字符串，可以避免 `for` 循环的麻烦。
+
+    new Array(count + 1).join(stringToRepeat);
+	// 译者注：new Array(3).join('#') 将会返回 "##"
+
+### 结论（In conclusion）
+
+应该尽量避免使用数组构造函数创建新数组。推荐使用数组的字面语法。它们更加短小和简洁，因此增加了代码的可读性。
+
+[1]: https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Array
+

doc/zh/array/general.md

@@ -0,0 +1,57 @@
+## 数组遍历与属性
+
+虽然在 JavaScript 中数组是是对象，但是没有好的理由去使用 [`for in` 循环](#object.forinloop) 遍历数组。
+相反，有一些好的理由**不去**使用 `for in` 遍历数组。
+
+> **注意:** JavaScript 中数组**不是** *关联数组*。
+> JavaScript 中只有[对象](#object.general) 来管理键值的对应关系。但是关联数组是**保持**顺序的，而对象**不是**。
+
+由于 `for in` 循环会枚举原型链上的所有属性，唯一过滤这些属性的方式是使用 [`hasOwnProperty`](#object.hasownproperty) 函数，
+因此会比普通的 `for` 循环慢上好多倍。
+
+### 遍历（Iteration）
+
+为了达到遍历数组的最佳性能，推荐使用经典的 `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` 属性（The `length` property）
+
+`length` 属性的 *getter* 方式会简单的返回数组的长度，而 *setter* 方式会**截断**数组。
+
+    var foo = [1, 2, 3, 4, 5, 6];
+    foo.length = 3;
+    foo; // [1, 2, 3]
+
+    foo.length = 6;
+    foo; // [1, 2, 3]
+
+译者注：
+在 Firebug 中查看此时 foo 的值是： [1, 2, 3, undefined, undefined, undefined]
+但是这个结果并不准确，如果你在 Chrome 的控制台查看 foo 的结果，你会发现是这样的： [1, 2, 3]
+因为在 JavaScript 中 undefined 是一个变量，注意是变量不是关键字，因此上面两个结果的意义是完全不相同的。
+
+	// 译者注：为了验证，我们来执行下面代码，看序号 5 是否存在于 foo 中。
+	5 in foo; // 不管在 Firebug 或者 Chrome 都返回 false
+	foo[5] = undefined;
+	5 in foo; // 不管在 Firebug 或者 Chrome 都返回 true
+
+	
+为 `length` 设置一个更小的值会截断数组，但是增大 `length` 属性值不会对数组产生影响。
+
+### 结论（In conclusion）
+
+为了更好的性能，推荐使用普通的 `for` 循环并缓存数组的 `length` 属性。
+使用 `for in` 遍历数组被认为是不好的代码习惯并倾向于产生错误和导致性能问题。
+

doc/zh/core/eval.md

@@ -0,0 +1,68 @@
+## 为什么不要使用 `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
+
+[译者注][30]：上面的代码等价于在全局作用域中调用 `eval`，和下面两种写法效果一样：
+
+	// 写法一：直接调用全局作用域下的 foo 变量
+	var foo = 1;
+    function test() {
+        var foo = 2;
+        window.foo = 3;
+        return foo;
+    }
+    test(); // 2
+    foo; // 3
+	
+	// 写法二：使用 call 函数修改 `eval` 执行的上下文为全局作用域
+	var foo = 1;
+    function test() {
+        var foo = 2;
+        eval.call(window, 'foo = 3');
+        return foo;
+    }
+    test(); // 2
+    foo; // 3
+
+在**任何情况下**我们都应该避免使用 `eval` 函数。99.9% 使用 `eval` 的场景都有**不使用** `eval` 的解决方案。
+    
+### 伪装的 `eval`（`eval` in disguise）
+
+[定时函数](#other.timeouts) `setTimeout` 和 `setInterval` 都可以接受字符串作为它们的第一个参数。
+这个字符串**总是**在全局作用域中执行，因此 `eval` 在这种情况下没有被直接调用。
+
+
+### 安全问题（Security issues）
+
+`eval` 也存在安全问题，因为它会执行**任意**传给它的代码，
+在代码字符串未知或者是来自一个不信任的源时，绝对不要使用 `eval` 函数。
+
+### 结论（In conclusion）
+
+绝对不要使用 `eval`，任何使用它的代码都会在它的工作方式，性能和安全性方面受到质疑。
+如果一些情况必须使用到 `eval` 才能正常工作，首先它的设计会受到质疑，这**不应该**是首选的解决方案，
+一个更好的不使用 `eval` 的解决方案应该得到充分考虑并优先采用。
+
+
+[30]: http://cnblogs.com/sanshi/

doc/zh/core/semicolon.md

@@ -0,0 +1,109 @@
+## 自动分号插入
+
+尽管 JavaScript 有 C 的代码风格，但是它**不**强制要求在代码中使用分号，实际上可以省略它们。
+
+JavaScript 不是一个没有分号的语言，恰恰相反上它需要分号来就解析源代码。
+因此 JavaScript 解析器在遇到由于缺少分号导致的解析错误时，会**自动**在源代码中插入分号。
+
+    var foo = function() {
+    } // 解析错误，分号丢失
+    test()
+
+自动插入分号，解析器重新解析。
+
+    var foo = function() {
+    }; // 没有错误，解析继续
+    test()
+
+自动的分号插入被认为是 JavaScript 语言**最大**的设计缺陷之一，因为它*能*改变代码的行为。
+
+
+### 工作原理（How it works）
+
+下面的代码没有分号，因此解析器需要自己判断需要在哪些地方插入分号。
+
+
+    (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) {
+
+            // Not inserted, lines got merged
+            log('testing!')(options.list || []).forEach(function(i) {
+
+            }); // <- 插入分号
+
+            options.value.test(
+                'long string to pass here',
+                'and another long string to pass'
+            ); // <- 插入分号
+
+            return; // <- 插入分号, 改变了 return 表达式的行为
+            { // 作为一个代码段处理
+
+                // a label and a single expression statement
+                foo: function() {} 
+            }; // <- 插入分号
+        }
+        window.test = test; // <- 插入分号
+
+    // The lines got merged again
+    })(window)(function(window) {
+        window.someLibrary = {}; // <- 插入分号
+
+    })(window); //<- 插入分号
+
+> **注意:** JavaScript 不能正确的处理 return 表达式紧跟换行符的情况，
+> 虽然这不能算是自动分号插入的错误，但这确实是一种不希望的副作用。
+
+
+解析器显著改变了上面代码的行为，在另外一些情况下也会做出**错误的处理**。
+
+
+### 前置括号（Leading parenthesis）
+
+在前置括号的情况下，解析器**不会**自动插入分号。
+
+    log('testing!')
+    (options.list || []).forEach(function(i) {})
+
+上面代码被解析器转换为一行。
+
+    log('testing!')(options.list || []).forEach(function(i) {})
+
+`log` 函数的执行结果**极大**可能**不是**函数；这种情况下就会出现 `TypeError` 的错误，详细错误信息可能是 `undefined is not a function`。
+
+
+### 结论（In conclusion）
+
+建议**绝对**不要省略分号，同时也提倡将花括号和相应的表达式放在一行，
+对于只有一行代码的 `if` 或者 `else` 表达式，也不应该省略花括号。
+这些良好的编程习惯不仅可以提到代码的一致性，而且可以防止解析器改变代码行为的错误处理。
+