Sync with upstream @ 7bb6066e

.gitignore

@@ -21,3 +21,4 @@ sftp-config.json
 Thumbs.db
 
 
+/svgs

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

@@ -29,9 +29,17 @@
 
 من الجيد تذكر المصطلحات الواردة أعلاه لأنها مستخدمة في مقالات المطورين على الإنترنت. سنستخدمهم أيضًا. على سبيل المثال ، إذا كانت "الميزة إكس مدعومة بواسطة في8" ، فمن المحتمل أنها تعمل في كروم و أوبرا.
 
+<<<<<<< HEAD
 ```smart header="كيف تعمل المحركات؟"
 
 المحركات معقدة. ولكن الأساسيات بسيطه .
+=======
+- [V8](https://en.wikipedia.org/wiki/V8_(JavaScript_engine)) -- in Chrome, Opera and Edge.
+- [SpiderMonkey](https://en.wikipedia.org/wiki/SpiderMonkey) -- in Firefox.
+- ...There are other codenames like "Chakra" for IE, "JavaScriptCore", "Nitro" and "SquirrelFish" for Safari, etc.
+
+The terms above are good to remember because they are used in developer articles on the internet. We'll use them too. For instance, if "a feature X is supported by V8", then it probably works in Chrome, Opera and Edge.
+>>>>>>> 7bb6066eb6ea3a030b875cdc75433c458f80997e
 
 ١. يقرأ ("يحلّل") المحرك (المثبت إذا كان متصفحًا) السكريبت.
 
@@ -59,7 +67,11 @@
 - الحصول على ملفات تعريف الارتباط وتعيينها ، وطرح الأسئلة على الزائر ، وإظهار الرسائل.
 - تذكر البيانات الموجودة على جانب العميل ("التخزين المحلي").
 
+<<<<<<< HEAD
 ## ما الذي لا يمكن لجافا سكريبت في المتصفح فعله؟
+=======
+JavaScript's abilities in the browser are limited for the sake of a user's safety. The aim is to prevent an evil webpage from accessing private information or harming the user's data.
+>>>>>>> 7bb6066eb6ea3a030b875cdc75433c458f80997e
 
 إمكانيات جافا سكريبت في المتصفح محدودة من أجل سلامة المستخدم. الهدف هو منع صفحة ويب شريرة من الوصول إلى المعلومات الخاصة أو الإضرار ببيانات المستخدم.
 
@@ -86,9 +98,15 @@
 هناك على الأقل *ثلاثة* أشياء رائعة حول جافا سكريبت:
 
 ```compare
+<<<<<<< HEAD
 + تكامل تام مع HTML / CSS.
 + الأشياء البسيطة تتم ببساطة.
 + مدعوم من قبل جميع المتصفحات الرائدة وتمكينه تلقائيا.
