Merge pull request BonsaiDen#118 from julionc/master

[es] Spanish translation

Author: BonsaiDen

.gitignore

@@ -12,5 +12,6 @@
 /site/tr
 /site/ko
 /site/ja
+/site/es
 *.md~
 *.src.md

doc/es/array/constructor.md

@@ -0,0 +1,35 @@
+## El constructor `Array`
+
+Desde el constructor `Array` es ambiguo en la forma en que ocupa sus párametros,
+es recomendable siempre el uso de arrays literales - la notación `[]` - 
+cuando se crean nuevos arrays.
+
+    [1, 2, 3]; // Resultado: [1, 2, 3]
+    new Array(1, 2, 3); // Resultado: [1, 2, 3]
+
+    [3]; // Resultado: [3]
+    new Array(3); // Resultado: []
+    new Array('3') // Resultado: ['3']
+
+En casos cuando sólo hay un argumento pasado al constructor del `Array`,
+y que el argumento es un `Número`, el contructor devolverá un array *disperso* 
+con la propiedad `length` establecida al valor del argumento. Esto debe señalarse
+que la propiedad `length` **sólo** del nuevo array se establecerá de esa manera, 
+los índices reales de la matriz no se iniciará. 
+
+    var arr = new Array(3);
+    arr[1]; // undefined
+    1 in arr; // falso, el índice no se ha establecido
+
+El comportamiento de poder establecer la longitud de un array inicial sólo es útil
+en algunos casos array, como la repetición de una cadena, en la que se evita el uso 
+del código de `bucle for`.
+
+    new Array(count + 1).join(stringToRepeat);
+
+### En conclusión
+
+El uso de un constructor `Array` debe ser devuelto como sea posible. 
+Los literales son definitivamente preferidos. Estos son más cortos y tienen una
+sintaxis más limpia; por lo tanto, también se incrementa la legibilidad del código.
+

doc/es/array/general.md

