translate: signals debounced and effect guides (Angular 22.1) (#210)

Translate guide/signals/debounced.md and guide/signals/effect.md into
Spanish and keep the English originals as .en.md backups.

Fixes #186

Author: oidacra

adev-es/src/content/guide/signals/debounced.en.md

@@ -0,0 +1,85 @@
+# Debouncing signals with `debounced`
+
+IMPORTANT: `debounced` is [experimental](reference/releases#experimental). It's ready for you to try, but it might change before it is stable.
+
+Use `debounced` to delay reacting to a signal's value until it stops changing. It returns a `Resource` whose value reflects the debounced value of the source signal.
+
+```angular-ts
+import {debounced, resource, signal} from '@angular/core';
+
+@Component({
+  template: `
+    <input (input)="query.set($event.target.value)" />
+
+    @if (results.isLoading()) {
+      <p>Searching…</p>
+    }
+    @for (item of results.value(); track item.id) {
+      <li>{{ item.name }}</li>
+    }
+  `,
+})
+export class Search {
+  query = signal('');
+
+  debouncedQuery = debounced(this.query, 300);
+
+  results = resource({
+    params: () => this.debouncedQuery.value(),
+    loader: ({params}) => fetchResults(params),
+  });
+}
+```
+
+`debounced` takes the source signal and a wait duration in milliseconds. The returned resource's `value()` always contains the last settled value, and `status()` tells you whether a new value is still pending.
+
+## Status during debounce
+
+While the debounce timer is counting down, `status()` is `'loading'` and `value()` returns the previously resolved value. When the timer expires, the resource settles to `'resolved'`. If the source signal throws, the resource enters `'error'` immediately; no timer runs.
+
+See [Resource status](/guide/signals/resource#resource-status) for the full list of statuses and their `value()` behavior.
+
+## Custom wait function
+
+Instead of a millisecond duration, you can pass a function that returns a `Promise<void>`. The resource resolves when the promise resolves. If the source signal changes before the promise settles, Angular discards the previous promise and starts a new one.
+
+```ts
+debouncedQuery = debounced(query, (value, lastSnapshot) => {
+  // Retry immediately after an error rather than making the user wait again.
+  if (lastSnapshot.status === 'error') return;
+  // Short queries get a longer delay—the user is likely still typing.
+  const ms = value.length < 3 ? 500 : 200;
+  return new Promise<void>((resolve) => setTimeout(resolve, ms));
+});
+```
+
+See the `DebounceTimer` type in the API reference for details.
+
+## Equality
+
+By default, `debounced` uses `Object.is` to compare values.
+
+Provide a custom equality function with the `equal` option when the default identity check is too strict:
+
+```ts
+debouncedFilter = debounced(filter, 200, {
+  equal: (a, b) => a.category === b.category && a.minPrice === b.minPrice,
+});
+```
+
+## Injection context
+
+`debounced` must be called inside an [injection context](guide/di/dependency-injection-context). Angular automatically destroys the debounced resource and cancels any pending timer when the injector is destroyed.
+
+To use `debounced` outside of an injection context, pass an explicit `Injector` via the options:
+
+```ts
+@Service()
+export class SearchService {
+  private injector = inject(Injector);
+
+  createDebouncedQuery(query: Signal<string>): Resource<string> {
+    return debounced(query, 300, {injector: this.injector});
+  }
+}
+```

adev-es/src/content/guide/signals/debounced.md

@@ -1,8 +1,8 @@
-# Debouncing signals with `debounced`
+# Aplicar debounce a signals con `debounced`
 
-IMPORTANT: `debounced` is [experimental](reference/releases#experimental). It's ready for you to try, but it might change before it is stable.
+IMPORTANT: `debounced` es [experimental](reference/releases#experimental). Está listo para que lo pruebes, pero podría cambiar antes de ser estable.
 
-Use `debounced` to delay reacting to a signal's value until it stops changing. It returns a `Resource` whose value reflects the debounced value of the source signal.
+Usa `debounced` para retrasar la reacción al valor de una signal hasta que deje de cambiar. Devuelve un `Resource` cuyo valor refleja el valor con debounce de la signal fuente.
 
 ```angular-ts
 import {debounced, resource, signal} from '@angular/core';
@@ -12,7 +12,7 @@ import {debounced, resource, signal} from '@angular/core';
     <input (input)="query.set($event.target.value)" />
 
     @if (results.isLoading()) {
-      <p>Searching…</p>
+      <p>Buscando…</p>
     }
     @for (item of results.value(); track item.id) {
       <li>{{ item.name }}</li>
@@ -31,47 +31,47 @@ export class Search {
 }
 ```
 
-`debounced` takes the source signal and a wait duration in milliseconds. The returned resource's `value()` always contains the last settled value, and `status()` tells you whether a new value is still pending.
+`debounced` recibe la signal fuente y una duración de espera en milisegundos. El `value()` del resource devuelto siempre contiene el último valor asentado, y `status()` te indica si un nuevo valor sigue pendiente.
 
-## Status during debounce
+## Estado durante el debounce {#status-during-debounce}
 
-While the debounce timer is counting down, `status()` is `'loading'` and `value()` returns the previously resolved value. When the timer expires, the resource settles to `'resolved'`. If the source signal throws, the resource enters `'error'` immediately; no timer runs.
+Mientras el temporizador del debounce está en cuenta regresiva, `status()` es `'loading'` y `value()` devuelve el valor resuelto anteriormente. Cuando el temporizador expira, el resource se asienta en `'resolved'`. Si la signal fuente lanza un error, el resource entra en `'error'` de inmediato; no se ejecuta ningún temporizador.
 
-See [Resource status](/guide/signals/resource#resource-status) for the full list of statuses and their `value()` behavior.
+Consulta [Estado del resource](/guide/signals/resource#resource-status) para ver la lista completa de estados y el comportamiento de `value()` en cada uno.
 
-## Custom wait function
+## Función de espera personalizada {#custom-wait-function}
 
-Instead of a millisecond duration, you can pass a function that returns a `Promise<void>`. The resource resolves when the promise resolves. If the source signal changes before the promise settles, Angular discards the previous promise and starts a new one.
+En lugar de una duración en milisegundos, puedes pasar una función que devuelva un `Promise<void>`. El resource se resuelve cuando la promesa se resuelve. Si la signal fuente cambia antes de que la promesa se asiente, Angular descarta la promesa anterior e inicia una nueva.
 
 ```ts
 debouncedQuery = debounced(query, (value, lastSnapshot) => {
-  // Retry immediately after an error rather than making the user wait again.
+  // Reintenta de inmediato tras un error en lugar de hacer que el usuario espere de nuevo.
   if (lastSnapshot.status === 'error') return;
-  // Short queries get a longer delay—the user is likely still typing.
+  // Las consultas cortas reciben un retraso mayor: probablemente el usuario sigue escribiendo.
   const ms = value.length < 3 ? 500 : 200;
   return new Promise<void>((resolve) => setTimeout(resolve, ms));
 });
 ```
 
-See the `DebounceTimer` type in the API reference for details.
+Consulta el tipo `DebounceTimer` en la referencia de la API para más detalles.
 
-## Equality
+## Igualdad {#equality}
 
-By default, `debounced` uses `Object.is` to compare values.
+Por defecto, `debounced` usa `Object.is` para comparar valores.
 
-Provide a custom equality function with the `equal` option when the default identity check is too strict:
+Proporciona una función de igualdad personalizada con la opción `equal` cuando la comprobación de identidad predeterminada sea demasiado estricta:
 
 ```ts
 debouncedFilter = debounced(filter, 200, {
   equal: (a, b) => a.category === b.category && a.minPrice === b.minPrice,
 });
 ```
 
-## Injection context
+## Contexto de inyección {#injection-context}
 
-`debounced` must be called inside an [injection context](guide/di/dependency-injection-context). Angular automatically destroys the debounced resource and cancels any pending timer when the injector is destroyed.
+`debounced` debe llamarse dentro de un [contexto de inyección](guide/di/dependency-injection-context). Angular destruye automáticamente el resource con debounce y cancela cualquier temporizador pendiente cuando se destruye el inyector.
 
-To use `debounced` outside of an injection context, pass an explicit `Injector` via the options:
+Para usar `debounced` fuera de un contexto de inyección, pasa un `Injector` explícito a través de las opciones:
 
 ```ts
 @Service()

adev-es/src/content/guide/signals/effect.en.md

@@ -0,0 +1,207 @@
+## Effects
+
+Signals are useful because they notify interested consumers when they change. An **effect** is an operation that runs whenever one or more signal values change. You can create an effect with the `effect` function:
+
+```ts
+import {effect} from '@angular/core';
+
+effect(() => {
+  console.log(`The current count is: ${count()}`);
+});
+```
+
+Effects always run **at least once.** When an effect runs, it tracks any signal value reads. Whenever any of these signal values change, the effect runs again. Similar to computed signals, effects keep track of their dependencies dynamically, and only track signals which were read in the most recent execution.
+
+Effects always execute **asynchronously**, during the change detection process.
+
+### Use cases for effects
+
+Effects should be the last API you reach for. Always prefer `computed()` for derived values and `linkedSignal()` for values that can be both derived and manually set. If you find yourself copying data from one signal to another with an effect, it's a sign you should move your source-of-truth higher up and use `computed()` or `linkedSignal()` instead. Effects are best for syncing signal state to imperative, non-signal APIs.
+
+TIP: There are no situations where effect is good, only situations where it is appropriate.
+
+- Logging signal values, either for analytics or as a debugging tool.
+- Keeping data in sync with different kinds of storage: `window.localStorage`, session storage, cookies, etc.
+- Adding custom DOM behavior that can't be expressed with template syntax.
+- Performing custom rendering to a `<canvas>` element, charting library, or other third party UI library.
+
+<docs-callout critical title="When not to use effects">
+Avoid using effects for propagation of state changes. This can result in `ExpressionChangedAfterItHasBeenChecked` errors, infinite circular updates, or unnecessary change detection cycles.
+
+Instead, use `computed` signals to model state that depends on other state.
+</docs-callout>
+
+### Injection context
+
+By default, you can only create an `effect()` within an [injection context](guide/di/dependency-injection-context) (where you have access to the `inject` function). The easiest way to satisfy this requirement is to call `effect` within a component, directive, or service `constructor`:
+
+```ts
+@Component(/* ... */)
+export class EffectiveCounter {
+  readonly count = signal(0);
+
+  constructor() {
+    // Register a new effect.
+    effect(() => {
+      console.log(`The count is: ${this.count()}`);
+    });
+  }
+}
+```
+
+To create an effect outside the constructor, you can pass an `Injector` to `effect` via its options:
+
+```ts
+@Component(/* ... */)
+export class EffectiveCounter {
+  readonly count = signal(0);
+  private injector = inject(Injector);
+
+  initializeLogging(): void {
+    effect(
+      () => {
+        console.log(`The count is: ${this.count()}`);
+      },
+      {injector: this.injector},
+    );
+  }
+}
+```
+
+### Execution of effects
+
+Angular implicitly defines two implicit behaviors for its effects depending on the context they were created in.
+
+A "View Effect" is an `effect` created in the context of a component instantiation. This includes effects created by services that are tied to component injectors.<br>
+A "Root Effect" is created in the context of a root provided service instantiation.
+
+The execution of both kinds of `effect` are tied to the change detection process.
+
+- "View effects" are executed _before_ their corresponding component is checked by the change detection process.
+- "Root effects" are executed prior to all components being checked by the change detection process.
+
+In both cases, if at least one of the effect dependencies changed during the effect execution, the effect will re-run before moving ahead on the change detection process.
+
+### Destroying effects
+
+When a component or directive is destroyed, Angular automatically cleans up any associated effects.
+
+An `effect` can be created in two different contexts that will affect when it's destroyed:
+
+- A "View effect" is destroyed when the component is destroyed.
+- A "Root effect" is destroyed when the application is destroyed.
+
+Effects return an `EffectRef`. You can use the ref's `destroy` method to manually dispose of an effect. You can combine this with the `manualCleanup` option when creating an effect to disable automatic cleanup. Be careful to actually destroy such effects when they're no longer required.
+
+### Effect cleanup functions
+
+When a component or directive is destroyed, Angular automatically cleans up any associated effects.
+Effects might start long-running operations, which you should cancel if the effect is destroyed or runs again before the first operation finished. When you create an effect, your function can optionally accept an `onCleanup` function as its first parameter. This `onCleanup` function lets you register a callback that is invoked before the next run of the effect begins, or when the effect is destroyed.
+
+```ts
+effect((onCleanup) => {
+  const user = currentUser();
+
+  const timer = setTimeout(() => {
+    console.log(`1 second ago, the user became ${user}`);
+  }, 1000);
+
+  onCleanup(() => {
+    clearTimeout(timer);
+  });
+});
+```
+
+## Side effects on DOM elements
+
+The `effect` function is a general-purpose tool for running code in reaction to signal changes. However, it runs _before_ the Angular updates the DOM. In some situations, you may need to manually inspect or modify the DOM, or integrate a 3rd-party library that requires direct DOM access.
+
+For these situations, you can use `afterRenderEffect`. It functions like `effect`, but runs after Angular has finished rendering and committed its changes to the DOM.
+
+```ts
+@Component(/* ... */)
+export class MyFancyChart {
+  chartData = input.required<ChartData>();
+  canvas = viewChild.required<ElementRef<HTMLCanvasElement>>('canvas');
+  chart: ChartInstance;
+
+  constructor() {
+    // Run a single time to create the chart instance
+    afterNextRender({
+      write: () => {
+        this.chart = initializeChart(this.canvas().nativeElement(), this.chartData());
+      },
+    });
+
+    // Re-run after DOM has been updated whenever `chartData` changes
+    afterRenderEffect(() => {
+      this.chart.updateData(this.chartData());
+    });
+  }
+}
+```
+
+In this example `afterRenderEffect` is used to update a chart created by a 3rd party library.
+
+TIP: You often don't need `afterRenderEffect` to check for DOM changes. APIs like `ResizeObserver`, `MutationObserver` and `IntersectionObserver` are preferred to `effect` or `afterRenderEffect` when possible.
+
+### Render phases
+
+Accessing the DOM and mutating it can impact the performance of your application, for example by triggering too many unnecessary [reflows](https://developer.mozilla.org/en-US/docs/Glossary/Reflow).
+
+To optimize those operations, `afterRenderEffect` offers four phases to group the callbacks and execute them in an optimized order.
+
+The phases are:
+
+| Phase            | Description                                                                                                                                                                                        |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `earlyRead`      | Use this phase to read from the DOM before a subsequent write callback, for example to perform custom layout that the browser doesn't natively support. Prefer the read phase if reading can wait. |
+| `write`          | Use this phase to write to the DOM. **Never** read from the DOM in this phase.                                                                                                                     |
+| `mixedReadWrite` | Use this phase to read from and write to the DOM simultaneously. Never use this phase if it is possible to divide the work among the other phases instead.                                         |
+| `read`           | Use this phase to read from the DOM. **Never** write to the DOM in this phase.                                                                                                                     |
+
+Using these phases helps prevent layout thrashing and ensures that your DOM operations are performed in a safe and efficient manner.
+
+You can specify the phase by passing an object with a `phase` property to `afterRender` or `afterNextRender`:
+
+```ts
+afterRenderEffect({
+  earlyRead: (cleanupFn) => {
+    /* ... */
+  },
+  write: (previousPhaseValue, cleanupFn) => {
+    /* ... */
+  },
+  mixedReadWrite: (previousPhaseValue, cleanupFn) => {
+    /* ... */
+  },
+  read: (previousPhaseValue, cleanupFn) => {
+    /* ... */
+  },
+});
+```
+
+CRITICAL: If you don't specify the phase, `afterRenderEffect` runs callbacks during the `mixedReadWrite` phase. This may worsen application performance by causing additional DOM reflows.
+
+#### Phase executions
+
+The `earlyRead` phase callback receives no parameters. Each subsequent phase receives the return value of the previous phase's callback as a Signal. You can use this to coordinate work across phases.
+
+Effects run in the following phase order:
+
+1. `earlyRead`
+2. `write`
+3. `mixedReadWrite`
+4. `read`
+
+If one of the phases modifies a signal value tracked by `afterRenderEffect`, the affected phases execute again.
+
+#### Cleanup
+
+Each phase provides a cleanup callback function as argument. The cleanup callbacks are executed when the `afterRenderEffect` is destroyed or before re-running phase effects.
+
+### Server-side rendering caveats
+
+`afterRenderEffect`, similarly to `afterNextRender`/`afterEveryRender`, only runs on the client.
+
+NOTE: Components are not guaranteed to be [hydrated](/guide/hydration) before the callback runs. You must use caution when directly reading or writing the DOM and layout.