docs: translate comparing-observables.md (#57)

* docs: keep the english version of comparing-observables.md file as *.en.md file

aio/content/guide/comparing-observables.en.md

@@ -0,0 +1,318 @@
+# Observables compared to other techniques
+
+You can often use observables instead of promises to deliver values asynchronously. Similarly, observables can take the place of event handlers. Finally, because observables deliver multiple values, you can use them where you might otherwise build and operate on arrays.
+
+Observables behave somewhat differently from the alternative techniques in each of these situations, but offer some significant advantages. Here are detailed comparisons of the differences.
+
+## Observables compared to promises
+
+Observables are often compared to promises. Here are some key differences:
+
+* Observables are declarative; computation does not start until subscription. Promises execute immediately on creation. This makes observables useful for defining recipes that can be run whenever you need the result.
+
+* Observables provide many values. Promises provide one. This makes observables useful for getting multiple values over time.
+
+* Observables differentiate between chaining and subscription. Promises only have `.then()` clauses. This makes observables useful for creating complex transformation recipes to be used by other part of the system, without causing the work to be executed.
+
+* Observables `subscribe()` is responsible for handling errors. Promises push errors to the child promises. This makes observables useful for centralized and predictable error handling.
+
+
+### Creation and subscription
+
+* Observables are not executed until a consumer subscribes. The `subscribe()` executes the defined behavior once, and it can be called again. Each subscription has its own computation. Resubscription causes recomputation of values.
+
+  <code-example 
+    path="comparing-observables/src/observables.ts" 
+    header="src/observables.ts (observable)" 
+    region="observable">
+  </code-example>
+
+* Promises execute immediately, and just once. The computation of the result is initiated when the promise is created. There is no way to restart work. All `then` clauses (subscriptions) share the same computation.
+
+  <code-example 
+    path="comparing-observables/src/promises.ts" 
+    header="src/promises.ts (promise)"
+    region="promise">
+  </code-example>
+
+### Chaining
+
+* Observables differentiate between transformation function such as a map and subscription. Only subscription activates the subscriber function to start computing the values.
+
+  <code-example 
+    path="comparing-observables/src/observables.ts" 
+    header="src/observables.ts (chain)" 
+    region="chain">
+  </code-example>
+
+* Promises do not differentiate between the last `.then` clauses (equivalent to subscription) and intermediate `.then` clauses (equivalent to map).
+
+  <code-example 
+    path="comparing-observables/src/promises.ts"
+    header="src/promises.ts (chain)" 
+    region="chain">
+  </code-example>
+
+### Cancellation
+
+* Observable subscriptions are cancellable. Unsubscribing removes the listener from receiving further values, and notifies the subscriber function to cancel work.
+
+  <code-example 
+    path="comparing-observables/src/observables.ts" 
+    header="src/observables.ts (unsubcribe)" 
+    region="unsubscribe">
+  </code-example>
+
+* Promises are not cancellable.
+
+### Error handling
+
+* Observable execution errors are delivered to the subscriber's error handler, and the subscriber automatically unsubscribes from the observable.
+
+  <code-example 
+    path="comparing-observables/src/observables.ts" 
+    header="src/observables.ts (error)"
+    region="error">
+  </code-example>
+
+* Promises push errors to the child promises.
+
+  <code-example 
+    path="comparing-observables/src/promises.ts" 
+    header="src/promises.ts (error)"
+    region="error">
+  </code-example>
+
+### Cheat sheet
+
+The following code snippets illustrate how the same kind of operation is defined using observables and promises.
+
+<table>
+  <thead>
+    <tr>
+      <th>Operation</th>
+      <th>Observable</th>
+      <th>Promise</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>Creation</td>
+      <td>
+        <pre>
+new Observable((observer) => {
+  observer.next(123);
+});</pre>
+      </td>
+      <td>
+        <pre>
+new Promise((resolve, reject) => {
+  resolve(123);
+});</pre>
+      </td>
+    </tr>
+    <tr>
+      <td>Transform</td>
+      <td><pre>obs.pipe(map((value) => value * 2));</pre></td>
+      <td><pre>promise.then((value) => value * 2);</pre></td>
+    </tr>
+    <tr>
+      <td>Subscribe</td>
+      <td>
+        <pre>
+sub = obs.subscribe((value) => {
+  console.log(value)
+});</pre>
+      </td>
+      <td>
+        <pre>
+promise.then((value) => {
+  console.log(value);
+});</pre>
+      </td>
+    </tr>
+    <tr>
+      <td>Unsubscribe</td>
+      <td><pre>sub.unsubscribe();</pre></td>
+      <td>Implied by promise resolution.</td>
+    </tr>
+  </tbody>
+</table>
+
+## Observables compared to events API
+
+Observables are very similar to event handlers that use the events API. Both techniques define notification handlers, and use them to process multiple values delivered over time. Subscribing to an observable is equivalent to adding an event listener. One significant difference is that you can configure an observable to transform an event before passing the event to the handler.
+
+Using observables to handle events and asynchronous operations can have the advantage of greater consistency in contexts such as HTTP requests.
+
+Here are some code samples that illustrate how the same kind of operation is defined using observables and the events API.
+
+<table>
+  <tr>
+    <th></th>
+    <th>Observable</th>
+    <th>Events API</th>
+  </tr>
+  <tr>
+    <td>Creation & cancellation</td>
+    <td>
+<pre>// Setup
+let clicks$ = fromEvent(buttonEl, ‘click’);
+// Begin listening
+let subscription = clicks$
+  .subscribe(e => console.log(‘Clicked’, e))
+// Stop listening
+subscription.unsubscribe();</pre>
+   </td>
+   <td>
+<pre>function handler(e) {
+  console.log(‘Clicked’, e);
+}
+// Setup & begin listening
+button.addEventListener(‘click’, handler);
+// Stop listening
+button.removeEventListener(‘click’, handler);
+</pre>
+    </td>
+  </tr>
+  <tr>
+    <td>Subscription</td>
+    <td>
+<pre>observable.subscribe(() => {
+  // notification handlers here
+});</pre>
+    </td>
+    <td>
+<pre>element.addEventListener(eventName, (event) => {
+  // notification handler here
+});</pre>
+    </td>
+  </tr>
+  <tr>
+    <td>Configuration</td>
+    <td>Listen for keystrokes, but provide a stream representing the value in the input.
+<pre>fromEvent(inputEl, 'keydown').pipe(
+  map(e => e.target.value)
+);</pre>
+    </td>
+    <td>Does not support configuration.
+<pre>element.addEventListener(eventName, (event) => {
+  // Cannot change the passed Event into another
+  // value before it gets to the handler
+});</pre>
+    </td>
+  </tr>
+</table>
+
+
+## Observables compared to arrays
+
+An observable produces values over time. An array is created as a static set of values. In a sense, observables are asynchronous where arrays are synchronous. In the following examples, ➞ implies asynchronous value delivery.
+
+<table>
+  <tr>
+    <th></th>
+    <th>Observable</th>
+    <th>Array</th>
+  </tr>
+  <tr>
+    <td>Given</td>
+    <td>
+      <pre>obs: ➞1➞2➞3➞5➞7</pre>
+      <pre>obsB: ➞'a'➞'b'➞'c'</pre>
+    </td>
+    <td>
+      <pre>arr: [1, 2, 3, 5, 7]</pre>
+      <pre>arrB: ['a', 'b', 'c']</pre>
+    </td>
+  </tr>
+  <tr>
+    <td><pre>concat()</pre></td>
+    <td>
+      <pre>concat(obs, obsB)</pre>
+      <pre>➞1➞2➞3➞5➞7➞'a'➞'b'➞'c'</pre>
+    </td>
+    <td>
+      <pre>arr.concat(arrB)</pre>
+      <pre>[1,2,3,5,7,'a','b','c']</pre>
+    </td>
+  </tr>
+  <tr>
+    <td><pre>filter()</pre></td>
+    <td>
+      <pre>obs.pipe(filter((v) => v>3))</pre>
+      <pre>➞5➞7</pre>
+    </td>
+    <td>
+      <pre>arr.filter((v) => v>3)</pre>
+      <pre>[5, 7]</pre>
+    </td>
+  </tr>
+  <tr>
+    <td><pre>find()</pre></td>
+    <td>
+      <pre>obs.pipe(find((v) => v>3))</pre>
+      <pre>➞5</pre>
+    </td>
+    <td>
+      <pre>arr.find((v) => v>3)</pre>
+      <pre>5</pre>
+    </td>
+  </tr>
+  <tr>
+    <td><pre>findIndex()</pre></td>
+    <td>
+      <pre>obs.pipe(findIndex((v) => v>3))</pre>
+      <pre>➞3</pre>
+    </td>
+    <td>
+      <pre>arr.findIndex((v) => v>3)</pre>
+      <pre>3</pre>
+    </td>
+  </tr>
+  <tr>
+    <td><pre>forEach()</pre></td>
+    <td>
+      <pre>obs.pipe(tap((v) => {
+  console.log(v);
+}))
+1
+2
+3
+5
+7</pre>
+    </td>
+    <td>
+      <pre>arr.forEach((v) => {
+  console.log(v);
+})
+1
+2
+3
+5
+7</pre>
+    </td>
+  </tr>
+  <tr>
+    <td><pre>map()</pre></td>
+    <td>
+      <pre>obs.pipe(map((v) => -v))</pre>
+      <pre>➞-1➞-2➞-3➞-5➞-7</pre>
+    </td>
+    <td>
+      <pre>arr.map((v) => -v)</pre>
+      <pre>[-1, -2, -3, -5, -7]</pre>
+    </td>
+  </tr>
+  <tr>
+    <td><pre>reduce()</pre></td>
+    <td>
+      <pre>obs.pipe(reduce((s,v)=> s+v, 0))</pre>
+      <pre>➞18</pre>
+    </td>
+    <td>
+      <pre>arr.reduce((s,v) => s+v, 0)</pre>
+      <pre>18</pre>
+    </td>
+  </tr>
+</table>

aio/content/guide/comparing-observables.md

@@ -1,25 +1,24 @@
-# Observables compared to other techniques
+# Observables en comparación con otras técnicas
 
-You can often use observables instead of promises to deliver values asynchronously. Similarly, observables can take the place of event handlers. Finally, because observables deliver multiple values, you can use them where you might otherwise build and operate on arrays.
+A menudo puedes usar observables en lugar de promesas para entregar valores de forma asíncrona. Del mismo modo, los observables pueden reemplazar a los controladores de eventos. Finalmente, porque los observables entregan múltiples valores, puedes usarlos donde de otro modo podrías construir y operar con arrays.
 
-Observables behave somewhat differently from the alternative techniques in each of these situations, but offer some significant advantages. Here are detailed comparisons of the differences.
+Los observables se comportan de manera algo diferente a las técnicas alternativas en cada una de estas situaciones, pero ofrecen algunas ventajas significativas. Aquí hay comparaciones detalladas de las diferencias.
 
-## Observables compared to promises
+## Observables en comparación con promesas
 
-Observables are often compared to promises. Here are some key differences:
+Los observables a menudo se comparan con las promesas. Aquí hay algunas diferencias clave:
 
-* Observables are declarative; computation does not start until subscription. Promises execute immediately on creation. This makes observables useful for defining recipes that can be run whenever you need the result.
+* Los observables son declarativos; La ejecución no comienza hasta la suscripción. Las promesas se ejecutan inmediatamente después de la creación. Esto hace que los observables sean útiles para definir recetas que se pueden ejecutar cuando necesites el resultado.
 
-* Observables provide many values. Promises provide one. This makes observables useful for getting multiple values over time.
+* Los observables proporcionan muchos valores. Las promesas proporcionan un valor. Esto hace que los observables sean útiles para obtener múltiples valores a lo largo del tiempo.
 
-* Observables differentiate between chaining and subscription. Promises only have `.then()` clauses. This makes observables useful for creating complex transformation recipes to be used by other part of the system, without causing the work to be executed.
+* Los observables diferencian entre encadenamiento y suscripción. Las promesas solo tienen cláusulas `.then ()`. Esto hace que los observables sean útiles para crear recetas de transformación complejas para ser utilizadas por otra parte del sistema, sin que el trabajo se ejecute.
 
-* Observables `subscribe()` is responsible for handling errors. Promises push errors to the child promises. This makes observables useful for centralized and predictable error handling.
+* Observables `subscribe()` es responsable de manejar los errores. Las promesas empujan los errores a promesas hijas. Esto hace que los observables sean útiles para el manejo centralizado y predecible de errores.
 
+### Creación y suscripción
 
-### Creation and subscription
+* Los observables no se ejecutan hasta que un consumidor se suscribe. El `subscribe()` ejecuta el comportamiento definido una vez, y se puede volver a llamar. Cada suscripción tiene su propia computación. La resuscripción provoca la recomputación de los valores.
-
-* Observables are not executed until a consumer subscribes. The `subscribe()` executes the defined behavior once, and it can be called again. Each subscription has its own computation. Resubscription causes recomputation of values.
 
   <code-example
     path="comparing-observables/src/observables.ts"
@@ -27,7 +26,7 @@ Observables are often compared to promises. Here are some key differences:
     region="observable">
   </code-example>
 
-* Promises execute immediately, and just once. The computation of the result is initiated when the promise is created. There is no way to restart work. All `then` clauses (subscriptions) share the same computation.
+* Las promesas se ejecutan de inmediato, y solo una vez. La computación del resultado se inicia cuando se crea la promesa. No hay forma de reiniciar el trabajo. Todas las cláusulas `then` (suscripciones) comparten la misma computación.
 
   <code-example
     path="comparing-observables/src/promises.ts"
@@ -35,9 +34,9 @@ Observables are often compared to promises. Here are some key differences:
     region="promise">
   </code-example>
 
-### Chaining
+### Encadenamiento
 
-* Observables differentiate between transformation function such as a map and subscription. Only subscription activates the subscriber function to start computing the values.
+* Los observables diferencian entre la función de transformación, como `map` y `subscription`. Solo la suscripción activa la función de suscriptor para comenzar a calcular los valores.
 
   <code-example
     path="comparing-observables/src/observables.ts"
@@ -45,7 +44,7 @@ Observables are often compared to promises. Here are some key differences:
     region="chain">
   </code-example>
 
-* Promises do not differentiate between the last `.then` clauses (equivalent to subscription) and intermediate `.then` clauses (equivalent to map).
+* Las promesas no diferencian entre las últimas cláusulas `.then` (equivalentes al subscription) y las cláusulas intermedias `.then` (equivalentes al map).
 
   <code-example
     path="comparing-observables/src/promises.ts"
@@ -53,9 +52,9 @@ Observables are often compared to promises. Here are some key differences:
     region="chain">
   </code-example>
 
-### Cancellation
+### Cancelación
 
-* Observable subscriptions are cancellable. Unsubscribing removes the listener from receiving further values, and notifies the subscriber function to cancel work.
+* Las suscripciones de los observables son cancelables. La cancelación de la suscripción evita que el oyente reciba más valores y notifica a la función del suscriptor que cancele el trabajo.
 
   <code-example
     path="comparing-observables/src/observables.ts"
@@ -63,11 +62,11 @@ Observables are often compared to promises. Here are some key differences:
     region="unsubscribe">
   </code-example>
 
-* Promises are not cancellable.
+* Las promesas no son cancelables.
 
-### Error handling
+### Manejo de errores
 
-* Observable execution errors are delivered to the subscriber's error handler, and the subscriber automatically unsubscribes from the observable.
+* Los errores de ejecución en observables se entregan al controlador de errores del suscriptor, y el suscriptor cancela automáticamente la suscripción del observable.
 
   <code-example
     path="comparing-observables/src/observables.ts"
@@ -75,7 +74,7 @@ Observables are often compared to promises. Here are some key differences:
     region="error">
   </code-example>
 
-* Promises push errors to the child promises.
+* Las promesas empujan los errores a las promesas hijas.
 
   <code-example
     path="comparing-observables/src/promises.ts"
@@ -83,9 +82,9 @@ Observables are often compared to promises. Here are some key differences:
     region="error">
   </code-example>
 
-### Cheat sheet
+### Hoja de trucos
 
-The following code snippets illustrate how the same kind of operation is defined using observables and promises.
+Los siguientes fragmentos de código ilustran cómo se define el mismo tipo de operación utilizando observables y promesas.
 
 <table>
   <thead>
@@ -139,13 +138,13 @@ promise.then((value) => {
   </tbody>
 </table>
 
-## Observables compared to events API
+## Observables en comparación con eventos API
 
-Observables are very similar to event handlers that use the events API. Both techniques define notification handlers, and use them to process multiple values delivered over time. Subscribing to an observable is equivalent to adding an event listener. One significant difference is that you can configure an observable to transform an event before passing the event to the handler.
+Los observables son muy similares a los controladores de eventos que usan la API de eventos. Ambas técnicas definen manejadores de notificaciones y las utilizan para procesar múltiples valores entregados a lo largo del tiempo. Suscribirse a un observable es equivalente a agregar un detector de eventos. Una diferencia significativa es que puedes configurar un observable para transformar un evento antes de pasar el evento al controlador.
 
-Using observables to handle events and asynchronous operations can have the advantage of greater consistency in contexts such as HTTP requests.
+El uso de observables para manejar eventos y operaciones asíncronas puede tener la ventaja de una mayor coherencia en contextos como las solicitudes HTTP.
 
-Here are some code samples that illustrate how the same kind of operation is defined using observables and the events API.
+Aquí hay algunos ejemplos de código que ilustran cómo se define el mismo tipo de operación usando observables y la API de eventos.
 
 <table>
   <tr>
@@ -205,9 +204,9 @@ button.removeEventListener(‘click’, handler);
 </table>
 
 
-## Observables compared to arrays
+## Observables en comparación con arrays
 
-An observable produces values over time. An array is created as a static set of values. In a sense, observables are asynchronous where arrays are synchronous. In the following examples, ➞ implies asynchronous value delivery.
+Un observable produce valores a lo largo del tiempo. Se crea un array como un conjunto estático de valores. En cierto sentido, los observables son asíncronos mientras que los arrays son síncronos. En los siguientes ejemplos, ➞ implica entrega de valor asíncrono.
 
 <table>
   <tr>