+=======
++ Full integration with HTML/CSS.
++ Simple things are done simply.
++ Supported by all major browsers and enabled by default.
+>>>>>>> 7bb6066eb6ea3a030b875cdc75433c458f80997e
 ```
 
 جافا سكريبت هي تقنية المتصفح الوحيدة التي تجمع بين هذه الأشياء الثلاثة.
@@ -120,6 +138,12 @@
 
 ## ملخص
 
+<<<<<<< HEAD
 - تم إنشاء جافا سكريبت في البداية كلغة للمتصفح فقط ، ولكنها تُستخدم الآن في العديد من البيئات الأخرى أيضًا.
 - تتمتع جافا سكريبت اليوم بمكانة فريدة باعتبارها لغة المتصفح الأكثر استخدامًا مع تكاملها التام مع HTML / CSS.
-- هناك العديد من اللغات التي يتم "تحويلها" إلى جافا سكريبت وتوفر ميزات معينة. يوصى بإلقاء نظرة عليهم ، على الأقل لفترة وجيزة ، بعد إتقان جافا سكريبت.
+- هناك العديد من اللغات التي يتم "تحويلها" إلى جافا سكريبت وتوفر ميزات معينة. يوصى بإلقاء نظرة عليهم ، على الأقل لفترة وجيزة ، بعد إتقان جافا سكريبت.
+=======
+- JavaScript was initially created as a browser-only language, but it is now used in many other environments as well.
+- Today, JavaScript has a unique position as the most widely-adopted browser language, fully integrated with HTML/CSS.
+- There are many languages that get "transpiled" to JavaScript and provide certain features. It is recommended to take a look at them, at least briefly, after mastering JavaScript.
+>>>>>>> 7bb6066eb6ea3a030b875cdc75433c458f80997e

1-js/01-getting-started/3-code-editors/article.md

@@ -35,7 +35,14 @@
 - [Notepad++](https://notepad-plus-plus.org/) (الويندوز، مجاني).
 - [Vim](http://www.vim.org/) و [Emacs](https://www.gnu.org/software/emacs/) رائعة إذا كنت تعرف كيفية استخدامها.
 
+<<<<<<< HEAD
 ## دعونا لا نتشاجر
+=======
+- [Atom](https://atom.io/) (cross-platform, free).
+- [Sublime Text](http://www.sublimetext.com) (cross-platform, shareware).
+- [Notepad++](https://notepad-plus-plus.org/) (Windows, free).
+- [Vim](http://www.vim.org/) and [Emacs](https://www.gnu.org/software/emacs/) are also cool if you know how to use them.
+>>>>>>> 7bb6066eb6ea3a030b875cdc75433c458f80997e
 
 المحررات أعلاه هي التي نقوم باستخدامها أنا وأصدقائي، والذين أعتقد أنهم مطورون جيدون يستخدمونها منذ وقت طويل وتسعدهم.
 

1-js/01-getting-started/4-devtools/article.md

@@ -8,7 +8,11 @@
 
 يفضل معظم المطورون العمل على متصفِّحي Chrome أو FireFox لاحتوائهما على أفضل أدوات المطوّر. توفر المتصفِّحات الأخرى أيضًا مجموعة أدوات للمطوّر والتي من الممكن أن تحتوي على مزايا خاصة. لكن عادةً ما تحاول اللحاق بمتصفِّحي Chrome و FireFox الأفضل من هذه الناحية. يفضل المطوّرون بشكل عام العمل على متصفِّح واحد وينتقلون إلى متصفِّح آخر عندما تكون المشكلة التي يعملون عليها محدَّدة بهذا المتصفِّح.
 
+<<<<<<< HEAD
 بناءً على ذلك، نجد أنَّ أدوات المطور مهمة للغاية لما تمتلكه من مزايا تساعدك أثناء مسيرتك في تطوير الويب عبر JavaScript. سنتعلم في البداية طريقة فتحها، واستخدامها لاستكشاف الأخطاء، وتشغيل تعليمات JavaScript ضمنها.
+=======
+Developer tools are potent; they have many features. To start, we'll learn how to open them, look at errors, and run JavaScript commands.
+>>>>>>> 7bb6066eb6ea3a030b875cdc75433c458f80997e
 
 أدوات المطور قوية, لديها العديد من الميزات. للبدء, سنتعلم كيفية فتحها ، والنظر في الأخطاء ، وتشغيل أوامر جافا سكريبت.
 

1-js/02-first-steps/01-hello-world/article.md

@@ -73,7 +73,11 @@
 <script src="/path/to/script.js"></script>
 ```
 
+<<<<<<< HEAD
 هنا، `/path/to/script.js` هو مسار منفرد للنص البرمجي من جذر الموقع. يمكن أيضاً توفير مسار نسبي من خلال الصفحة الحالية. على سبيل المثال، `src="script.js"` تعني أن الملف `"script.js"` في نفس المجلد.
+=======
+Here, `/path/to/script.js` is an absolute path to the script from the site root. One can also provide a relative path from the current page. For instance, `src="script.js"`, just like `src="./script.js"`, would mean a file `"script.js"` in the current folder.
+>>>>>>> 7bb6066eb6ea3a030b875cdc75433c458f80997e
 
 يمكن أن نعطي المسار الكامل أيضاً. على سبيل المثال :
 

1-js/02-first-steps/02-structure/article.md

@@ -46,6 +46,7 @@ alert(3+
 قريبًا خلال الشيفرات التي ستكتبها).
 إذا كنت ترغب في الاطلاع على مثال واقعي عن هذه الحالة، إليك الشيفرة البرمجية التالية:
 
+<<<<<<< HEAD
 ```
 [1, 2].foreach(alert)
 ```
