Merge branch 'main' into 5.4.0

src/content/docs/en/editor-setup.mdx

@@ -83,41 +83,40 @@ To add support for formatting `.astro` files outside of the editor (e.g. CLI) or
     <PackageManagerTabs>
       <Fragment slot="npm">
       ```shell
-      npm install --save-dev prettier prettier-plugin-astro
+      npm install --save-dev --save-exact prettier prettier-plugin-astro
       ```
       </Fragment>
       <Fragment slot="pnpm">
       ```shell
-      pnpm add -D prettier prettier-plugin-astro
+      pnpm add --save-dev --save-exact prettier prettier-plugin-astro
       ```
       </Fragment>
       <Fragment slot="yarn">
       ```shell
-      yarn add --dev prettier prettier-plugin-astro
+      yarn add --dev --exact prettier prettier-plugin-astro
       ```
       </Fragment>
     </PackageManagerTabs>
 
-2. Create a `.prettierrc.mjs` config file at the root of your project and add `prettier-plugin-astro` to it.
+2. Create a `.prettierrc` configuration file (or `.prettierrc.json`, `.prettierrc.mjs`, or [other supported formats](https://prettier.io/docs/configuration)) in the root of your project and add `prettier-plugin-astro` to it.
 
     In this file, also manually specify the parser for Astro files.
 
-    ```js title=".prettierrc.mjs"
-    /** @type {import("prettier").Config} */
-    export default {
-      plugins: ['prettier-plugin-astro'],
-      overrides: [
+    ```json title=".prettierrc"
+    {
+      "plugins": ["prettier-plugin-astro"],
+      "overrides": [
         {
-          files: '*.astro',
-          options: {
-            parser: 'astro',
-          },
-        },
-      ],
-    };
+          "files": "*.astro",
+          "options": {
+            "parser": "astro",
+          }
+        }
+      ]
+    }
     ```
 
-3. Run the command `prettier . --write` in the terminal to format your files.
+3. Run the following command in your terminal to format your files.
 
     <PackageManagerTabs>
       <Fragment slot="npm">
@@ -132,7 +131,7 @@ To add support for formatting `.astro` files outside of the editor (e.g. CLI) or
       </Fragment>
       <Fragment slot="yarn">
       ```shell
-      yarn prettier . --write
+      yarn exec prettier . --write
       ```
       </Fragment>
     </PackageManagerTabs>

src/content/docs/en/guides/dev-toolbar.mdx

@@ -1,11 +1,11 @@
 ---
 title: Dev toolbar
-description: A guide to using the developer toolbar in Astro
+description: A guide to using the dev toolbar in Astro
 i18nReady: true
 ---
 import RecipeLinks from "~/components/RecipeLinks.astro";
 
-While the dev server is running, Astro includes a development toolbar at the bottom of every page in your local browser preview.
+While the dev server is running, Astro includes a dev toolbar at the bottom of every page in your local browser preview.
 
 This toolbar includes a number of useful tools for debugging and inspecting your site during development and can be [extended with more dev toolbar apps](#extending-the-dev-toolbar) found in the integrations directory. You can even [build your own toolbar apps](/en/recipes/making-toolbar-apps/) using the [Dev Toolbar API](/en/reference/dev-toolbar-app-reference/)!
 
@@ -35,7 +35,7 @@ The dev toolbar aims to provide a quick and easy way to catch common issues duri
 
 ### Settings
 
-The Settings app allows you to configure options for the development toolbar, such as verbose logging, disabling notifications, and adjusting its placement on your screen.
+The Settings app allows you to configure options for the dev toolbar, such as verbose logging, disabling notifications, and adjusting its placement on your screen.
 
 ## Extending the dev toolbar
 
@@ -63,7 +63,7 @@ export default defineConfig({
 })
 ```
 
-To enable the dev toolbar again, remove these lines from your configuration, or set `enabled:true`.
+To enable the dev toolbar again, remove these lines from your configuration, or set `enabled: true`.
 
 ### Per-user
 

src/content/docs/en/tutorial/5-astro-api/2.mdx

@@ -65,7 +65,7 @@ You can create entire sets of pages dynamically using `.astro` files that export
 
     Be sure to give each route in your array the new props, and then make those props available to your component template outside of your function.
 
-    ```astro title="src/pages/tags/[tag].astro" ins={5,18} "props: {posts: allPosts}" 
+    ```astro title="src/pages/tags/[tag].astro" ins={5,18} ins="props: {posts: allPosts}" 
     ---
     import BaseLayout from '../../layouts/BaseLayout.astro';
 

src/content/docs/es/guides/server-islands.mdx

