Merge pull request #197 from alfiya-udc/master

Fetch: Download progress

Author: javascript-translate-bot

5-network/02-fetch-progress/article.md

@@ -1,54 +1,54 @@
 
-# Fetch: Download progress
+# Fetch: ход загрузки
 
-`Fetch` allows to track download progress, but not upload progress.
+`Fetch` позволяет отслеживать процесс получения данных. 
 
-Please note: there's currently no way for fetch to track upload progress. For that purpose, please use [XMLHttpRequest](info:xmlhttprequest).
+Заметим, на данный момент в `fetch` нет способа отследить прогресс отправки данных. Для этого используйте [XMLHttpRequest](info:xmlhttprequest).
 
-To track download progress, we can use `response.body` property. It's a "readable stream" -- a special object that provides body chunk-by-chunk, as it comes, so we can see how much is available at the moment.
+Если мы хотим отследить ход загрузки данных с сервера, можно использовать свойство `response.body`. Это так называемый "поток для чтения" (англ. `readable stream`) -- особый объект, который предоставляет тело ответа по частям, по мере поступления, так что мы можем увидеть, сколько уже получено. 
 
-Here's the sketch of code that uses it to read response:
+Вот пример кода, который использует этот объект для чтения ответа:
 
 ```js
-// instead of response.json() and other methods
+// вместо response.json() и других методов
 const reader = response.body.getReader();
 
-// infinite loop while the body is downloading
+// бесконечный цикл, пока идёт загрузка
 while(true) {
-  // done is true for the last chunk
-  // value is Uint8Array of the chunk bytes
+  // done становится true в последнем фрагменте
+  // value - Uint8Array из байтов каждого фрагмента
   const {done, value} = await reader.read();
 
   if (done) {
     break;
   }
 
-  console.log(`Received ${value.length} bytes`)
+  console.log(`Получено ${value.length} байт`)
 }
 ```
 
-So, we loop, while `await reader.read()` returns response chunks.
+Таким образом, цикл идёт, пока `await reader.read()` возвращает в ответе данные по частям.
 
-A chunk has two properties:
-- **`done`** -- true when the reading is complete.
-- **`value`** -- a typed array of bytes: `Uint8Array`.
+У возвращаемого фрагмента (англ. `chunk`) есть два свойства:
+- **`done`** -- `true`, когда чтение закончено.
+- **`value`** -- типизированный массив байтов: `Uint8Array`.
 
-To log the progress, we just need to count chunks.
+Чтобы пошагово отследить процесс, нам нужно всего лишь посчитать получившиеся фрагменты.
 
-Here's the full code to get response and log the progress, more explanations follow:
+Вот полный код, где в процессе получения ответа от сервера мы фиксируем, сколько данных пришло из каждой части.
 
 ```js run async
-// Step 1: start the fetch and obtain a reader
+// Шаг 1: начинаем обработку с помощью fetch и достаём ссылку на поток для чтения
 let response = await fetch('https://api.github.com/repos/javascript-tutorial/en.javascript.info/commits?per_page=100');
 
 const reader = response.body.getReader();
 
-// Step 2: get total length
+// Шаг 2: получаем длину контента
 const contentLength = +response.headers.get('Content-Length');
 
-// Step 3: read the data
-let receivedLength = 0; // length at the moment
-let chunks = []; // array of received binary chunks (comprises the body)
+// Шаг 3: считываем данные:
+let receivedLength = 0; // длину на данный момент
+let chunks = []; // массив полученных двоичных фрагментов (в нём будет тело ответа)
 while(true) {
   const {done, value} = await reader.read();
 
@@ -59,46 +59,46 @@ while(true) {
   chunks.push(value);
   receivedLength += value.length;
 
-  console.log(`Received ${receivedLength} of ${contentLength}`)
+  console.log(`Получено ${receivedLength} из ${contentLength}`)
 }
 
-// Step 4: concatenate chunks into single Uint8Array
+// Шаг 4: соединим фрагменты в общий типизированный массив Uint8Array
 let chunksAll = new Uint8Array(receivedLength); // (4.1)
 let position = 0;
 for(let chunk of chunks) {
 	chunksAll.set(chunk, position); // (4.2)
 	position += chunk.length;
 }
 
-// Step 5: decode into a string
+// Шаг 5: декодируем Uint8Array обратно в строку
 let result = new TextDecoder("utf-8").decode(chunksAll);
 
-// We're done!
+// Готово!
 let commits = JSON.parse(result);
 alert(commits[0].author.login);
 ```
 
