Sync with upstream @ 72aa4f0b

.gitignore

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

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

@@ -29,20 +29,40 @@
 
 من الجيد تذكر المصطلحات الواردة أعلاه لأنها مستخدمة في مقالات المطورين على الإنترنت. سنستخدمهم أيضًا. على سبيل المثال ، إذا كانت "الميزة إكس مدعومة بواسطة في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.
+>>>>>>> 72aa4f0b9783a38155dd766ef50f025e672cfcee
 
 ١. يقرأ ("يحلّل") المحرك (المثبت إذا كان متصفحًا) السكريبت.
 
 ٢. ثم يحول ("يترجم") السكربت الى لغة  الآلة.
 
+<<<<<<< HEAD
 ٣. وبعد ذلك يتم تشغيل رموز الآلة، بسرعة كبيرة.
+=======
+1. The engine (embedded if it's a browser) reads ("parses") the script.
+2. Then it converts ("compiles") the script to machine code.
+3. And then the machine code runs, pretty fast.
+>>>>>>> 72aa4f0b9783a38155dd766ef50f025e672cfcee
 
 يطبق المحرك التحسينات في كل خطوة من العملية. حتى أنه يراقب النص المترجم أثناء تشغيله ، ويحلل البيانات التي تتدفق من خلاله ، ويزيد من تحسين رموز الآلة بناءً على تلك المعرفة.
 ```
 
+<<<<<<< HEAD
 ## ما الذي يمكن أن يفعله جافا سكريبت في المتصفح؟
+=======
+## What can in-browser JavaScript do?
+
+Modern JavaScript is a "safe" programming language. It does not provide low-level access to memory or the CPU, because it was initially created for browsers which do not require it.
+>>>>>>> 72aa4f0b9783a38155dd766ef50f025e672cfcee
 
 جافا سكريبت الحديثة هي لغة برمجة "آمنة". لا توفر وصولاً منخفض المستوى إلى الذاكرة أو وحدة المعالجة المركزية، لأنه تم إنشاؤها في البداية للمتصفحات التي لا تتطلب ذلك.
 
@@ -59,14 +79,19 @@
 - الحصول على ملفات تعريف الارتباط وتعيينها ، وطرح الأسئلة على الزائر ، وإظهار الرسائل.
 - تذكر البيانات الموجودة على جانب العميل ("التخزين المحلي").
 
+<<<<<<< HEAD
 ## ما الذي لا يمكن لجافا سكريبت في المتصفح فعله؟
+=======
+JavaScript's abilities in the browser are limited to protect the user's safety. The aim is to prevent an evil webpage from accessing private information or harming the user's data.
+>>>>>>> 72aa4f0b9783a38155dd766ef50f025e672cfcee
 
 إمكانيات جافا سكريبت في المتصفح محدودة من أجل سلامة المستخدم. الهدف هو منع صفحة ويب شريرة من الوصول إلى المعلومات الخاصة أو الإضرار ببيانات المستخدم.
 
 من أمثلة هذه القيود:
 
 - جافا سكريبت على صفحة الويب قد لا تقرأ/تكتب ملفات عشوائية على القرص الصلب أو تنسخها أو تنفذ برامج. ليس لديها وصول مباشر إلى وظائف نظام التشغيل.
 
+<<<<<<< HEAD
     تسمح المتصفحات الحديثة له بالعمل مع الملفات ، ولكن الوصول محدود ويتم توفيره فقط إذا قام المستخدم بإجراءات معينة ، مثل "إسقاط" ملف في نافذة المتصفح أو تحديده عبر علامة `<input>`.
 
     هناك طرق للتفاعل مع الكاميرا / الميكروفون والأجهزة الأخرى ، لكنها تتطلب إذنًا صريحًا من المستخدم. لذلك قد لا تعمل الصفحة التي تم تمكين جافا سكريبت فيها بشكل خفي على تمكين كاميرا الويب ومراقبة المناطق المحيطة وإرسال المعلومات إلى [آن آس أيه](https://ar.wikipedia.org/wiki/وكالة_الأمن_القومي_الأمريكية)
@@ -80,35 +105,63 @@
 ![](limitations.svg)
 
 لا توجد مثل هذه الحدود إذا تم استخدام جافا سكريبت خارج المتصفح ، على سبيل المثال على الخادم. تسمح المتصفحات الحديثة أيضًا الإضافات التي قد تطلب تصريحات ممتدة.
+=======
+    There are ways to interact with the camera/microphone and other devices, but they require a user's explicit permission. So a JavaScript-enabled page may not sneakily enable a web-camera, observe the surroundings and send the information to the [NSA](https://en.wikipedia.org/wiki/National_Security_Agency).
+- Different tabs/windows generally do not know about each other. Sometimes they do, for example when one window uses JavaScript to open the other one. But even in this case, JavaScript from one page may not access the other page if they come from different sites (from a different domain, protocol or port).
+
+    This is called the "Same Origin Policy". To work around that, *both pages* must agree for data exchange and must contain special JavaScript code that handles it. We'll cover that in the tutorial.
+
+    This limitation is, again, for the user's safety. A page from `http://anysite.com` which a user has opened must not be able to access another browser tab with the URL `http://gmail.com`, for example, and steal information from there.
+- JavaScript can easily communicate over the net to the server where the current page came from. But its ability to receive data from other sites/domains is crippled. Though possible, it requires explicit agreement (expressed in HTTP headers) from the remote side. Once again, that's a safety limitation.
+
+![](limitations.svg)
+
+Such limitations do not exist if JavaScript is used outside of the browser, for example on a server. Modern browsers also allow plugins/extensions which may ask for extended permissions.
+>>>>>>> 72aa4f0b9783a38155dd766ef50f025e672cfcee
 
 ## ما الذي يجعل جافا سكريبت فريدًا؟
 
 هناك على الأقل *ثلاثة* أشياء رائعة حول جافا سكريبت:
 
 ```compare
+<<<<<<< HEAD
 + تكامل تام مع HTML / CSS.
 + الأشياء البسيطة تتم ببساطة.
 + مدعوم من قبل جميع المتصفحات الرائدة وتمكينه تلقائيا.
+=======
++ Full integration with HTML/CSS.
++ Simple things are done simply.
++ Supported by all major browsers and enabled by default.
+>>>>>>> 72aa4f0b9783a38155dd766ef50f025e672cfcee
 ```
 
 جافا سكريبت هي تقنية المتصفح الوحيدة التي تجمع بين هذه الأشياء الثلاثة.
 
 هذا ما يجعل جافا سكريبت فريدًا. هذا هو السبب في أنها الأداة الأكثر انتشارًا لإنشاء واجهات المتصفح.
 
+<<<<<<< HEAD
 ومع ذلك، تسمح جافا سكريبت أيضًا بإنشاء خوادم وتطبيقات الجوال، إلخ.
+=======
+That said, JavaScript can be used to create servers, mobile applications, etc.
+>>>>>>> 72aa4f0b9783a38155dd766ef50f025e672cfcee
 
 ## لغات "فوق" جافا سكريبت
 
 لا تتناسب القواعد اللغوية لجافا سكريبت مع احتياجات الجميع. الناس المختلفون يريدون ميزات مختلفة.
 
 هذا أمر متوقع ، لأن المشاريع والمتطلبات تختلف من شخص لآخر.
 
+<<<<<<< HEAD
 ظهرت في الآونة الأخيرة عدد كبير من اللغات الجديدة ، والتي *تم تحويلها* إلى جافا سكريبت قبل تشغيلها في المتصفح.
+=======
+So, recently a plethora of new languages appeared, which are *transpiled* (converted) to JavaScript before they run in the browser.
+>>>>>>> 72aa4f0b9783a38155dd766ef50f025e672cfcee
 
 الأدوات الحديثة تجعل الترجمة سريعة وشفافة للغاية ، مما يسمح للمطورين في الواقع بالتشفير بلغة أخرى وتحويلها تلقائيًا "خلف الكواليس".
 
 أمثلة على هذه اللغات:
 
+<<<<<<< HEAD
 - [كوفي سكريبت](http://coffeescript.org/) هو "سكر نحوي" لجافا سكريبت. إنه يقدم بناء جمل أقصر ، مما يسمح لنا بكتابة كود أكثر وضوحًا ودقة. عادة ،مطورو روبي يحبونها.
 - [تايب سكريبت](http://www.typescriptlang.org/) يركز على إضافة "كتابة بيانات صارمة" لتبسيط تطوير ودعم الأنظمة المعقدة. تم تطويره بواسطة ميكروسوفت.
 - [فلو](http://flow.org/) يضيف أيضًا كتابة البيانات ، ولكن بطريقة مختلفة. تم تطويره بواسطة فايسبوك.
@@ -117,9 +170,25 @@
 - [كوتلن](https://kotlinlang.org/docs/reference/js-overview.html) هي لغة برمجة حديثة وموجزة وآمنة يمكنها استهداف المتصفح أو نود.
 
 هناك أكثر. بالطبع ، حتى لو استخدمنا إحدى اللغات المترجمة ، يجب أن نعرف أيضًا جافا سكريبت لفهم ما نقوم به حقًا.
+=======
+- [CoffeeScript](https://coffeescript.org/) is "syntactic sugar" for JavaScript. It introduces shorter syntax, allowing us to write clearer and more precise code. Usually, Ruby devs like it.
+- [TypeScript](https://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](https://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.
+- [Kotlin](https://kotlinlang.org/docs/reference/js-overview.html) is a modern, concise and safe programming language that can target the browser or Node.
+
+There are more. Of course, even if we use one of these transpiled languages, we should also know JavaScript to really understand what we're doing.
+>>>>>>> 72aa4f0b9783a38155dd766ef50f025e672cfcee
 
 ## ملخص
 
+<<<<<<< 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.
+>>>>>>> 72aa4f0b9783a38155dd766ef50f025e672cfcee

1-js/01-getting-started/2-manuals-specifications/article.md

@@ -2,15 +2,23 @@
 
 هذا الكتاب هو _دورة تعليمية_. يهدف الى تعليمك اللغه تدريجيا. و لكن إذا كنت علي علم بالأساسيات فسوف تحتاج إلى مصدر آخر.
 
+<<<<<<< HEAD
 ## الوصف
+=======
+This book is a *tutorial*. It aims to help you gradually learn the language. But once you're familiar with the basics, you'll need other resources.
+>>>>>>> 72aa4f0b9783a38155dd766ef50f025e672cfcee
 
 [وصف The ECMA-262](https://www.ecma-international.org/publications/standards/Ecma-262.htm) يحتوي على المعلومات الأكثر عمقاً وتفصيلاً ورسميةً عن جافا سكريبت. وهي تقوم بتعريف اللغة.
 
 و لكن كونها بهذه الرسمية، تجعل فهمها من أول مرة صعبا. لذلك إذا كنت تريد مصدر المعلومى الأكثر وثوقاً عن تفاصيل اللغة، الوصف هو المكان الصحيح. لكنها ليست للإستعمال اليومي.
 
 نسخة وصف جديدة تُصدر كل عام. فيما بين هذه الإصدارات، آخر مسودة وصف توجد في <https://tc39.es/ecma262/>.
 
+<<<<<<< HEAD
 لكي تقرأ عن خصائص التطور الحاد الجديد، بما فى ذلك "المعايير التقريبية" (ما يسمي "المرحلة 3")، انظر للمقترحات في <https://github.com/tc39/proposals>.
+=======
+A new specification version is released every year. Between these releases, the latest specification draft is at <https://tc39.es/ecma262/>.
+>>>>>>> 72aa4f0b9783a38155dd766ef50f025e672cfcee
 
 أيضاً، إذا كنت تطور من أجل المتصفح، إذا هناك مواصفات أخرى مشمولة في [الجزء الثاني](info:browser-environment) من الدورة التعليمية.
 
@@ -20,18 +28,31 @@
 
 يمكن أن تجدها في <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference>.
 
+<<<<<<< HEAD
 أيضاً، غالباً ما يكون من الأفضل استخدام البحث عبر الإنترنت بدلاً من ذلك. فقط استخدم "[مصطلح] MDN" للإستعلام، مثال <https://google.com/search?q=MDN+parseInt> لتبحث عن دالة `parseInt`.
 
+=======
+    You can find it at <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference>.
+
+Although, it's often best to use an internet search instead. Just use "MDN [term]" in the query, e.g. <https://google.com/search?q=MDN+parseInt> to search for the `parseInt` function.
+>>>>>>> 72aa4f0b9783a38155dd766ef50f025e672cfcee
 
 ## جدول التوافق
 
 جافا سكريبت لغة فى سياق متطور، تضاف إليها خصائص جديدة بانتظام.
 
 
+<<<<<<< HEAD
 لتَّـحَقّـق من الدعم ما بين المتصفحات والمحركات الأخرى، انظر:
 
 - <http://caniuse.com> - جدول الدعم لكل خاصية، مثال: لترى أيًا من المحركات يدعم دوال التشفير الحديث: <http://caniuse.com/#feat=cryptography>.
 - <https://kangax.github.io/compat-table> - جدول بمواصفات ومحركات اللغة وقابلية دعم كل محرك لكل خاصية.
+=======
+- <https://caniuse.com> - per-feature tables of support, e.g. to see which engines support modern cryptography functions: <https://caniuse.com/#feat=cryptography>.
+- <https://kangax.github.io/compat-table> - a table with language features and engines that support those or don't support.
+
+All these resources are useful in real-life development, as they contain valuable information about language details, their support, etc.
+>>>>>>> 72aa4f0b9783a38155dd766ef50f025e672cfcee
 
 كل هذه المصادر مفيدة في تطوير الحياة الواقعية، لأنها تحتوي علي معلومات قيّمة عن تفاصيل ودعم اللغة.
 

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

@@ -12,8 +12,13 @@
 
 إذا لم تقم باختيار IDE بعد، ففكر في الخيارات التالية:
 
+<<<<<<< HEAD
 - [فيجوال ستديو كود](https://code.visualstudio.com/) (يعمل على أكثر من نظام تشغيل، مجاني).
 - [ويب ستورم](http://www.jetbrains.com/webstorm/) (يعمل على أكثر من نظام تشغيل، مدفوع).
+=======
+- [Visual Studio Code](https://code.visualstudio.com/) (cross-platform, free).
+- [WebStorm](https://www.jetbrains.com/webstorm/) (cross-platform, paid).
+>>>>>>> 72aa4f0b9783a38155dd766ef50f025e672cfcee
 
 بالنسبة للويندوز، يمكن استخدام برنامج فيجوال ستديو، لايجب الخلط بينه وبين الفيجوال ستديو كود، فيجوال ستديو هو محرر مدفوع يعمل على نظام ويندوز فقط، ومناسب تماماً لبيئة الـ.NET. أنه أيضاً جيد لجافا سكريبت. كما يوجد إصدار مجاني منه [Visual Studio Community](https://www.visualstudio.com/vs/community/).
 
@@ -35,7 +40,13 @@
 - [Notepad++](https://notepad-plus-plus.org/) (الويندوز، مجاني).
 - [Vim](http://www.vim.org/) و [Emacs](https://www.gnu.org/software/emacs/) رائعة إذا كنت تعرف كيفية استخدامها.
 
+<<<<<<< HEAD
 ## دعونا لا نتشاجر
+=======
+- [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.
+>>>>>>> 72aa4f0b9783a38155dd766ef50f025e672cfcee
 
 المحررات أعلاه هي التي نقوم باستخدامها أنا وأصدقائي، والذين أعتقد أنهم مطورون جيدون يستخدمونها منذ وقت طويل وتسعدهم.
 

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.
+>>>>>>> 72aa4f0b9783a38155dd766ef50f025e672cfcee
 
 أدوات المطور قوية, لديها العديد من الميزات. للبدء, سنتعلم كيفية فتحها ، والنظر في الأخطاء ، وتشغيل أوامر جافا سكريبت.