@@ -0,0 +1,116 @@
+---
+title: Islas de Servidor
+description: Combina HTML estático de alto rendimiento con contenido dinámico renderizado en el servidor.
+i18nReady: true
+---
+
+Las islas de servidor te permiten renderizar "islas" dinámicas o personalizadas bajo demanda de forma individual, sin sacrificar el rendimiento del resto de la página.
+
+Esto significa que tus visitantes verán las partes más importantes de tu página antes y permite que tu contenido principal se guarde en caché de manera más agresiva, ofreciendo así un rendimiento más rápido.
+
+## Componentes de Islas de Servidor
+
+Una isla de servidor es un [componente de Astro](/es/basics/astro-components/) al que se le indica retrasar la renderización hasta que su contenido esté disponible.
+
+Tu página se renderizará de inmediato con cualquier [contenido por defecto que hayas definido](#contenido-por-defecto-para-islas-de-servidor). Luego, el contenido real del componente se obtiene en el cliente y se muestra cuando esté disponible.
+
+Con [un adaptador instalado](/es/guides/on-demand-rendering/#adaptadores-de-servidor) para realizar la renderización diferida, agrega la [directiva `server:defer`](/es/reference/directives-reference/#directivas-del-servidor) a cualquier componente de tu página para convertirlo en su propia isla:
+
+```astro title="src/pages/index.astro" "server:defer"
+---
+import Avatar from '../components/Avatar.astro';
+---
+<Avatar server:defer />
+```
+
+Estos componentes pueden hacer [todo lo que normalmente harías en una página renderizada bajo demanda](/es/guides/on-demand-rendering/#funciones-de-renderizado-bajo-demanda) usando un adaptador, como obtener contenido y acceder a cookies:
+
+```astro title="src/components/Avatar.astro"
+---
+import { getUserAvatar } from '../sessions';
+const userSession = Astro.cookies.get('session');
+const avatarURL = await getUserAvatar(userSession);
+---
+<img alt="User avatar" src={avatarURL} />
+```
+
+## Contenido por defecto para Islas de Servidor
+
+Cuando utilices el atributo `server:defer` en un componente para retrasar su renderizado, puedes colocar contenido por defecto mediante el slot con nombre "fallback".
+
+Este contenido por defecto se renderizará inicialmente junto con el resto de la página al cargarla y será reemplazado por el contenido real de tu componente en cuanto esté disponible.
+
+Para añadir contenido por defecto, agrega `slot="fallback"` a un elemento secundario (otros componentes o elementos HTML) que le pases a tu componente de isla de servidor:
+
+```astro
+---
+import Avatar from '../components/Avatar.astro';
+import GenericAvatar from '../components/GenericAvatar.astro';
+---
+<Avatar server:defer>
+  <GenericAvatar slot="fallback" />
+</Avatar>
+```
+
+Este contenido por defecto puede incluir, por ejemplo:
+
+- Un avatar genérico en lugar del avatar propio del usuario.
+- Una UI de tipo placeholder, como mensajes personalizados.
+- Indicadores de carga, por ejemplo spinners.
+
+
+## Como funciona
+
+La implementación de las islas de servidor se realiza principalmente en el proceso de compilación, donde el contenido del componente se reemplaza por un script ligero.
+
+Cada una de las islas marcadas con `server:defer` se separa en su propia ruta especial, que el script recupera en tiempo de ejecución. Cuando Astro compila tu sitio, omite el componente e inyecta en su lugar un script y cualquier contenido que hayas marcado con `slot="fallback"`.
+
+Cuando la página se carga en el navegador, estos componentes se solicitan a un endpoint especial que los renderiza y devuelve el HTML. Esto significa que los usuarios verán al instante las partes más críticas de la página, mientras que el contenido por defecto estará visible brevemente antes de que se carguen las islas dinámicas.
+
+Cada isla se carga de forma independiente de las demás. Esto implica que, si alguna tarda más en cargarse, no retrasará el resto del contenido personalizado.
+
+Este patrón de renderizado fue diseñado para ser portátil, ya que no depende de ninguna infraestructura de servidor en particular. Funcionará con cualquier servicio de hosting que utilices, desde un servidor de Node.js en un contenedor de Docker hasta el proveedor serverless de tu elección.
+
+## Caché
+
+Los datos para las islas de servidor se obtienen mediante una solicitud `GET`, pasando las props como una cadena encriptada en la query de la URL. Esto permite almacenar los datos en caché con la [cabecera HTTP `Cache-Control`](https://developer.mozilla.org/es/docs/Web/HTTP/Headers/Cache-Control), utilizando directivas estándar de `Cache-Control`.
+
+Sin embargo, [el navegador limita las URLs a una longitud máxima de 2048 bytes](https://chromium.googlesource.com/chromium/src/+/master/docs/security/url_display_guidelines/url_display_guidelines.md#url-length) por razones prácticas y para evitar problemas de denegación de servicio (DoS). Si tu cadena de consulta hace que la URL supere este límite, Astro enviará en su lugar una solicitud `POST` que contiene todas las props en el cuerpo. 
+
+Las solicitudes `POST` no se almacenan en caché en los navegadores porque se utilizan para enviar datos, lo que podría causar problemas de integridad o seguridad de la información. Por lo tanto, cualquier lógica de caché existente en tu proyecto dejará de funcionar. Siempre que sea posible, pasa únicamente las props necesarias a tus islas de servidor y evita enviar objetos de datos o arreglos completos para mantener tu query lo más pequeña posible. 
+
+## Acceder a la URL de la página en una Isla de Servidor
+
+En la mayoría de los casos, tu componente de isla de servidor puede obtener información sobre la página que lo está renderizando [pasando props](/es/basics/astro-components/#props-de-componentes), igual que en los componentes normales. 
+
+No obstante, las islas de servidor se ejecutan en su propio contexto aislado, independiente de la solicitud de la página. Tanto `Astro.url` como `Astro.request.url` en un componente de isla de servidor devolverán una URL con el formato `/_server-islands/Avatar`, en lugar de la URL actual de la página en el navegador. Además, si estás pre-renderizando la página, no tendrás acceso a información como los parámetros de la query para pasarlos como props.
+
+Para acceder a la información de la URL de la página, puedes revisar la cabecera [Referer](https://developer.mozilla.org/es/docs/Web/HTTP/Headers/Referer) que contendrá la dirección de la página que está cargando la island en el navegador:
+
+```astro
+---
+const referer = Astro.request.headers.get('Referer');
+const url = new URL(referer);
+const productId = url.searchParams.get('product');
+---
+```
+
+## Reutilizar la clave de cifrado
+
+Astro utiliza [criptografía](https://developer.mozilla.org/es/docs/Glossary/Cryptography) para cifrar las props que se pasan a las islas de servidor, evitando así la filtración accidental de secretos. Estas props se cifran usando una clave que se genera durante el proceso de compilación.
+
+En la mayoría de los proveedores de hosting, esto sucede de manera transparente y no necesitas hacer nada como desarrollador. Sin embargo, si estás usando rolling deployments en un entorno como Kubernetes, podrías tener problemas cuando el frontend y el backend estén temporalmente fuera de sincronización y las claves no coincidan.
+
+Para resolverlo, puedes crear una clave con la CLI de Astro y reutilizarla en todos tus despliegues. Esto garantiza que el frontend de cada usuario se comunique con un backend que tenga la clave correcta.
+
+Genera una clave usando `astro create-key`:
+
+```shell
+astro create-key
+```
+
+Esto creará una clave que puedes configurar como la variable de entorno ASTRO_KEY donde tu entorno de hosting lo requiera, por ejemplo, en un archivo .env:
+
+```ini title=".env"
+ASTRO_KEY=zyM5c0qec+1Sgi4K+AejFX9ufbig7/7wIZjxOjti9Po=
+```

src/content/docs/es/recipes/analyze-bundle-size.mdx

@@ -0,0 +1,88 @@
+---
+title: Analizar el tamaño del empaquetado
+description: Aprende cómo analizar el empaquetado generado por Astro usando `rollup-plugin-visualizer`.
+i18nReady: true
+type: recipe
+---
+
+import { Steps } from '@astrojs/starlight/components';
+import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
+
+Comprender qué forma parte de un empaquetado de Astro es importante para mejorar el rendimiento del sitio. Visualizar el empaquetado puede dar pistas sobre dónde se pueden hacer cambios en tu proyecto para reducir su tamaño.
+
+## Receta
+
+La [biblioteca `rollup-plugin-visualizer`](https://github.com/btd/rollup-plugin-visualizer) te permite visualizar y analizar tu empaquetado de Rollup para ver qué módulos están ocupando espacio.
+<Steps>
+1. Instala `rollup-plugin-visualizer`:
+
+    <PackageManagerTabs>
+        <Fragment slot="npm">
+        ```shell
+        npm install rollup-plugin-visualizer --save-dev
+        ```
+        </Fragment>
+        <Fragment slot="pnpm">
+        ```shell
+        pnpm add rollup-plugin-visualizer --save-dev
+        ```
+        </Fragment>
+        <Fragment slot="yarn">
+        ```shell
+        yarn add rollup-plugin-visualizer --save-dev
+        ```
+        </Fragment>
+    </PackageManagerTabs>
+
+2. Agrega el plugin al archivo `astro.config.mjs`:
+
+    ```js
+    // @ts-check
+    import { defineConfig } from 'astro/config';
+    import { visualizer } from "rollup-plugin-visualizer";
+
+    export default defineConfig({
+    vite: {
+        plugins: [visualizer({
+            emitFile: true,
+            filename: "stats.html",
+        })]
+    }
+    });
+    ```
+3. Ejecuta el comando de compilación:
+
+    <PackageManagerTabs>
+        <Fragment slot="npm">
+        ```shell
+        npm run build
+        ```
+        </Fragment>
+        <Fragment slot="pnpm">
+        ```shell
+        pnpm build
+        ```
+        </Fragment>
+        <Fragment slot="yarn">
+        ```shell
+        yarn build
+        ```
+        </Fragment>
+    </PackageManagerTabs>
+
+4. Encuentra el(los) archivo(s) `stats.html` de tu proyecto.
+
+		Este archivo estará en la raíz de tu directorio `dist/` para sitios completamente estáticos y te permitirá ver qué está incluido en el empaquetado.
+
+		Si tu proyecto de Astro usa renderizado bajo demanda, tendrás dos archivos `stats.html`. Uno será para el cliente y el otro para el servidor, y cada uno estará ubicado en la raíz de los directorios `dist/client` y `dist/server/`.
+
+		Consulta [la documentación de Rollup Plugin Visualizer](https://github.com/btd/rollup-plugin-visualizer#how-to-use-generated-files) para obtener orientación sobre cómo interpretar estos archivos o configurar opciones específicas.
+
+</Steps>
+
+:::note
+Dado el enfoque único de Astro para la hidratación, la compilación no representa necesariamente el empaquetado
+que recibirá el cliente.
+
+El visualizador de Rollup muestra todas las dependencias utilizadas en todo el sitio, pero no desglosa el tamaño del empaquetado por página.
+:::

src/content/docs/es/reference/directives-reference.mdx

@@ -80,7 +80,7 @@ import api from '../db/api.js';
 <article set:html={api.getArticle(Astro.props.id)}></article>
 ```
 
-`set:html={Promise<Response>}` inyecta una [Respuesta](https://developer.mozilla.org/en-US/docs/Web/API/Response) en un elemento.
+`set:html={Promise<Response>}` inyecta una [Respuesta](https://developer.mozilla.org/es/docs/Web/API/Response) en un elemento.
 
 Esto es más útil cuando se usa `fetch()`. Por ejemplo, recuperar publicaciones antiguas de un anterior generador de sitios estáticos.
 
@@ -139,6 +139,18 @@ Carga e hidrata el componente JavaScript una vez que la página haya terminado c
 <ShowHideButton client:idle />
 ```
 
+### `timeout`
+
+<p><Since v="4.15.0" /></p>
+
+El tiempo máximo de espera, en milisegundos, antes de hidratar el componente, incluso si la página aún no ha terminado su carga inicial.
+
+Esto te permite pasar un valor para [la opción `timeout` desde la especificación de `requestIdleCallback()`](https://www.w3.org/TR/requestidlecallback/#the-requestidlecallback-method). Esto significa que puedes retrasar la hidratación de elementos de la interfaz de usuario de menor prioridad con más control, asegurando que tu elemento sea interactivo dentro de un período de tiempo determinado.
+
+```astro
+<ShowHideButton client:idle={{timeout: 500}} />
+```
+
 ### `client:visible`
 
 - **Prioridad:** Baja
@@ -191,12 +203,35 @@ Si el componente ya está oculto y se muestra mediante media queries de CSS, ent
 <SomeLitComponent client:only="lit" />
 ```
 
+#### Mostrar contenido de carga
+
+Para los componentes que se renderizan solo en el cliente, también es posible mostrar contenido alternativo mientras se están cargando. Usa `slot="fallback"` en cualquier elemento hijo para crear contenido que se mostrará solo hasta que tu componente en el cliente esté disponible:
+
+```astro {2}
+<ClientComponent client:only="vue">
+  <div slot="fallback">Cargando</div>
+</ClientComponent>
+```
+
 ### Directivas de cliente personalizadas
 
 Desde Astro 2.6.0, las integraciones también pueden agregar directivas `client:*` personalizadas para cambiar cómo y cuándo se deben hidratar los componentes.
 
 Consulta la [API `addClientDirective`](/es/reference/integrations-reference/#opción-addclientdirective) para saber más sobre cómo crear una directiva de cliente personalizada.
 
+## Directivas del Servidor
+
+Estas directivas controlan cómo se renderizan los componentes tipo isla de servidor.
+
+### `server:defer`
+
+La directiva `server:defer` transforma el componente en una isla de servidor, haciendo que se renderice bajo demanda, fuera del alcance del resto de la renderización de la página.
+
+<ReadMore>Consulta más sobre el uso de [componentes de isla de servidor](/es/guides/server-islands/).</ReadMore>
+
+```astro
+<Avatar server:defer />
+```
 
 ## Directivas Script & Style