From 6a891403fdefec9952adb7c7047c9e7b731e223b Mon Sep 17 00:00:00 2001 From: Ilya Kantor Date: Sun, 27 Sep 2020 13:18:00 +0300 Subject: [PATCH 1/7] readme --- README.md | 173 +++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 152 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 4b19fc5cf4..f8eb47dad8 100755 --- a/README.md +++ b/README.md @@ -1,39 +1,170 @@ -# The Modern JavaScript Tutorial +# The Modern JavaScript Tutorial in v2 -This repository hosts the English content of the Modern JavaScript Tutorial, published at [https://javascript.info](https://javascript.info). +This repository hosts the translation of in v2. -## Translations -We'd like to make the tutorial available in many languages. Please help us to translate. +**That's how you can contribute:** -See for the details. +- See the [v2 Translate Progress](https://github.com/javascript-tutorial/v2.javascript.info/issues/1) issue. +- Choose an unchecked article you'd like to translate. +- Add a comment with the article title to the issue, e.g. `An Introduction to JavaScript`. + - Our bot will mark it in the issue, for everyone to know that you're translating it. + - Your comment should contain only the title. +- Fork the repository, translate and send a PR when done. + - PR title should match article title, the bot will write it's number into the issue. -## Contributions +Please kindly allow maintainers to review and merge or request changes in your translation. + +If maintainers do not respond, or if you'd like to become a maintainer, write us at the [main repo](https://github.com/javascript-tutorial/en.javascript.info/issues/new). + +**Let others know what you're translating, in message boards or chats in your language. Invite them to join!** -We'd also like to collaborate on the tutorial with other people. +🎉 Thank you! -Something's wrong? A topic is missing? Explain it to people, add as PR 👏 +Your name and the contribution size will appear in the "About project" page when the translation gets published. -**You can edit the text in any editor.** The tutorial uses enhanced "markdown" format, easy to grasp. And if you want to see how it looks on-site, there's a server to run the tutorial locally at . - -The list of contributors is available at . +P.S. The full list of languages can be found at . ## Structure -Every chapter, article or a task has its folder. +Every chapter, an article or a task resides in its own folder. + +The folder is named `N-url`, where `N` – is the number for sorting (articles are ordered), and `url` is the URL-slug on the site. + +The folder has one of files: + +- `index.md` for a section, +- `article.md` for an article, +- `task.md` for a task formulation (+`solution.md` with the solution text if any). + +A file starts with the `# Title Header`, and then the text in Markdown-like format, editable in a simple text editor. + +Additional resources and examples for the article or the task, are also in the same folder. + +## Translation Tips + +Please keep line breaks and paragraphs "as is": don't add newlines and don't remove existing ones. Makes it easy to merge future changes from the English version into the translation. + +If you see that the English version can be improved – great, please send a PR to it. + +### Terms + +- Some specification terms are not to be translated, e.g. "Function Declaration" can be left "as is". +- For other terms like `resolved promise`, `slash`, `regexp`, and so on - look for a glossary, hopefully there's one for your language already. If not, look for translations in manuals, such as [MDN](https://developer.mozilla.org/en-US/). + + +### Terms with meaning + +In English many terms have an obvious meaning. For a person who doesn't understand English, there's no such meaning. + +Please keep that in mind, sometimes explanations or additional translations are needed, e.g. + +```md +`ReadableStream` objects allows to read data chunk-by-chunk. +``` + +```md +`ReadableStream` ("flujo legible") objeto ... +``` + +### Text in Code Blocks + +- Translate comments. +- Translate user-messages and example strings. +- Don't translate variables, classes, identifiers. +- Ensure that the code works after the translation :) + +Example: + +```js +// Example +const text = "Hello, world"; +document.querySelector('.hello').innerHTML = text; +``` + +✅ DO (translate comment): + +```js +// Ejemplo +const text = 'Hola mundo'; +document.querySelector('.hello').innerHTML = text; +``` + +❌ DON'T (translate class): -The folder is named like `N-url`, where `N` is a number for the sorting purposes and `url` is the URL part with title of the material. +```js +// Ejemplo +const text = 'Hola mundo'; +// ".hello" is a class +// DO NOT TRANSLATE +document.querySelector('.hola').innerHTML = text; +``` -The type of the material is defined by the file inside the folder: +Please note, that sometimes code is followed by pictures, and if you translate text `Hello` -> `Hola` in the code, you need to translate text in picturess as well. - - `index.md` stands for a chapter - - `article.md` stands for an article - - `task.md` stands for a task (solution must be provided in `solution.md` file aswell) +In that case it's probably easier not to translate such text. See more about translating images later. -Each of these files starts from the `# Main header`. -It's very easy to add something new. +### External Links + +If an external link is to Wikipedia, e.g. `https://en.wikipedia.org/wiki/JavaScript`, and a version of that article exists in your language that is of decent quality, link to that version instead. + +Example: + +```md +[JavaScript](https://en.wikipedia.org/wiki/JavaScript) is a programming language. +``` + +✅ OK (en -> es): + +```md +[JavaScript](https://es.wikipedia.org/wiki/JavaScript) es un lenguaje de programación. +``` + +For links to MDN, a partially translated version is ok. + +If a linked article has no translated version, leave the link "as is". + +### Metadata + +Some files, usually tasks, have YAML metadata at the top, delimited by `---`: + +```md +importance: 5 --- -♥ -Ilya Kantor @iliakan +... +``` + +Please don't translate "importance" (and other top metadata). + +### Anchors + +Some headers have `[#anchor]` at the end, e.g. + +```md +## Spread operator [#spread-operator] +``` + +Please don't translate or remove the `[#...]` part, it's for URL anchors. + + +### Images + +Most illustrations use SVG format, the text in there can be replaced with a translated variant. + +The translated text is in `images.yml` file in the tutorial root. + +The file format is YAML: +```yaml +image.svg: # image file + "hello world": # English phrase + text: "Hola mundo" # translation + position: "centre" # "center" or "right", if needed to center or right-align the translation +``` + +## Running locally + +You can run the tutorial server locally to see how the translation looks. + +The server and install instructions are at . From db4a88097469307ee93c3f54545857236518fa99 Mon Sep 17 00:00:00 2001 From: Ilya Kantor Date: Thu, 29 Oct 2020 21:46:52 +0300 Subject: [PATCH 2/7] WIP --- .../01-hello-javascript/article.md | 33 ++ .../01-hello-javascript/javascript-engine.svg | 1 + 1-js/01-getting-started/02-basics/article.md | 406 ++++++++++++++++++ .../02-basics/use-strict.svg | 1 + .../02-basics/variable-change.svg | 1 + .../02-basics/variable-copy-value.svg | 1 + .../01-getting-started/02-basics/variable.svg | 1 + 1-js/01-getting-started/1-intro/article.md | 121 ------ .../1-intro/limitations.svg | 1 - .../2-manuals-specifications/article.md | 42 -- .../3-code-editors/article.md | 46 -- 1-js/01-getting-started/4-devtools/article.md | 63 --- 1-js/01-getting-started/4-devtools/bug.html | 17 - 1-js/01-getting-started/4-devtools/chrome.png | Bin 42131 -> 0 bytes .../4-devtools/[email protected] | Bin 69383 -> 0 bytes 1-js/01-getting-started/4-devtools/safari.png | Bin 109313 -> 0 bytes .../4-devtools/[email protected] | Bin 272413 -> 0 bytes 1-js/02-first-steps/04-variables/article.md | 2 +- .../04-variables/variable-change.svg | 1 - 1-js/02-first-steps/04-variables/variable.svg | 1 - .../02-object-copy/variable-copy-value.svg | 2 +- figures.sketch | Bin 9539299 -> 9567064 bytes 22 files changed, 446 insertions(+), 294 deletions(-) create mode 100644 1-js/01-getting-started/01-hello-javascript/article.md create mode 100644 1-js/01-getting-started/01-hello-javascript/javascript-engine.svg create mode 100644 1-js/01-getting-started/02-basics/article.md create mode 100644 1-js/01-getting-started/02-basics/use-strict.svg create mode 100644 1-js/01-getting-started/02-basics/variable-change.svg create mode 100644 1-js/01-getting-started/02-basics/variable-copy-value.svg create mode 100644 1-js/01-getting-started/02-basics/variable.svg delete mode 100644 1-js/01-getting-started/1-intro/article.md delete mode 100644 1-js/01-getting-started/1-intro/limitations.svg delete mode 100644 1-js/01-getting-started/2-manuals-specifications/article.md delete mode 100644 1-js/01-getting-started/3-code-editors/article.md delete mode 100644 1-js/01-getting-started/4-devtools/article.md delete mode 100644 1-js/01-getting-started/4-devtools/bug.html delete mode 100644 1-js/01-getting-started/4-devtools/chrome.png delete mode 100644 1-js/01-getting-started/4-devtools/[email protected] delete mode 100644 1-js/01-getting-started/4-devtools/safari.png delete mode 100644 1-js/01-getting-started/4-devtools/[email protected] delete mode 100644 1-js/02-first-steps/04-variables/variable-change.svg delete mode 100644 1-js/02-first-steps/04-variables/variable.svg diff --git a/1-js/01-getting-started/01-hello-javascript/article.md b/1-js/01-getting-started/01-hello-javascript/article.md new file mode 100644 index 0000000000..76e055756d --- /dev/null +++ b/1-js/01-getting-started/01-hello-javascript/article.md @@ -0,0 +1,33 @@ +# Hello, JavaScript! + +The programs in JavaScript are called *scripts*. They can be embedded right into HTML using ` +``` + +JavaScript can execute not only in a browser, but also on a server, or actually on any device that has a special program called [the JavaScript engine](https://en.wikipedia.org/wiki/JavaScript_engine). + +Browsers have built-in JavaScript engines, so they can run scripts. + +We can also run scripts using [Node.js](https://nodejs.org), it's commonly used to build server-side applications. + +Depending on the environment, JavaScript may provide platform-specific functionality. + +- In a web browser, JavaScript can manipulate the web-page, send network requests, show messages and so on. +- Node.js allows to run a web-server. + +...And so on. Even a coffee machine may include its own JavaScript engine, that could allow us to program its recipes. + + + +In this tutorial we concentrate on the "core JavaScript", that's the same everywhere.** + +After you learn it, you can go in any direction: learn browser functionality, how to write servers and so on. + +Please turn the page to start learning JavaScript! diff --git a/1-js/01-getting-started/01-hello-javascript/javascript-engine.svg b/1-js/01-getting-started/01-hello-javascript/javascript-engine.svg new file mode 100644 index 0000000000..493aef701f --- /dev/null +++ b/1-js/01-getting-started/01-hello-javascript/javascript-engine.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/1-js/01-getting-started/02-basics/article.md b/1-js/01-getting-started/02-basics/article.md new file mode 100644 index 0000000000..80c8d039d4 --- /dev/null +++ b/1-js/01-getting-started/02-basics/article.md @@ -0,0 +1,406 @@ + +# Basic concepts + +Let's take a piece of JavaScript code and discuss it line by line. + +Please don't hesitate to open "read more" sections below. They aren't strictly required, but contain valueable information. + +```js run +"use strict"; + +let message = "Hello!"; + +alert(message); +``` + +Click the "run" icon â–· in the right-upper corner to see how it works. + +Now we'll go over it line by line. + +## Strict mode + +The first line: + +```js +"use strict"; +``` + +The code starts with the special directive: `"use strict"`. + +To understand what it means, let's make a short dive into the history of JavaScript. + +JavaScript appeared many years ago, in 1995. For a long time, it evolved without compatibility issues. New features were added to the language while old functionality didn't change. + +That had the benefit of never breaking existing code. But the downside was that any mistake or an imperfect decision made by JavaScript's creators got stuck in the language forever. + +This was the case until 2009, when the 5th version of the standard appeared. It added new features to the language and modified some of the existing ones. + +Now the important part. + +**To keep the old code working, these modernizations are off by default.** We need to explicitly enable them with a special directive: `"use strict"` + +With that directive on top the script runs in so-called "strict mode". Or, we'd better say "modern mode", because that's what it essentially is. + + + +Some JavaScript features enable strict mode automatically, e.g. classes and modules, so that we don't need to write `"use strict"` for them. We'll cover these features later. + +**Here, in the tutorial, we'll always use strict mode, unless explicitly stated otherwise.** + +We're studying modern JavaScript after all. But you'll also see notes about how things work without `use strict`, just in case you come across an old script. + +## Variables + +A [variable](https://en.wikipedia.org/wiki/Variable_(computer_science)) is a "named storage" for data. We can use variables to store goodies, visitors, and so on. + +The second line declares (creates) a variable with the name `message` and stores the string `"John"` in it: + +```js +let message = "Hello!"; +``` + +We could also split this line into two: + +```js +let message; +message = "Hello!"; +``` + +Here, we first declare the variable with `let message`, and then assign the value. + +We can easily grasp the concept of a "variable" if we imagine it as a "box" for data, with a uniquely-named sticker on it. + +For instance, the variable `message` can be imagined as a box labeled `"message"` with the value `"Hello!"` in it: + + + +We can put any value in the box. + +We can also change it as many times as we want: +```js +let message; + +message = "Hello!"; + +message = "World!"; // value changed +``` + +When the value is changed, the old data is removed from the variable: + + + +We can also declare multiple variables and copy data from one into another. + +```js run +let hello = "Hello!"; + +let message; + +*!* +// copy the value "Hello!" from hello into message +message = hello; +*/!* +``` + +Now we have two variables, both store the same string: + + + +````warn header="Re-declaration triggers an error" +A variable can be declared only once. + +A repeated declaration of the same variable is an error: + +```js run +let message = "One"; + +// repeated 'let' leads to an error +let message = "Two"; // SyntaxError: 'message' has already been declared +``` +So, we should declare a variable once and then refer to it without `let`. +```` + +````warn header="Omitting `let` is possible without `use strict`" +In the old times, it was possible to create a variable by a mere assignment of the value without using `let`. This still works now if the script runs in the "compatibility mode", without `use strict`: + +```js run no-strict +// note: no "use strict" in this example + +num = 5; // the variable "num" is created if it didn't exist + +alert(num); // 5 +``` + +This is a bad practice and would cause an error in strict mode. +```` + +### Variable naming + +There are two limitations on variable names in JavaScript: + +1. The name must contain only letters, digits, or the symbols `$` and `_`. +2. The first character must not be a digit. + +Examples of valid names: + +```js +let userName; +let test123; +``` + +When the name contains multiple words, [camelCase](https://en.wikipedia.org/wiki/CamelCase) is commonly used. That is: words go one after another, each word after the first one starts with a capital letter: `myVeryLongName`. + +Examples of incorrect variable names: + +```js no-beautify +let 1a; // cannot start with a digit + +let my-name; // hyphens '-' aren't allowed in the name +``` + +```smart header="Case matters" +Variables named `apple` and `AppLE` are two different variables. +``` + +````smart header="Non-Latin letters are allowed, but not recommended" +It is possible to use any language, including cyrillic letters or even hieroglyphs, like this: + +```js +let имя = "..."; +let 我 = "..."; +``` + +Technically, there is no error here. Such names are allowed, but there is an international convention to use English in variable names. Even if you're writing a small script, it may have a long life ahead. People from other countries may need to read it in the future. +```` + +````warn header="Reserved names" +There is a [list of reserved words](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Lexical_grammar#Keywords), which cannot be used as variable names because they are used by the language itself. + +For example: `let`, `class`, `return`, and `function` are reserved. + +The code below gives a syntax error: + +```js run no-beautify +let let = 5; // can't name a variable "let", error! +let return = 5; // also can't name it "return", error! +``` +```` + +### Other ways to declare a variable + +Besides `let`, there are two other keywords that declare a variable: + +- `var` (e.g. `var message`) -- the outdated way to declare a variable, you can meet it in really old scripts. + Please don't use it. +- `const` (e.g. `const message`) -- declares a *constant* variable. + +A constant variable must be declared with the initial value, and afterwards it can't be reassigned. + +For example: +```js run +const birthday = "18.04.1982"; + +birthday = "01.01.1970"; // Error: Assignment to constant variable. +``` + +A person might change their name, but not the birthday. The idea of `const` is to let everyone (including the JavaScript engine)¸know about it. + +## Statements and semicolons + +The third line of our code is: + +```js +alert(message); +``` + + +