-Let's explain that step-by-step:
+Разберёмся, что здесь произошло:
 
-1. We perform `fetch` as usual, but instead of calling `response.json()`, we obtain a stream reader `response.body.getReader()`.
+1. Мы обращаемся к `fetch` как обычно, но вместо вызова `response.json()` мы получаем доступ к потоку чтения `response.body.getReader()`.
 
-    Please note, we can't use both these methods to read the same response. Either use a reader or a response method to get the result.
-2. Prior to reading, we can figure out the full response length from the `Content-Length` header.
+    Обратите внимание, что мы не можем использовать одновременно оба эти метода для одного и того же ответа. Используйте либо обычный метод `response.json()`, либо чтение потока `response.body`.
+2. Ещё до чтения потока мы можем вычислить полную длину ответа из заголовка `Content-Length`.
 
-    It may be absent for cross-domain requests (see chapter <info:fetch-crossorigin>) and, well, technically a server doesn't have to set it. But usually it's at place.
-3. Call `await reader.read()` until it's done.
+    Она может отсутствовать в кросс-доменных запросах  (подробнее в разделе <info:fetch-crossorigin>) и, в общем-то, серверу необязательно её устанавливать. Тем не менее, обычно длина указана.
+3. Вызываем `await reader.read()` до окончания загрузки.
 
-    We gather response `chunks` in the array. That's important, because after the response is consumed, we won't be able to "re-read" it using `response.json()` or another way (you can try, there'll be an error).
-4. At the end, we have `chunks` -- an array of `Uint8Array` byte chunks. We need to join them into a single result. Unfortunately, there's no single method that concatenates those, so there's some code to do that:
-    1. We create `new Uint8Array(receivedLength)` -- a same-typed array with the combined length.
-    2. Then use `.set(chunk, position)` method to copy each `chunk` one after another in the resulting array.
-5. We have the result in `chunksAll`. It's a byte array though, not a string.
+    Всё, что получили, мы складываем по "кусочкам" в массив. Это важно, потому что после того, как ответ получен, мы уже не сможем "перечитать" его, используя `response.json()` или любой другой способ (попробуйте - будет ошибка).
+4. В самом конце у нас типизированный массив -- `Uint8Array`. В нём находятся фрагменты данных. Нам нужно их склеить, чтобы получить строку. К сожалению, для этого нет специального метода, но можно сделать, например, так:
+    1. Создаём `new Uint8Array(receivedLength)` -- массив того же типа заданной длины.
+    2. Используем `.set(chunk, position)` метод для копирования каждого фрагмента друг за другом в массив результатов.
+5. Наш результат теперь хранится в `chunksAll`. Это не строка, а байтовый массив.
 
-    To create a string, we need to interpret these bytes. The built-in [TextDecoder](info:text-decoder) does exactly that. Then we can `JSON.parse` it.
+    Чтобы получить именно строку, надо декодировать байты. Встроенный метод [TextDecoder](info:text-decoder) как раз этим и занимается. Потом мы можем распарсить её с помощью `JSON.parse`.
 
-What if we need binary content instead of JSON? That's even simpler. Instead of steps 4 and 5, we could make a blob of all chunks:
+Что если результат нам нужен в бинарном виде, а не в JSON-формате? Это ещё проще. Вместо шагов 4 и 5, мы создаём объект `Blob`:
 ```js
 let blob = new Blob(chunks);
 ```
 
-Once again, please note, that's not for upload progress (no way now), only for download progress.
+На всякий случай повторимся, что здесь мы рассмотрели, как отслеживать процесс получения данных с сервера, а не их отправки на сервер. Как отследить отправку `fetch` - пока нет способа.