@@ -0,0 +1,58 @@
+## Iteración de un Array y sus propiedades
+
+A pesar que los arrays en JavaScript son objetos, no existe un buena razón para
+usarlo en un [`bucle for`](#object.forinloop) para una interación de este. De 
+hecho, hay un número de buenas razones **contra** el uso de `for in` en arrays.
+
+> **Nota:** Los arrays de JavaScript **no** son *arrays asociativos*. JavaScript sólo 
+> tiene [objetos](#object.general) para el mapeo de keys a valores. Y mientras
+> que los arrays asociativos **preservan** el orden, los objetos **no**.
+
+Dado que el bucle `for in` enumera todas las propiedades que están en una cadena
+de prototipo y la única manera para excluir estas propiedades es el uso de
+[`hasOwnProperty`](#object.hasownproperty), ya que es **veinte veces** más
+lento que un bucle `for` normal.
+
+### Iteración
+
+Con el fin de obtener el mejor rendimiento cuando se repite la interación de arrays, 
+es lo mejor hacer uso del clásico bucle `for`.
+
+    var list = [1, 2, 3, 4, 5, ...... 100000000];
+    for(var i = 0, l = list.length; i < l; i++) {
+        console.log(list[i]);
+    }
+
+Hay una captura adicional en el ejemplo anterior, que es el almacenamiento de la
+caché de longitud del array vía `l = list.length`.
+
+Aunque la propiedad `length` es definida en el mismo array, todavía posee una sobrecarga
+para realizar la búsqueda en cada interación del bucle. Y mientras que los últimos 
+motores de JavaScript **pueden** aplicar optimizaciones en este caso, no hay manera 
+de saber si el ćodigo se ejecutará en uno de estos nuevos motores nuevos o no.
+
+De hecho, dejando de lado el alamacenamiento en caché puede resultar que el bucle
+inicie sólo la **mitad de rápido** que con la longitud de la caché.
+
+### La propiedad `length`
+
+Mientras que *getter* de la propiedad `length` simplemente retorne el número de
+elementos son contenidos en un array, el *setter* puede ser usado para 
+**truncar** el array.
+
+    var foo = [1, 2, 3, 4, 5, 6];
+    foo.length = 3;
+    foo; // [1, 2, 3]
+
+    foo.length = 6;
+    foo; // [1, 2, 3]
+
+La asignación de un menor número de longitud trunca al array, pero incrementando la
+longitud no tiene ningún efecto sobre el array.
+
+### En conclusión
+
+Para obtener el mejor rendimiento es recomendable siempre usar el bucle `for`
+y alamacenar en caché la propiedad `length`. El uso del bucle `for in` en un array 
+es señal de un código mal escrito propenso a errores y un mal desempeño. 
+

doc/es/core/delete.md

@@ -0,0 +1,87 @@
+## The `delete` Operator
+
+In short, it's *impossible* to delete global variables, functions and some other
+stuff in JavaScript which have a `DontDelete` attribute set.
+
+### Global code and Function code
+
+When a variable or a function is defined in a global 
+or a [function scope](#function.scopes) it is a property of either 
+Activation object or Global object. Such properties have a set of attributes, 
+one of these is `DontDelete`. Variable and function declarations in global 
+and function code always create properties with `DontDelete`, therefore 
+cannot be deleted.
+
+    // global variable:
+    var a = 1; // DontDelete is set
+    delete a; // false
+    a; // 1
+
+    // normal function:
+    function f() {} // DontDelete is set
+    delete f; // false
+    typeof f; // "function"
+
+    // reassigning doesn't help:
+    f = 1;
+    delete f; // false
+    f; // 1
+
+### Explicit properties
+
+There are things which can be deleted normally: these are explicitly set 
+properties.
+
+    // explicitly set property:
+    var obj = {x: 1};
+    obj.y = 2;
+    delete obj.x; // true
+    delete obj.y; // true
+    obj.x; // undefined
+    obj.y; // undefined
+
+In the example above `obj.x` and `obj.y` can be deleted because they have no 
+`DontDelete` atribute. That's why an example below works too.
+
+    // this works fine, except for IE:
+    var GLOBAL_OBJECT = this;
+    GLOBAL_OBJECT.a = 1;
+    a === GLOBAL_OBJECT.a; // true - just a global var
+    delete GLOBAL_OBJECT.a; // true
+    GLOBAL_OBJECT.a; // undefined
+
+Here we use a trick to delete `a`. [`this`](#function.this) here refers 
+to the Global object and we explicitly declare variable `a` as it's property 
+which allows us to delete it.
+
+IE (at least 6-8) has some bugs, so code above doesn't work.
+
+### Function arguments and built-ins
+
+Functions' normal arguments, [`arguments` object](#function.arguments) 
+and built-in properties also have `DontDelete` set.
+
+    // function arguments and properties:
+    (function (x) {
+    
+      delete arguments; // false
+      typeof arguments; // "object"
+      
+      delete x; // false
+      x; // 1
+      
+      function f(){}
+      delete f.length; // false
+      typeof f.length; // "number"
+      
+    })(1);
+
+### Host objects
+    
+Behaviour of `delete` operator can be unpredictable for hosted objects. Due to 
+specification, host objects are allowed to implement any kind of behavior. 
+
+### In conclusion
+
+`delete` operator often has an unexpected behaviour and can be safely used 
+only for dealing with explicitly set properties on normal objects.

doc/es/core/eval.md

@@ -0,0 +1,47 @@
+## ¿Por qué no usar `eval`?
+
+La función `eval` ejecuta un string como código JavaScript en el ámbito local.
+
+    var foo = 1;
+    function test() {
+        var foo = 2;
+        eval('foo = 3');
+        return foo;
+    }
+    test(); // 3
+    foo; // 1
+
+Pero `eval` sólo ejecutará en ámbito local cuando es llamado **directamente** *y* 
+el nombre de la función llamada es `eval`.
+
+    var foo = 1;
+    function test() {
+        var foo = 2;
+        var bar = eval;
+        bar('foo = 3');
+        return foo;
+    }
+    test(); // 2
+    foo; // 3
+
+El uso de `eval` debe evitarse **a toda costa**. El 99.9% de su "uso" puede 
+lograrse **sin** su uso..
+    
+### `eval` disfrazado
+
+Las funciones de [tiempo de espera](#other.timeouts) `setTimeout` y `setInterval` pueden
+tomar un string como primer argumento. En este caso, el string **siempre** se ejecutará en
+el ámbito global ya que `eval` no ha sido llamado directamente.
+
+### Problemas de seguridad
+
+`eval` es también un problema de seguridad ya que ejecuta **cualquier** código enviado,
+y **nunca** debe usarse con strings que no se conozcan o tengan un origen no confiable.
+
+### En conclusión
+
+`eval` nunca debe ser usado, cualquier código que haga uso del mismo debe ser cuestionado
+en su funcionamiento, rendimiento y seguridad. En caso de que se necesite trabajar con
+`eval`, el diseño ha de ser cuestionado y **no** debe  utilizarse en primer lugar, se
+debe usar un *mejor diseño*, que no requiera el uso de `eval`. 
+

doc/es/core/semicolon.md

@@ -0,0 +1,114 @@
+## Automatic Semicolon Insertion
+
+Although JavaScript has C style syntax, it does **not** enforce the use of
+semicolons in the source code, so it is possible to omit them.
+
+JavaScript is not a semicolon-less language. In fact, it needs the 
+semicolons in order to understand the source code. Therefore, the JavaScript
+parser **automatically** inserts them whenever it encounters a parse
+error due to a missing semicolon.
+
+    var foo = function() {
+    } // parse error, semicolon expected
+    test()
+
+Insertion happens, and the parser tries again.
+
+    var foo = function() {
+    }; // no error, parser continues
+    test()
+
+The automatic insertion of semicolon is considered to be one of **biggest**
+design flaws in the language because it *can* change the behavior of code.
+
+### How it Works
+
+The code below has no semicolons in it, so it is up to the parser to decide where
+to insert them.
+
+    (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)
+
+Below is the result of the parser's "guessing" game.
+
+    (function(window, undefined) {
+        function test(options) {
+
+            // Not inserted, lines got merged
+            log('testing!')(options.list || []).forEach(function(i) {
+
+            }); // <- inserted
+
+            options.value.test(
+                'long string to pass here',
+                'and another long string to pass'
+            ); // <- inserted
+
+            return; // <- inserted, breaks the return statement
+            { // treated as a block
+
+                // a label and a single expression statement
+                foo: function() {} 
+            }; // <- inserted
+        }
+        window.test = test; // <- inserted
+
+    // The lines got merged again
+    })(window)(function(window) {
+        window.someLibrary = {}; // <- inserted
+
+    })(window); //<- inserted
+
+> **Note:** The JavaScript parser does not "correctly" handle return statements 
+> which are followed by a new line, while this is not neccessarily the fault of 
+> the automatic semicolon insertion, it can still be an unwanted side-effect. 
+
+The parser drastically changed the behavior of the code above. In certain cases,
+it does the **wrong thing**.
+
+### Leading Parenthesis
+
+In case of a leading parenthesis, the parser will **not** insert a semicolon.
+
+    log('testing!')
+    (options.list || []).forEach(function(i) {})
+
+This code gets transformed into one line.
+
+    log('testing!')(options.list || []).forEach(function(i) {})
+
+Chances are **very** high that `log` does **not** return a function; therefore,
+the above will yield a `TypeError` stating that `undefined is not a function`.
+
+### In Conclusion
+
+It is highly recommended to **never** omit semicolons; it is also advocated to 
+keep braces on the same line with their corresponding statements and to never omit 
+them for one single-line `if` / `else` statements. Both of these measures will 
+not only improve the consistency of the code, but they will also prevent the 
+JavaScript parser from changing its behavior.
+