Sync with upstream @ 34a80e70

.github/FUNDING.yml

@@ -0,0 +1 @@
+github: iliakan

.gitignore

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

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

@@ -1,10 +1,18 @@
 # 介紹 JavaScript
 
+<<<<<<< HEAD
 一起來看看 JavaScript 有什麼特別的，我們能做些什麼，與哪些配合不錯的技術。
+=======
+Let's see what's so special about JavaScript, what we can achieve with it, and what other technologies play well with it.
+>>>>>>> 34a80e70f8cce5794be259d25f815d7a7db7cbe3
 
 ## 什麼是 JavaScript?
 
+<<<<<<< HEAD
 *JavaScript* 最初是為了 *"賦予網頁活力"* 而創造的。
+=======
+*JavaScript* was initially created to "make web pages alive".
+>>>>>>> 34a80e70f8cce5794be259d25f815d7a7db7cbe3
 
 這種程式語言我們稱之為 *腳本*，它們可以被寫入網頁 HTML 中，並在頁面讀取時自動執行。
 
@@ -24,26 +32,44 @@
 
 不同的引擎有不同的 "代號（codenames）"。例如：
 
+<<<<<<< HEAD
 - [V8](https://en.wikipedia.org/wiki/V8_(JavaScript_engine)) -- Chrome 和 Opera 內的引擎。
 - [SpiderMonkey](https://en.wikipedia.org/wiki/SpiderMonkey) -- Firefox 內的引擎。
 - ... 還有其他代號，像是不同版本 IE 使用的 "Trident" 與 "Chakra"、微軟 Edge 的 "ChakraCore"、Safari 的 "Nitro" 與 "SquirrelFish"，等等。
 
 上面提到的代號最好可以記住，因為這些代號常被用於網路上的開發者文章，就像我們一樣。如："V8 支援某個 X 功能"，代表該功能在 Chrome 和 Opera 上應該可以運作。
+=======
+- [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.
+>>>>>>> 34a80e70f8cce5794be259d25f815d7a7db7cbe3
 
 ```smart header="引擎怎麼運作的？"
 
 引擎很複雜，但概念很簡單。
 
+<<<<<<< HEAD
 1. 引擎（瀏覽器內建）讀取（"解析"）腳本
 2. 接著轉換（"編譯"）腳本為機器語言
 3. 然後機器語言極快地執行
+=======
+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.
+>>>>>>> 34a80e70f8cce5794be259d25f815d7a7db7cbe3
 
 引擎會對流程中每個階段進行優化。甚至會在執行時監看編譯好的腳本，分析其資料流，並以此再優化機器碼。
 ```
 
 ## 瀏覽器中的 JavaScript 可以做什麼？
 
+<<<<<<< HEAD
 現代化 JavaScript 是個 "安全" 的程式語言。它不提供對記憶體或 CPU 的低階存取，因為它原生是為了瀏覽器而建立，所以不需要。
+=======
+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.
+>>>>>>> 34a80e70f8cce5794be259d25f815d7a7db7cbe3
 
 JavaScript 的能力很大一部分取決於執行它的環境。例如 [Node.js](https://wikipedia.org/wiki/Node.js) 提供 JavaScript 可以讀寫任意檔案與發送網路請求（network requests）等功能。
 
@@ -59,14 +85,23 @@ JavaScript 的能力很大一部分取決於執行它的環境。例如 [Node.js
 
 ## 瀏覽器中的 JavaScript **不能**做什麼？
 
+<<<<<<< HEAD
 為了使用者的資訊安全，JavaScript 在瀏覽器內的功能被限制。此為防範惡意網頁獲取私人資訊或損害使用者資料。
+=======
+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.
+>>>>>>> 34a80e70f8cce5794be259d25f815d7a7db7cbe3
 
 這些限制範例如下：
 
+<<<<<<< HEAD
 - 網頁上的 JavaScript 無法讀寫、複製和執行硬碟內任意檔案。它也沒有直接存取作業系統的功能。
+=======
+- JavaScript on a webpage may not read/write arbitrary files on the hard disk, copy them or execute programs. It has no direct access to OS functions.
+>>>>>>> 34a80e70f8cce5794be259d25f815d7a7db7cbe3
 
     現代化瀏覽器允許 JavaScript 有限制地操作檔案，且只有在使用者做特定動作時提供，像是："拖曳" 一個檔案至瀏覽器視窗，或經由 `<input>` 標籤選取。
 
+<<<<<<< HEAD
     JavaScript 有些方法可與相機、麥克風或其他裝置互動，但都需要使用者明確地授權。所以啟用 JavaScript 的網頁不會偷偷開啟相機觀察周遭並傳資料給 [美國國家安全局（NSA）](https://en.wikipedia.org/wiki/National_Security_Agency)。
 - 不同的瀏覽器分頁/視窗基本上不知道彼此，但有時例外，例如：當一個視窗使用 JavaScript 開啟另一個視窗時。但就算如此，開啟不同網站（不同域名、通訊協定或埠）的頁面，其中的 JavaScript 亦無法溝通。
 
@@ -78,44 +113,88 @@ JavaScript 的能力很大一部分取決於執行它的環境。例如 [Node.js
 ![](limitations.svg)
 
 在瀏覽器以外的 JavaScript 就沒有這些限制，如：伺服器上的 JavaScript。現代化瀏覽器也允許插件/擴充套件要求額外權限。
+=======
+    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.
+>>>>>>> 34a80e70f8cce5794be259d25f815d7a7db7cbe3
 
 ## 是什麼讓 JavaScript 如此獨特？
 
 至少有 *三項* JavaScript 很棒的事：
 
 ```compare
+<<<<<<< HEAD
 + 與 HTML/CSS 完整整合
 + 簡單的事能夠簡單地完成
 + 所有主要瀏覽器支援且預設開啟
+=======
++ Full integration with HTML/CSS.
++ Simple things are done simply.
++ Supported by all major browsers and enabled by default.
+>>>>>>> 34a80e70f8cce5794be259d25f815d7a7db7cbe3
 ```
 在瀏覽器技術中，只有 JavaScript 能唯一滿足這三項。
 
 這造就 JavaScript 如此獨特。這也是為什麼它是建立瀏覽器介面最為廣泛的工具。
 
+<<<<<<< HEAD
 此外，JavaScript 也可以建立伺服器和手機應用程式等等。
+=======
+That said, JavaScript can be used to create servers, mobile applications, etc.
+>>>>>>> 34a80e70f8cce5794be259d25f815d7a7db7cbe3
 
 ## JavaScript "之上" 的語言
 
 JavaScript 的語法並不符合每個人的要求，不同人想要不同功能。
 
 這是預期中的，因為每個人的計畫和需求都不一樣。
 
+<<<<<<< HEAD
 所以最近有大量新語言出現，它們在被瀏覽器執行前，都被 *轉譯*（transpiled）成 JavaScript。
+=======
+So, recently a plethora of new languages appeared, which are *transpiled* (converted) to JavaScript before they run in the browser.
+>>>>>>> 34a80e70f8cce5794be259d25f815d7a7db7cbe3
 
 現代化的工具讓轉譯迅速且透明，且實際上使開發者用另一種語言寫程式，再被自行轉換成 JavaScript。
 
 例如這些語言：
 
+<<<<<<< HEAD
 - [CoffeeScript](http://coffeescript.org/) 是組 JavaScript 的 "語法糖"。它有更簡短的語法，可以讓我們寫出更清楚且精確的程式碼，通常 Ruby 開發者愛用。
 - [TypeScript](http://www.typescriptlang.org/) 致力於增加 "強型態確認（strict data typing）" 來簡化開發與支援複雜的系統，為微軟所開發。
 - [Flow](http://flow.org/) 同樣增加型態確認但使用不同方式，為臉書所開發。
 - [Dart](https://www.dartlang.org/) 是一種擁有自己引擎的獨立語言，它執行在非瀏覽器環境上（像是手機應用程式），但也可以轉譯成 JavaScript，為谷歌所開發。
 
 還有更多其他語言。當然，就算我們使用某種轉譯式語言，我們應該也要了解 JavaScript 來真正知道我們在做什麼。
+=======
+- [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.
+>>>>>>> 34a80e70f8cce5794be259d25f815d7a7db7cbe3
 
 ## 總結
 
 - JavaScript 最初被建為只用在瀏覽器上的語言，但現在也被其他多種環境所使用。
 - 至今 JavaScript 有著獨特的地位，它是在瀏覽器上最被廣泛採用的語言且與 HTML/CSS 完整整合。
 - 有許多語言可被 "轉譯" 成 JavaScript 並提供特定的功能。建議在掌握 JavaScript 後可以稍微看看。
 
+<<<<<<< HEAD
+=======
+- 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.
+>>>>>>> 34a80e70f8cce5794be259d25f815d7a7db7cbe3

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

@@ -2,22 +2,35 @@
 
 這本書是個 *教程*，主要是幫助你漸漸地學會這門語言，一旦你熟悉了基礎，你將會需要更多其他的資源。
 
+<<<<<<< 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.
+>>>>>>> 34a80e70f8cce5794be259d25f815d7a7db7cbe3
 
 [The ECMA-262 specification](https://www.ecma-international.org/publications/standards/Ecma-262.htm) 規格書包含了 JavaScript 最深入、詳細以及形式化的資訊。它定義了這門語言。
 
 但就因為它太形式化了，一開始你會很難讀得懂。如果你需要關於這門語言最可靠的資源，來看規格書就對了，但它不太適合你拿來日常使用。
 
 每年都會有新規格版本釋出，這些釋出版本之間的最新規格草案在這 <https://tc39.es/ecma262/>。
 
+<<<<<<< HEAD
 如果你想知道最尖端的功能，包含那些 "即將成為標準"（所謂 "stage 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/>.
+>>>>>>> 34a80e70f8cce5794be259d25f815d7a7db7cbe3
 
 同樣地，假如你在開發瀏覽器相關的功能，我們也有在此教程的 [第二部分](info:browser-environment) 介紹相關的規格書。
 
+<<<<<<< HEAD
 ## 操作手冊
+=======
+Also, if you're developing for the browser, then there are other specifications covered in the [second part](info:browser-environment) of the tutorial.
+>>>>>>> 34a80e70f8cce5794be259d25f815d7a7db7cbe3
 
 - **MDN (Mozilla) JavaScript Reference** 是一個包含了範例以及其他資訊的操作手冊，很適合拿來獲取個別函式或是方法的深入資訊。
 
+<<<<<<< HEAD
     你可以在這裡找到 <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference>。
 
     不過，透過網路搜尋通常會是較好的選擇。使用在搜尋列打入 "MDN [關鍵字]" 的方式，比如你要搜尋 `parseInt` 這個函式，可以用 <https://google.com/search?q=MDN+parseInt>。
@@ -29,6 +42,13 @@
 ## 兼容表
 
 JavaScript 是一個持續開發中的語言，它定期會被加入一些新功能。
+=======
+- **MDN (Mozilla) JavaScript Reference** is the main manual with examples and other information. It's great to get in-depth information about individual language functions, methods etc.
+
+    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.
+>>>>>>> 34a80e70f8cce5794be259d25f815d7a7db7cbe3
 
 想知道瀏覽器或是其他引擎的支援程度，可以參考：
 
@@ -37,5 +57,14 @@ JavaScript 是一個持續開發中的語言，它定期會被加入一些新功
 
 所有這些資訊對於實務開發都是很有用的，因為他們包含了非常有價值的資訊，比如支援程度跟語言的細節等。
 
+<<<<<<< HEAD
 當你需要比較深入的資訊或是需要了解一些特定的功能時，請記得使用這些資訊（或是此頁）。
 
+=======
+- <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.
+
+Please remember them (or this page) for the cases when you need in-depth information about a particular feature.
+>>>>>>> 34a80e70f8cce5794be259d25f815d7a7db7cbe3

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

@@ -12,8 +12,13 @@
 
 如果你還沒選擇使用一個 IDE，可以考慮以下選擇：
 
+<<<<<<< HEAD
 - [Visual Studio Code](https://code.visualstudio.com/)（跨平台，免費）。
 - [WebStorm](http://www.jetbrains.com/webstorm/)（跨平台，付費）。
+=======
+- [Visual Studio Code](https://code.visualstudio.com/) (cross-platform, free).
+- [WebStorm](https://www.jetbrains.com/webstorm/) (cross-platform, paid).
+>>>>>>> 34a80e70f8cce5794be259d25f815d7a7db7cbe3
 
 若使用 Windows 系統，也可選用 "Visual Studio"，但別跟 "Visual Studio Code" 搞混了。"Visual Studio" 是一個需付費且強大的 Windows 專屬編輯器，特別適合開發 .NET 平台，用來開發 JavaScript 也不錯。它有個免費的版本 [Visual Studio Community](https://www.visualstudio.com/vs/community/)。
 
@@ -29,13 +34,21 @@
 
 實際上，輕量化編輯器可能有各式各樣的插件，包含目錄語法層級分析與自動程式補完，所以兩者間並沒有明顯的界線。
 
+<<<<<<< HEAD
 以下是一些值得考慮的選擇：
 
 - [Atom](https://atom.io/)（跨平台，免費）。
 - [Visual Studio Code](https://code.visualstudio.com/)（跨平台，免費）.
 - [Sublime Text](http://www.sublimetext.com)（跨平台，共享軟體）。
 - [Notepad++](https://notepad-plus-plus.org/)（Windows，免費）。
 - [Vim](http://www.vim.org/) 和 [Emacs](https://www.gnu.org/software/emacs/) 也很不錯，前提是你要知道怎麼使用。
+=======
+There are many options, for instance:
+
+- [Sublime Text](https://www.sublimetext.com/) (cross-platform, shareware).
+- [Notepad++](https://notepad-plus-plus.org/) (Windows, free).
+- [Vim](https://www.vim.org/) and [Emacs](https://www.gnu.org/software/emacs/) are also cool if you know how to use them.
+>>>>>>> 34a80e70f8cce5794be259d25f815d7a7db7cbe3
 
 ## 不要起爭議
 
@@ -45,3 +58,12 @@
 
 選擇編輯器就像選其他工具一樣，需要依照你的專案、習慣和個人喜好選擇。
 
+<<<<<<< HEAD
+=======
+The choice of an editor, like any other tool, is individual and depends on your projects, habits, and personal preferences.
+
+The author's personal opinion:
+
+- I'd use [Visual Studio Code](https://code.visualstudio.com/) if I develop mostly frontend.
+- Otherwise, if it's mostly another language/platform and partially frontend, then consider other editors, such as XCode (Mac), Visual Studio (Windows) or Jetbrains family (Webstorm, PHPStorm, RubyMine etc, depending on the language).
+>>>>>>> 34a80e70f8cce5794be259d25f815d7a7db7cbe3

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

@@ -29,11 +29,23 @@
 - 在這裡我們可以看到紅色標註的錯誤訊息，這個例子中，腳本內有一個未知的 "lalala" 指令。
 - 在右邊有一個可以點擊連至原始碼的連結 `bug.html:12`，伴隨著產生錯誤的程式行數。
 
+<<<<<<< HEAD
 錯誤訊息底下，有一個藍色 `>` 符號，它代表著我們可以輸入 JavaScript 的 "命令行"。按下 `key:Enter` 來執行它們（用 `key:Shift+Enter` 來輸入多行指令）。
+=======
+Below the error message, there is a blue `>` symbol. It marks a "command line" where we can type JavaScript commands. Press `key:Enter` to run them.
+>>>>>>> 34a80e70f8cce5794be259d25f815d7a7db7cbe3
 
 現在我們可以看到錯誤就夠了，晚點會於章節 <info:debugging-chrome> 再回到開發者工具並深入探討除錯這件事。
 
+<<<<<<< HEAD
 ## Firefox、Edge 與其他
+=======
+```smart header="Multi-line input"
+Usually, when we put a line of code into the console, and then press `key:Enter`, it executes.
+
+To insert multiple lines, press `key:Shift+Enter`. This way one can enter long fragments of JavaScript code.
+```
+>>>>>>> 34a80e70f8cce5794be259d25f815d7a7db7cbe3
 
 多數其他瀏覽器使用 `key:F12` 打開開發者工具。
 
@@ -49,13 +61,17 @@ Safari（Mac 瀏覽器，Windows/Linux 不支援）有點不太一樣，我們
 
 現在 `key:Cmd+Opt+C` 可以開啟控制台。同樣地，注意最上方出現一個新的選單名為 "開發（Develop）"，有著許多指令與選項。
 
+<<<<<<< HEAD
 ```smart header="輸入多行"
 通常當我們輸入一行程式碼到控制台並按下 `key:Enter`，它就執行了。
 
 要插入多行程式，按下 `key:Shift+Enter`，這樣就可以輸入長片段的 JavaScript 程式碼。
 ```
 
 ## 總結
+=======
+## Summary
+>>>>>>> 34a80e70f8cce5794be259d25f815d7a7db7cbe3
 
 - 開發者工具允許我們看到錯誤、執行指令、查看變數（variables）與更多其它事。
 - 大多數 Windows 的瀏覽器可以經由按下 `key:F12` 開啟。Mac 上的 Chrome 需要 `key:Cmd+Opt+J`；Safari 要用 `key:Cmd+Opt+C`（需先啟用）。