Merge pull request #271 from javascript-tutorial/sync-13da0566

Sync with upstream @ 13da056

Author: HachemiH

1-js/01-getting-started/1-intro/article.md

@@ -109,11 +109,19 @@ Les outils modernes rendent la [transpilation](https://fr.wiktionary.org/wiki/tr
 
 Les exemples de ce genre de langages :
 
+<<<<<<< HEAD
 - [CoffeeScript](http://coffeescript.org/) est un "sucre syntaxique" pour JavaScript, il introduit une syntaxe plus courte, permettant d’écrire du code plus précis et plus clair. Habituellement, les développeurs Ruby l'aiment bien.
 - [TypeScript](http://www.typescriptlang.org/) se concentre sur l'ajout de "typage strict des données" pour simplifier le développement et la prise en charge de systèmes complexes. Il est développé par Microsoft.
 - [Flow](http://flow.org/) ajoute également la saisie de données, mais de manière différente. Développé par Facebook.
 - [Dart](https://www.dartlang.org/) est un langage autonome doté de son propre moteur qui s'exécute dans des environnements autres que les navigateurs (comme les applications mobiles). Développé par Google.
 - [Brython](https://brython.info/) est un transpilateur Python vers JavaScript qui permet d'écrire des applications en Python pur sans JavaScript.
+=======
+- [CoffeeScript](http://coffeescript.org/) is a "syntactic sugar" for JavaScript. It introduces shorter syntax, allowing us to write clearer and more precise code. Usually, Ruby devs like it.
+- [TypeScript](http://www.typescriptlang.org/) is concentrated on adding "strict data typing" to simplify the development and support of complex systems. It is developed by Microsoft.
+- [Flow](http://flow.org/) also adds data typing, but in a different way. Developed by Facebook.
+- [Dart](https://www.dartlang.org/) is a standalone language that has its own engine that runs in non-browser environments (like mobile apps), but also can be transpiled to JavaScript. Developed by Google.
+- [Brython](https://brython.info/) is a Python transpiler to JavaScript that enables the writing of applications in pure Python without JavaScript.
+>>>>>>> 13da056653754765b50aa5a9f706f84a4a0d6293
 
 Il en existe évidemment bien plus, cela dit, même si nous utilisons un de ces langages, nous devrions également connaître le langage JavaScript, pour bien comprendre ce que nous faisons.
 

1-js/02-first-steps/04-variables/2-declare-variables/solution.md

@@ -6,7 +6,11 @@ C’est simple :
 let notrePlanete = "Terre";
 ```
 
+<<<<<<< HEAD
 Notez que nous pourrions utiliser un nom `planète` plus court, mais la planète à laquelle il fait référence pourrait ne pas être évidente. C’est bien d’être plus verbeux. Au moins jusqu'à ce que la variable n'estPasTropLongue.
+=======
+Note, we could use a shorter name `planet`, but it might not be obvious what planet it refers to. It's nice to be more verbose. At least until the variable isNotTooLong.
+>>>>>>> 13da056653754765b50aa5a9f706f84a4a0d6293
 
 ## le nom du visiteur actuel
 

1-js/02-first-steps/08-operators/article.md

@@ -105,7 +105,18 @@ Cependant, notez que les opérations se déroulent de gauche à droite. S'il y a
 alert(2 + 2 + '1' ); // "41" et non "221"
 ```
 
+<<<<<<< HEAD
 Ici, les opérateurs travaillent les uns après les autres. Le premier `+` additionne deux nombres, donc il renvoie `4`, puis le `+` suivant ajoute la chaîne `1`, donc c'est comme `4 + '1' = 41`.
+=======
+Here, operators work one after another. The first `+` sums two numbers, so it returns `4`, then the next `+` adds the string `1` to it, so it's like `4 + '1' = 41`.
+
+```js run
+alert('1' + 2 + 2); // "122" and not "14"
+```
+Here, the first operand is a string, the compiler treats the other two operands as strings too. The `2` gets concatenated to `'1'`, so it's like `'1' + 2 = "12"` and `"12" + 2 = "122"`.
+
+The binary `+` is the only operator that supports strings in such a way. Other arithmetic operators work only with numbers and always convert their operands to numbers.
+>>>>>>> 13da056653754765b50aa5a9f706f84a4a0d6293
 
 Le binaire `+` est le seul opérateur qui prend en charge les chaînes de cette manière. D'autres opérateurs arithmétiques ne fonctionnent qu'avec des nombres et convertissent toujours leurs opérandes en nombres.
 

1-js/02-first-steps/10-ifelse/article.md

@@ -68,7 +68,11 @@ if (cond) {
 
 ## La clause "else"
 
+<<<<<<< HEAD
 L'instruction `if` peut contenir un bloc optionnel `else`. Il s'exécute lorsque la condition est incorrecte.
+=======
+The `if` statement may contain an optional "else" block. It executes when the condition is falsy.
+>>>>>>> 13da056653754765b50aa5a9f706f84a4a0d6293
 
 Par exemple :
 ```js run

1-js/03-code-quality/06-polyfills/article.md

@@ -1,5 +1,5 @@
 
-# Polyfills
+# Polyfills and transpilers
 
 Le langage JavaScript évolue régulièrement. De nouvelles propositions pour le langage apparaissent régulièrement, elles sont analysées et, si elles sont jugées utiles, elles sont ajoutées à la liste dans <https://tc39.github.io/ecma262/> et ensuite progressent vers la [specification officielle](http://www.ecma-international.org/publications/standards/Ecma-262.htm).
 
@@ -9,8 +9,9 @@ Il est donc assez courant pour un moteur de ne mettre en œuvre qu'une partie de
 
 Une bonne page pour voir l’état actuel de la prise en charge des fonctionnalités du langage est <https://kangax.github.io/compat-table/es6/> (c’est énorme, nous avons encore beaucoup à étudier).
 
-## Babel
+As programmers, we'd like to use most recent features. The more good stuff - the better!
 
+<<<<<<< HEAD
 Lorsque nous utilisons des fonctionnalités modernes du langage, certains moteurs peuvent ne pas supporter un tel code. Comme indiqué, toutes les fonctionnalités ne sont pas implémentées partout.
 
 C'est là que Babel vient à la rescousse.
@@ -37,15 +38,53 @@ Nous devons donc configurer le transpileur et ajouter le polyfill pour les ancie
 Donc, si nous allons utiliser les fonctionnalités du langage moderne, un transpiler et un polyfill sont nécessaires.
 
 ## Exemples dans le tutoriel
+=======
+From the other hand, how to make out modern code work on older engines that don't understand recent features yet?
 
+There are two tools for that:
 
+1. Transpilers.
+2. Polyfills.
+
+Here, in this chapter, our purpose is to get the gist of how they work, and their place in web development.
+
+## Transpilers
+
+A [transpiler](https://en.wikipedia.org/wiki/Source-to-source_compiler) is a special piece of software that can parse ("read and understand") modern code, and rewrite it using older syntax constructs, so that the result would be the same.
+
+E.g. JavaScript before year 2020 didn't have the "nullish coalescing operator" `??`. So, if a visitor uses an outdated browser, it may fail to understand the code like `height = height ?? 100`.
+
+A transpiler would analyze our code and rewrite `height ?? 100` into `(height !== undefined && height !== null) ? height : 100`.
+
+```js
+// before running the transpiler
+height = height ?? 100;
+
+// after running the transpiler
+height = (height !== undefined && height !== null) ? height : 100;
+```
+
+Now the rewritten code is suitable for older JavaScript engines.
+>>>>>>> 13da056653754765b50aa5a9f706f84a4a0d6293
+
+Usually, a developer runs the transpiler on their own computer, and then deploys the transpiled code to the server.
+
+<<<<<<< HEAD
 ````online
 La plupart des exemples sont exécutables sur place, comme ceci :
+=======
+Speaking of names, [Babel](https://babeljs.io) is one of the most prominent transpilers out there. 
+>>>>>>> 13da056653754765b50aa5a9f706f84a4a0d6293
 
-```js run
-alert('Press the "Play" button in the upper-right corner to run');
-```
+Modern project build systems, such as [webpack](http://webpack.github.io/), provide means to run transpiler automatically on every code change, so it's very easy to integrate into development process.
+
+## Polyfills
+
+New language features may include not only syntax constructs and operators, but also built-in functions.
+
+For example, `Math.trunc(n)` is a function that "cuts off" the decimal part of a number, e.g `Math.trunc(1.23) = 1`.
 
+<<<<<<< HEAD
 Les exemples qui utilisent le JS moderne ne fonctionneront que si votre navigateur le prend en charge.
 ````
 
@@ -55,4 +94,45 @@ Pendant que vous lisez la version hors connexion, les exemples ne sont pas exéc
 
 Google Chrome est généralement la version la plus récente des fonctionnalités du langage, il accepte de lancer des démos ultra-sophistiquées sans transpilers, mais les autres navigateurs modernes fonctionnent également très bien.
 
+=======
+In some (very outdated) JavaScript engines, there's no `Math.trunc`, so such code will fail.
+
+As we're talking about new functions, not syntax changes, there's no need to transpile anything here. We just need to declare the missing function.
+
+A script that updates/adds new functions is called "polyfill". It "fills in" the gap and adds missing implementations.
+
+For this particular case, the polyfill for `Math.trunc` is a script that implements it, like this:
+
+```js
+if (!Math.trunc) { // if no such function
+  // implement it
+  Math.trunc = function(number) {
+    // Math.ceil and Math.floor exist even in ancient JavaScript engines
+    // they are covered later in the tutorial
+    return number < 0 ? Math.ceil(number) : Math.floor(number);
+  };
+}
+```
+
+JavaScript is a highly dynamic language, scripts may add/modify any functions, even including built-in ones. 
+
+Two interesting libraries of polyfills are:
+- [core js](https://github.com/zloirock/core-js) that supports a lot, allows to include only needed features.
+- [polyfill.io](http://polyfill.io) service that provides a script with polyfills, depending on the features and user's browser.
+
+
+## Summary
+
+In this chapter we'd like to motivate you to study modern and even "bleeding-edge" language features, even if they aren't yet well-supported by JavaScript engines.
+
+Just don't forget to use transpiler (if using modern syntax or operators) and polyfills (to add functions that may be missing). And they'll ensure that the code works.
+
+For example, later when you're familiar with JavaScript, you can setup a code build system based on [webpack](http://webpack.github.io/) with [babel-loader](https://github.com/babel/babel-loader) plugin.
+
+Good resources that show the current state of support for various features:
+- <https://kangax.github.io/compat-table/es6/> - for pure JavaScript.
+- <https://caniuse.com/> - for browser-related functions.
+
+P.S. Google Chrome is usually the most up-to-date with language features, try it if a tutorial demo fails. Most tutorial demos work with any modern browser though.
+>>>>>>> 13da056653754765b50aa5a9f706f84a4a0d6293
 

1-js/04-object-basics/02-object-copy/article.md

@@ -1,8 +1,14 @@
 # Les références d'objet et leur copie
 
+<<<<<<< HEAD
 Une des différences fondamentale des objets avec les primitives est que ceux-ci sont stockés et copiés "par référence", en opposition des valeurs primitives : strings, numbers, booleans, etc. -- qui sont toujours copiés comme "valeur entière".
 
 On comprendra plus facilement en regardant "sous le capot" le fonctionnement de la copie d'une valeur.
+=======
+One of the fundamental differences of objects versus primitives is that objects are stored and copied "by reference", whereas primitive values: strings, numbers, booleans, etc -- are always copied "as a whole value".
+
+That's easy to understand if we look a bit under the hood of what happens when we copy a value.
+>>>>>>> 13da056653754765b50aa5a9f706f84a4a0d6293
 
 Commençons avec une primitive, comme une chaîne de caractères.
 
@@ -13,17 +19,27 @@ let message = "Hello!";
 let phrase = message;
 ```
 
+<<<<<<< HEAD
 Il en résulte deux variables indépendantes, chacune stockant la chaîne de caractères `"Hello!"`.
+=======
+As a result we have two independent variables, each one storing the string `"Hello!"`.
+>>>>>>> 13da056653754765b50aa5a9f706f84a4a0d6293
 
 ![](variable-copy-value.svg)
 
 Un résultat plutôt évident n'est-ce pas ?
 
 Les objets ne fonctionnent pas comme cela.
 
+<<<<<<< HEAD
 **Une variable assignée à un objet ne stocke pas l'objet lui-même, mais son "adresse mémoire", en d'autres termes "une référence" à celui-ci.**
 
 Prenons un exemple d'une telle variable :
+=======
+**A variable assigned to an object stores not the object itself, but its "address in memory" -- in other words "a reference" to it.**
+
+Let's look at an example of such a variable:
+>>>>>>> 13da056653754765b50aa5a9f706f84a4a0d6293
 
 ```js
 let user = {
@@ -37,13 +53,23 @@ Et ici comment elle est stockée en mémmoire :
 
 L'objet est stocké quelque part dans la mémoire (du coté droit de l'image), tandis que la varaible `user` (du coté gauche) a une référence à celui-ci.
 
+<<<<<<< HEAD
 On peut voir la variable d'objet, ici `user`, comme une feuille de papier avec l'adresse.
 
 Lorque l'on réalise une action avec l'objet, par exemple récupérer la propriété `user.name`, le moteur de Javascript regarde à l'adresse et réalise l'opération sur l'objet.
+=======
+We may think of an object variable, such as `user`, as like a sheet of paper with the address of the object on it.
+
+When we perform actions with the object, e.g. take a property `user.name`, the JavaScript engine looks at what's at that address and performs the operation on the actual object.
+>>>>>>> 13da056653754765b50aa5a9f706f84a4a0d6293
 
 Et voilà pourquoi cela est important.
 
+<<<<<<< HEAD
 **Lorsqu'une la variable d'objet est copiée -- la référence est copiée, l'objet n'est pas dupliqué.**
+=======
+**When an object variable is copied, the reference is copied, but the object itself is not duplicated.**
+>>>>>>> 13da056653754765b50aa5a9f706f84a4a0d6293
 
 Par exemple:
 
@@ -53,13 +79,23 @@ let user = { name: "John" };
 let admin = user; // copie la référence
 ```
 
+<<<<<<< HEAD
 Maintenant nous avons deux variables, chacune avec la référence vers le même objet :
 
 ![](variable-copy-reference.svg)
 
 Comme vous pouvez le voir, il y a toujours qu'un seul objet, avec deux variables qui le référence.
 
 On peut utiliser n'importe quelle variable pour accéder à l'objet et modifier le contenu :
+=======
+Now we have two variables, each storing a reference to the same object:
+
+![](variable-copy-reference.svg)
+
+As you can see, there's still one object, but now with two variables that reference it.
+
+We can use either variable to access the object and modify its contents:
+>>>>>>> 13da056653754765b50aa5a9f706f84a4a0d6293
 
 ```js run
 let user = { name: 'John' };
@@ -73,7 +109,11 @@ admin.name = 'Pete'; // changé par la référence "admin"
 alert(*!*user.name*/!*); // 'Pete', les changements sont visibles sur la référence "user"
 ```
 
+<<<<<<< HEAD
 C'est comme si l'on avait un cabinet avec deux clés et que on l'on utilisait l'une d'elles (`admin`) pour y accéder. Puis, si l'on utilise plus tard la clé (`user`) on peut voir les changements.
+=======
+It's as if we had a cabinet with two keys and used one of them (`admin`) to get into it and make changes. Then, if we later use another key (`user`), we are still opening the same cabinet and can access the changed contents.
+>>>>>>> 13da056653754765b50aa5a9f706f84a4a0d6293
 
 ## Comparaison par référence
 
@@ -98,15 +138,23 @@ let b = {}; // 2 objets indépendants
 alert( a == b ); // false
 ```
 
+<<<<<<< HEAD
 Pour des comparaisons comme `obj1 > obj2` ou des comparaisons avec une primitive `obj == 5`, les objets sont convertis en primitive. Nous étudierons comment les conversions d'objets fonctionnent bientôt, mais pour dire la vérité, de telles comparaisons sont rarement nécessaires, en général elles sont le résultat d'une erreur de programmation.
+=======
+For comparisons like `obj1 > obj2` or for a comparison against a primitive `obj == 5`, objects are converted to primitives. We'll study how object conversions work very soon, but to tell the truth, such comparisons are needed very rarely -- usually they appear as a result of a programming mistake.
+>>>>>>> 13da056653754765b50aa5a9f706f84a4a0d6293
 
 ## Clonage et fusionage, Object.assign
 
 Copier une variable object créé une référence en plus vers le même objet.
 
 Mais quid si nous voulons dupliquer un objet ? Créer une copie indépendante, un clone ?
 
+<<<<<<< HEAD
 C'est aussi faisable, mais un peu plus compliqué, car en Javascript il n'y pas de méthode intégrée pour cela. En fait c'est rarement utile. Copier par référence fonctionne la plupart du temps.
+=======
+That's also doable, but a little bit more difficult, because there's no built-in method for that in JavaScript. But there is rarely a need -- copying by reference is good most of the time.
+>>>>>>> 13da056653754765b50aa5a9f706f84a4a0d6293
 
 Mais si nous le voulons, alors nous devons créer un nouvel objet et répliquer sa structure en itérant ses propriétés et en les copiant au niveau primitive.
 
@@ -226,12 +274,21 @@ user.sizes.width++;       // on modifie la propriété à un endroit
 alert(clone.sizes.width); // 51, on peut voir la modification dans un autre endroit
 ```
 
+<<<<<<< HEAD
 Pour régler ça, on doit utiliser la boucle de clonage qui examine chaque valeur de `user[key]` et, si c'est un objet, répliquer sa structure aussi. On appelle cela un "clone réél" (deep clone).
 
 On peut utiliser la récursion pour l'implémenter. Ou, pour ne pas réinventer la roue, prendre un implémentation existante. par exemple [_.cloneDeep(obj)](https://lodash.com/docs#cloneDeep) de la librairie [lodash](https://lodash.com).
 
 ```smart header="Les objets Const peuvent être modifiés"
 Un "effet secondaire" important du stockage d'objets en tant que références est qu'un objet déclaré comme `const` *peut* être modifié.
+=======
+To fix that, we should use a cloning loop that examines each value of `user[key]` and, if it's an object, then replicate its structure as well. That is called a "deep cloning".
+
+We can use recursion to implement it. Or, to not reinvent the wheel, take an existing implementation, for instance [_.cloneDeep(obj)](https://lodash.com/docs#cloneDeep) from the JavaScript library [lodash](https://lodash.com).
+
+````smart header="Const objects can be modified"
+An important side effect of storing objects as references is that an object declared as `const` *can* be modified.
+>>>>>>> 13da056653754765b50aa5a9f706f84a4a0d6293
 
 Par exemple :
 
@@ -247,16 +304,29 @@ user.name = "Pete"; // (*)
 alert(user.name); // Pete
 ```
 
+<<<<<<< HEAD
 Il peut sembler que la ligne `(*)` provoquerait une erreur, mais non. La valeur de `user` est constante, elle doit toujours référencer le même objet. Mais les propriétés de cet objet sont libres de changer.
 
 En d'autres termes, le `const user` ne donne une erreur que si nous essayons de définir `user = ...` dans son ensemble, et c'est tout.
 
 Cela dit, si nous avons vraiment besoin de créer des propriétés d'objet constantes, c'est également possible, mais en utilisant des méthodes totalement différentes, nous le mentionnerons dans le chapitre <info:property-descriptors>.
 ```
+=======
+It might seem that the line `(*)` would cause an error, but it does not. The value of `user` is constant, it must always reference the same object, but properties of that object are free to change.
+
+In other words, the `const user` gives an error only if we try to set `user=...` as a whole.
+
+That said, if we really need to make constant object properties, it's also possible, but using totally different methods. We'll mention that in the chapter <info:property-descriptors>.
+````
+>>>>>>> 13da056653754765b50aa5a9f706f84a4a0d6293
 
 ## Résumé
 
+<<<<<<< HEAD
 Les objets sont assignés et copiés par référence. En d'autres mots, une variable ne stocke pas la "valeur de l'objet" mais la "référence" (l'adresse en mémoire) de la valeur. Donc copier cette variable, ou la passer en argument d'une fonction, copie la référence, pas l'objet.
+=======
+Objects are assigned and copied by reference. In other words, a variable stores not the "object value", but a "reference" (address in memory) for the value. So copying such a variable or passing it as a function argument copies that reference, not the object itself.
+>>>>>>> 13da056653754765b50aa5a9f706f84a4a0d6293
 
 Toutes les opérations faites par une copie de la référence (comme ajouter/supprimer une propriété) sont faites sur le même objet.