@@ -55,10 +56,36 @@ alert(3+
 ```
 alert("There will be an error")
 [1 ,2].forEach(alert)
+=======
+The code outputs `6` because JavaScript does not insert semicolons here. It is intuitively obvious that if the line ends with a plus `"+"`, then it is an "incomplete expression", so a semicolon there would be incorrect. And in this case, that works as intended.
+
+**But there are situations where JavaScript "fails" to assume a semicolon where it is really needed.**
+
+Errors which occur in such cases are quite hard to find and fix.
+
+````smart header="An example of an error"
+If you're curious to see a concrete example of such an error, check this code out:
+
+```js run
+alert("Hello");
+
+[1, 2].forEach(alert);
+```
+
+No need to think about the meaning of the brackets `[]` and `forEach` yet. We'll study them later. For now, just remember the result of running the code: it shows `Hello`, then `1`, then `2`.
+
+Now let's remove the semicolon after the `alert`:
+
+```js run no-beautify
+alert("Hello")
+
+[1, 2].forEach(alert);
+>>>>>>> 7bb6066eb6ea3a030b875cdc75433c458f80997e
 ```
 عند تنفيذ الشيفرة البرمجية آنذاك، سيتم إظهار التنبيه الأول فقط ثم سنحصل على خطأ. تعود الشيفرة البرمجية للعمل بشكل
 صحيح مرة أخرى عند إضافة الفاصلة المنقوطة بعد التنبيه الأول:
 
+<<<<<<< HEAD
 ```
 alert("All fine now");
 [1 ,2].forEach(alert)
@@ -72,6 +99,18 @@ alert("All fine now");
 
 ```
 alert("There will be an error")[1, 2].forEach(alert)
+=======
+The difference compared to the code above is only one character: the semicolon at the end of the first line is gone.
+
+If we run this code, only the first `Hello` shows (and there's an error, you may need to open the console to see it). There are no numbers any more.
+
+That's because JavaScript does not assume a semicolon before square brackets `[...]`. So, the code in the last example is treated as a single statement.
+
+Here's how the engine sees it:
+
+```js run no-beautify
+alert("Hello")[1, 2].forEach(alert);
+>>>>>>> 7bb6066eb6ea3a030b875cdc75433c458f80997e
 ```
 ولكنهما عبارتين برمجيتين منفصلتين وليستا عبارة واحدة، وبالتالي عملية الدمج في هذه الحالة خطأ. من الممكن أن تتكرر
 هذه الحالة ضمن شروط أخرى.
@@ -87,7 +126,24 @@ alert("There will be an error")[1, 2].forEach(alert)
 المائلين على نفس السطر تعليقًا. ومن الممكن أن يشغل التعليق سطرًا كاملًا أو يأتي التعليق بعد العبارة البرمجية.
 إليك المثال التالي الذي يشرح ما سبق:
 
+<<<<<<< HEAD
 ```
+=======
+Looks weird, right? Such merging in this case is just wrong. We need to put a semicolon after `alert` for the code to work correctly.
+
+This can happen in other situations also.
+````
+
+We recommend putting semicolons between statements even if they are separated by newlines. This rule is widely adopted by the community. Let's note once again -- *it is possible* to leave out semicolons most of the time. But it's safer -- especially for a beginner -- to use them.
+
+## Comments [#code-comments]
+
+As time goes on, programs become more and more complex. It becomes necessary to add *comments* which describe what the code does and why.
+
+Comments can be put into any place of a script. They don't affect its execution because the engine simply ignores them.
+
+**One-line comments start with two forward slash characters `//`.**
+>>>>>>> 7bb6066eb6ea3a030b875cdc75433c458f80997e
 
 // يمتد هذا التعليق على كامل السطر فقط
 

1-js/02-first-steps/04-variables/article.md

@@ -26,7 +26,11 @@ let message;
 let message;
 
 *!*
+<<<<<<< HEAD
 message = 'Hello'; // تخزين النص
+=======
+message = 'Hello'; // store the string 'Hello' in the variable named message
+>>>>>>> 7bb6066eb6ea3a030b875cdc75433c458f80997e
 */!*
 ```
 
@@ -192,8 +196,13 @@ let 1a; // لا نستطيع نبدأ الاسم برقم
 let my-name; // الواصلات '-' غير مسموح بها في التسمية
 ```
 
+<<<<<<< HEAD
 ```smart header="الملاحظه المهمه"
 المتغيرات التي تُسمي `apple` و `AppLE` يكونوا متغيريين مختلفين تماما
+=======
+```smart header="Case matters"
+Variables named `apple` and `APPLE` are two different variables.
+>>>>>>> 7bb6066eb6ea3a030b875cdc75433c458f80997e
 ```
 
 ````smart header="يُسمح باستخدام الأحرف غير اللاتينية ، ولكن لا يُنصح بها"
@@ -299,7 +308,11 @@ const pageLoadTime = /* الوقت اللازم لتحضير صفحة الويب
 
 قيمة `pageLoadTime` غير معرفه في بداية تحضير الصفحة, لذلك من الطبيعي تسميتها. ولكنها مازالت ثابت لانها لم تتغير بعد التعريف.
 
+<<<<<<< HEAD
 بمعنى آخر ، تُستخدم الثوابت التي تحمل أسماء كبيرة فقط كأسماء مستعارة لقيم "الثابت الترميز".
+=======
+In other words, capital-named constants are only used as aliases for "hard-coded" values.
+>>>>>>> 7bb6066eb6ea3a030b875cdc75433c458f80997e
 
 ## تسمية الاشياء بشكل صحيح
 

1-js/02-first-steps/05-types/article.md

@@ -47,13 +47,23 @@ n = 12.345;
     alert( "not a number" / 2 ); // NaN مثل هذه القسمة خاطئة
     ```
 
+<<<<<<< HEAD
     `NaN` لزجة. أي عملية تتم على  `NaN` ترجع `NaN`:
+=======
+    `NaN` is sticky. Any further mathematical operation on `NaN` returns `NaN`:
+>>>>>>> 7bb6066eb6ea3a030b875cdc75433c458f80997e
 
     ```js run
-    alert( "not a number" / 2 + 5 ); // NaN
+    alert( NaN + 1 ); // NaN
+    alert( 3 * NaN ); // NaN
+    alert( "not a number" / 2 - 1 ); // NaN
     ```
 
+<<<<<<< HEAD
     لذلك إذا وجدت `NaN` في أي مكان في تعبير حسابي تنتشر في النتيجة بأكملها.
+=======
+    So, if there's a `NaN` somewhere in a mathematical expression, it propagates to the whole result (there's only one exception to that: `NaN ** 0` is `1`).
+>>>>>>> 7bb6066eb6ea3a030b875cdc75433c458f80997e
 
 ```smart header="العمليات الرياضية أمنة"
 القيام بالرياضيات "أمن" في جافا سكربت. نستطيع القيام بأي شئ: القسمة على صفر و معاملة النصوص الغير الرقمية على أنها أرقام و إلخ.
@@ -65,7 +75,7 @@ n = 12.345;
 
 سنرى المزيد من التعامل مع الأرقام خلال هذا الفصل <info:number>.
 
-## BigInt
+## BigInt [#bigint-type]
 
 في جافا سكريبت، النوع "number"  لا يمثل الأعداد الصحيحة أكبر من <code>(2<sup>53</sup>-1)</code> (و هو `9007199254740991`)، أو أقل من <code>-(-2<sup>53</sup>-1)</code> للأرقام السالبة. إنها قيود فنية ناتجة عن تمثيلهم الداخلي.
 
@@ -213,6 +223,7 @@ alert(age); // "undefined"
 
 معامل `typeof` يرجع نوع قيمة المدخلات. إنه مفيد عندما نريد معالجة قيم من أنواع مختلفة بإختلاف أو لمجرد إجراد فحص سريع للنوع .
 
+<<<<<<< HEAD
 إنه يدعم نوعين من بناء الكود:
 
 1. كمعامل: `typeof x`.
@@ -221,6 +232,9 @@ alert(age); // "undefined"
 بكلمات أخرى ، إنها تعمل بأقواس أو بدون أقواس. النتيجة ستكون واحدة.
 
 إستدعاء `typeof x` يرجع نص بإسم نوع القيمة:
+=======
+A call to `typeof x` returns a string with the type name:
+>>>>>>> 7bb6066eb6ea3a030b875cdc75433c458f80997e
 
 ```js
 typeof undefined // "undefined"
@@ -250,11 +264,29 @@ typeof alert // "function"  (3)
 
 الثلاث سطور الأخيرة قد تحتاج لتوضيح إضافي:
 
+<<<<<<< HEAD
 1. `Math` كائن مدمج داخلياً لتدعيم العمليات الرياضية. سنتعلمه في الفصل <info:number>. هنا، يخدم فقط كمثال للكائن.
 2. نتيجة `typeof null` هي `"object"`. هذا رسمياً يعتبر خطأ في سلوك `typeof` ، يأتي من الأيام الأولى لجافا سكربت وتم الحفاظ عليه من أجل التوافقية. قطعاً `null` ليس كائن. إنه قيمة خاصة بنوع منفصل خاص.
 3. نتيجة `typeof alert` هي `"function"`، لأن `alert` دالة. سندرس الدوال في الفصول القادمة وهناك سنرى أنه لا توجد نوع خاص  "دالة" في جافا سكربت. الدوال الدوال تنتمي للنوع كائن. لكن `typeof` تعاملهم بشكل مختلف، يرجع `"دالة"`. هذا أيضاً يأتي من الأيام الأولى لجافا سكربت. فنياً، مثل هذا السلوك غير صحيح، لكن قد يكون ملائم في الممارسة.
 
 ## خلاصة
+=======
+1. `Math` is a built-in object that provides mathematical operations. We will learn it in the chapter <info:number>. Here, it serves just as an example of an object.
+2. The result of `typeof null` is `"object"`. That's an officially recognized error in `typeof`, coming from very early days of JavaScript and kept for compatibility. Definitely, `null` is not an object. It is a special value with a separate type of its own. The behavior of `typeof` is wrong here.
+3. The result of `typeof alert` is `"function"`, because `alert` is a function. We'll study functions in the next chapters where we'll also see that there's no special "function" type in JavaScript. Functions belong to the object type. But `typeof` treats them differently, returning `"function"`. That also comes from the early days of JavaScript. Technically, such behavior isn't correct, but can be convenient in practice.
+
+```smart header="The `typeof(x)` syntax"
+You may also come across another syntax: `typeof(x)`. It's the same as `typeof x`.
+
+To put it clear: `typeof` is an operator, not a function. The parentheses here aren't a part of `typeof`. It's the kind of parentheses used for mathematical grouping.
+
+Usually, such parentheses contain a mathematical expression, such as `(2 + 2)`, but here they contain only one argument `(x)`. Syntactically, they allow to avoid a space between the `typeof` operator and its argument, and some people like it.
+
+Some people prefer `typeof(x)`, although the `typeof x` syntax is much more common.
+```
+
+## Summary
+>>>>>>> 7bb6066eb6ea3a030b875cdc75433c458f80997e
 
 يوجد 8 أنواع للبيانات في جافا سكربت.
 
@@ -269,8 +301,14 @@ typeof alert // "function"  (3)
 
 معامل `typeof` يسمح لنا بمعرفة نوع البيانات الموجودة بداخل المتغيرة.
 
+<<<<<<< HEAD
 - له شكلان: `typeof x` أو `typeof(x)`.
 - يرجع نص بإسم نوع البيانات، مثل  `"string"`.
 - من أجل `null` يرجع `"object"` - هذا خطأ في اللغة، إنه ليس في الحقيقة كائن.
+=======
+- Usually used as `typeof x`, but `typeof(x)` is also possible.
+- Returns a string with the name of the type, like `"string"`.
+- For `null` returns `"object"` -- this is an error in the language, it's not actually an object.
+>>>>>>> 7bb6066eb6ea3a030b875cdc75433c458f80997e
 
 في الفصول القادمة سنركز على القيم البدائية وعندما نكون متألفين معاهم، سنتجه للكائنات.

1-js/02-first-steps/07-type-conversions/article.md

@@ -7,7 +7,11 @@
 هناك أيضاً حالات نحتاج إلى تصريح تحويل القيمة إلى النوع المطلوب.
 
 ```smart header="Not talking about objects yet"
+<<<<<<< HEAD
 في هذا الفصل، لن نغطي الكائنات. الآن سوف نتحدث عن الأنواع الأساسية.
+=======
+In this chapter, we won't cover objects. For now, we'll just be talking about primitives.
+>>>>>>> 7bb6066eb6ea3a030b875cdc75433c458f80997e
 
 فيما بعد، بعد أن نتعلم عن الكائنات، في هذا الفصل <info:object-toprimitive> سنرى كيف تتلائم الكائنات فيه.
 ```