docs(diff): display two tabs for diffs additions and additions/deletions (#336)

* docs(diff): display two tabs for diffs additions and additions/deletions

To save copy/paste errors when following the dungeon adventure tutorial, by default we show only the
"after" content (highlighting added lines). Also include a tab for users to see the full diff too.

Fixes #332

* docs: display diffs which were previously too complex to display

* docs: update translations

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: cogwirrel

docs/src/components/diff.astro

@@ -1,5 +1,5 @@
 ---
-import { Code } from '@astrojs/starlight/components';
+import { Code, Tabs, TabItem } from '@astrojs/starlight/components';
 import { diffLines } from 'diff';
 
 const { before, after, lang } = Astro.props;
@@ -10,5 +10,26 @@ const diff = diffLines(before, after, { newlineIsToken: false })
     return change.value.slice(0, -1).split('\n').map(line => `${prefix}${line}`).join('\n') + '\n';
   }).join('');
 
+let removedLines = 0;
+const afterMeta = diff.split('\n').map((line, i) => {
+  if (line.startsWith('+')) {
+    return `ins={${i + 1 - removedLines}}`;
+  } else if (line.startsWith('-')) {
+    removedLines++;
+  }
+  return undefined;
+}).filter(x => x).join(' ');
+
 ---
-<Code lang="diff" code={diff} {...(lang ? { meta: `lang="${lang}"`} : {})} />
+{
+  removedLines > 0 ? (
+    <Tabs syncKey="diff">
+      <TabItem label="+">
+        <Code lang={lang} code={after} meta={afterMeta} />
+      </TabItem>
+      <TabItem label="+-">
+        <Code lang="diff" code={diff} {...(lang ? { meta: `lang="${lang}"`} : {})} />
+      </TabItem>
+    </Tabs>
+  ) : <Code lang="diff" code={diff} {...(lang ? { meta: `lang="${lang}"`} : {})} />
+}

docs/src/content/docs/en/get_started/tutorials/dungeon-game/3.mdx

@@ -39,10 +39,10 @@ Let's implement our agent. Update the following files in `packages/story/dungeon
 
 <Tabs>
   <TabItem label="main.py">
-<E2ECode lang="python" path="dungeon-adventure/3/main.py.template" />
+<E2EDiff lang="python" before="dungeon-adventure/3/main.py.old.template" after="dungeon-adventure/3/main.py.template" />
   </TabItem>
   <TabItem label="agent.py">
-<E2ECode lang="python" path="dungeon-adventure/3/agent.py.template" />
+<E2EDiff lang="python" before="dungeon-adventure/3/agent.py.old.template" after="dungeon-adventure/3/agent.py.template" />
   </TabItem>
 </Tabs>
 

docs/src/content/docs/en/get_started/tutorials/dungeon-game/4.mdx

@@ -70,7 +70,7 @@ Let's also update the `index.tsx` file to load our new `/game` route by default.
 
 <Tabs>
 <TabItem label="routes/index.tsx">
-<E2ECode path="dungeon-adventure/4/routes/index.tsx.template" lang="tsx" />
+<E2EDiff before="dungeon-adventure/4/routes/index.tsx.old.template" after="dungeon-adventure/4/routes/index.tsx.template" lang="tsx" />
 </TabItem>
 </Tabs>
 

docs/src/content/docs/es/get_started/tutorials/dungeon-game/3.mdx

@@ -26,13 +26,13 @@ import gameConversationPng from '@assets/game-conversation.png'
 ## Módulo 3: Implementación del Agente de Historia
 
 <Aside type="caution">
-Asegúrate de que tu cuenta AWS tenga acceso habilitado al [modelo predeterminado de Strands](https://strandsagents.com/latest/documentation/docs/user-guide/concepts/model-providers/amazon-bedrock/) dentro de Bedrock para tu región objetivo siguiendo los pasos de [esta guía](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access-modify.html). Al momento de escribir esto, el modelo es Anthropic Claude Sonnet 4.
+Asegúrate de que tu cuenta de AWS haya habilitado acceso al [modelo predeterminado de Strands](https://strandsagents.com/latest/documentation/docs/user-guide/concepts/model-providers/amazon-bedrock/) dentro de Bedrock para tu región objetivo siguiendo los pasos descritos en [esta guía](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access-modify.html). Al momento de escribir esto, el modelo es Anthropic Claude Sonnet 4.
 </Aside>
 
 El Agente de Historia es un agente de [Strands](https://strandsagents.com/) que, dado un `Game` y una lista de `Action`s como contexto, avanzará una historia. Configuraremos el agente para interactuar con nuestro Inventory MCP Server y gestionar los objetos disponibles del jugador.
 
 :::note
-Para simplificar este tutorial, implementamos el Agente de forma "sin estado", donde cada invocación es una sesión independiente que incluye todo el historial de mensajes. Para producción, considera integrar con [Bedrock AgentCore Memory](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/memory.html). Más documentación sobre el uso de AgentCore Memory con Strands está [disponible aquí](https://github.com/aws/bedrock-agentcore-sdk-python/tree/main/src/bedrock_agentcore/memory/integrations/strands).
+Para simplificar este tutorial, implementamos el Agente de forma "sin estado" donde cada invocación es una sesión independiente que incluye todo el historial de mensajes. Para entornos de producción, considera integrar con [Bedrock AgentCore Memory](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/memory.html). Más documentación sobre el uso de AgentCore Memory con Strands está [disponible aquí](https://github.com/aws/bedrock-agentcore-sdk-python/tree/main/src/bedrock_agentcore/memory/integrations/strands).
 :::
 
 ### Implementación del Agente
@@ -41,10 +41,10 @@ Implementemos nuestro agente. Actualiza los siguientes archivos en `packages/sto
 
 <Tabs>
   <TabItem label="main.py">
-<E2ECode lang="python" path="dungeon-adventure/3/main.py.template" />
+<E2EDiff lang="python" before="dungeon-adventure/3/main.py.old.template" after="dungeon-adventure/3/main.py.template" />
   </TabItem>
   <TabItem label="agent.py">
-<E2ECode lang="python" path="dungeon-adventure/3/agent.py.template" />
+<E2EDiff lang="python" before="dungeon-adventure/3/agent.py.old.template" after="dungeon-adventure/3/agent.py.template" />
   </TabItem>
 </Tabs>
 
@@ -61,7 +61,7 @@ Primero, compilemos el código base:
 <NxCommands commands={['run-many --target build --all']} />
 
 <Aside type="tip">
-Si encuentras errores de linting, ejecuta este comando para corregirlos automáticamente:
+Si encuentras errores de linting, puedes ejecutar el siguiente comando para corregirlos automáticamente.
 
 <NxCommands commands={['run-many --target lint --configuration=fix --all']} />
 </Aside>
@@ -72,7 +72,7 @@ Ahora puedes desplegar la aplicación ejecutando:
 
 Este despliegue tomará aproximadamente 2 minutos en completarse.
 
-Una vez completado, verás salidas similares a estas _(algunos valores fueron omitidos)_:
+Una vez completado el despliegue, verás salidas similares a las siguientes _(algunos valores han sido omitidos)_:
 
 ```bash
 dungeon-adventure-infra-sandbox-Application
@@ -104,10 +104,10 @@ Podemos probar nuestra API de dos formas:
     <NxCommands highlights={['arn:aws:bedrock-agentcore:region:xxxxxxx:runtime/dungeonadventureventoryMcpServerXXXX-YYYY', 'region']} env={{PORT: '9999', INVENTORY_MCP_ARN:"arn:aws:bedrock-agentcore:region:xxxxxxx:runtime/dungeonadventureventoryMcpServerXXXX-YYYY", AWS_REGION: '<region>'}} commands={["run dungeon_adventure.story:agent-serve"]} />
 
     :::caution
-    Usa la salida `InventoryMcpArn` del despliegue CDK arriba, y especifica tu `AWS_REGION` objetivo.
+    Usa el output `InventoryMcpArn` del despliegue CDK arriba, además de especificar tu `AWS_REGION` objetivo.
     :::
 
-    Cuando el servidor esté activo (¡no verás ninguna salida!), invócalo con:
+    Una vez que el servidor del Agente esté en ejecución (¡no verás ninguna salida!), invócalo con:
 
     ```bash
     curl -N -X POST http://127.0.0.1:9999/invocations \
@@ -117,16 +117,16 @@ Podemos probar nuestra API de dos formas:
     ```
   </TabItem>
   <TabItem label="Desplegado">
-    Para probar el agente desplegado, necesitas autenticarte con Cognito y obtener un token JWT. Primero configura tus variables de entorno:
+    Para probar el agente desplegado, necesitarás autenticarte con Cognito y obtener un token JWT. Primero configura tus variables de entorno:
 
     ```bash
-    # Usa el User Pool ID y Client ID de las salidas CDK
-    export POOL_ID="<UserPoolId de salidas CDK>"
-    export CLIENT_ID="<UserPoolClientId de salidas CDK>"
-    export REGION="<tu-región>"
+    # Establece tu User Pool ID y Client ID de Cognito desde los outputs de CDK
+    export POOL_ID="<UserPoolId from CDK outputs>"
+    export CLIENT_ID="<UserPoolClientId from CDK outputs>"
+    export REGION="<your-region>"
     ```
 
-    Crea un usuario de prueba y obtén un token:
+    Crea un usuario de prueba y obtén un token de autenticación:
 
     ```bash
     # Crear usuario
@@ -137,7 +137,7 @@ Podemos probar nuestra API de dos formas:
       --region $REGION \
       --message-action SUPPRESS > /dev/null
 
-    # Establecer contraseña permanente
+    # Establecer contraseña permanente (¡reemplaza con algo más seguro!)
     aws cognito-idp admin-set-user-password \
       --user-pool-id $POOL_ID \
       --username "testuser" \
@@ -154,22 +154,22 @@ Podemos probar nuestra API de dos formas:
     ```
 
     :::caution
-    Usa la salida `UserIdentityUserIdentityUserPoolIdXXX` para `POOL_ID` y asegúrate de tener el Client ID correspondiente de las salidas CDK.
+    Usa el output `UserIdentityUserIdentityUserPoolIdXXX` para `POOL_ID` y asegúrate de tener el Client ID correspondiente en tus outputs de despliegue CDK.
     :::
 
-    Ahora invoca el agente desplegado usando la URL de Bedrock AgentCore:
+    Ahora invoca el agente desplegado usando la URL de Bedrock AgentCore Runtime:
 
     ```bash
-    # Usa el StoryAgentArn de las salidas CDK
-    export AGENT_ARN="<StoryAgentArn de salidas CDK>"
+    # Establece el ARN del Agente de Historia desde los outputs de CDK
+    export AGENT_ARN="<StoryAgentArn from CDK outputs>"
 
-    # Codificar ARN para URL
+    # Codifica el ARN en URL
     export ENCODED_ARN=$(echo $AGENT_ARN | sed 's/:/%3A/g' | sed 's/\//%2F/g')
 
-    # Construir URL de invocación
+    # Construye la URL de invocación
     export MCP_URL="https://bedrock-agentcore.$REGION.amazonaws.com/runtimes/$ENCODED_ARN/invocations?qualifier=DEFAULT"
 
-    # Invocar el agente
+    # Invoca el agente
     curl -N -X POST "$MCP_URL" \
       -H "authorization: Bearer $BEARER_TOKEN" \
       -H "Content-Type: application/json" \
@@ -178,12 +178,12 @@ Podemos probar nuestra API de dos formas:
     ```
 
     :::note
-    La codificación URL es necesaria para formatear correctamente el ARN en el endpoint de Bedrock AgentCore.
+    La codificación URL es necesaria para formatear correctamente el ARN en el endpoint de API de Bedrock AgentCore.
     :::
   </TabItem>
 </Tabs>
 
-Si el comando tiene éxito, verás eventos transmitidos similares a:
+Si el comando se ejecuta correctamente, verás eventos transmitidos similares a:
 
 ```
 data: {"init_event_loop": true}
@@ -199,4 +199,4 @@ data: {"event": {"contentBlockDelta": {"delta": {"text": "Welcome"}, "contentBlo
 ...
 ```
 
-¡Felicidades! Has implementado tu primer Agente de Strands en Bedrock AgentCore Runtime. 🎉🎉🎉
+¡Felicidades! Has construido y desplegado tu primer Agente de Strands en Bedrock AgentCore Runtime. 🎉🎉🎉

docs/src/content/docs/es/get_started/tutorials/dungeon-game/4.mdx

@@ -28,13 +28,13 @@ Para comenzar a construir la interfaz de usuario, necesitamos configurar nuestro
 
 <NxCommands commands={["run @dungeon-adventure/game-ui:load:runtime-config"]} />
 
-Este comando descargará el archivo `runtime-config.json` que está desplegado y lo almacenará localmente en la carpeta `packages/game-ui/public`.
+Este comando descargará el `runtime-config.json` que está desplegado y lo almacenará localmente en la carpeta `packages/game-ui/public`.
 
 Ahora podemos iniciar el servidor de desarrollo con el siguiente comando:
 
 <NxCommands commands={["run @dungeon-adventure/game-ui:serve"]} />
 
-Luego puedes abrir el sitio web local en tu navegador, donde se te pedirá iniciar sesión y seguir las instrucciones para crear un nuevo usuario. Una vez completado, deberías ver el sitio web base:
+Luego puedes abrir el sitio web local en tu navegador, donde se te pedirá iniciar sesión y seguir las indicaciones para crear un nuevo usuario. Una vez completado, deberías ver el sitio web base:
 
 <Image src={baselineWebsitePng} alt="baseline-website.png" width="800" height="600" />
 
@@ -43,14 +43,14 @@ _Mantendremos el servidor de desarrollo en ejecución durante el resto de este m
 </Aside>
 
 :::tip
-Puedes ejecutar <NxCommands commands={["run @dungeon-adventure/game-ui:serve-local"]} /> para iniciar también los servidores locales de APIs conectadas, permitiéndote iterar simultáneamente en tu API tRPC y tu sitio web.
+Puedes ejecutar <NxCommands commands={["run @dungeon-adventure/game-ui:serve-local"]} /> en su lugar, lo que adicionalmente iniciará cualquier servidor API local conectado, permitiéndote iterar tanto en tu API tRPC como en tu sitio web simultáneamente.
 :::
 
 ### Crear una nueva ruta '/game'
 
-Mostraremos las capacidades de `@tanstack/react-router` creando una nueva ruta tipada. Para hacerlo, simplemente crea un archivo vacío en: `packages/game-ui/src/routes/game/index.tsx`. Notarás que el archivo se actualiza inmediatamente.
+Mostraremos las capacidades de `@tanstack/react-router` creando una nueva ruta tipada. Para esto, simplemente crea un archivo vacío en la siguiente ubicación: `packages/game-ui/src/routes/game/index.tsx`. Notarás que el archivo se actualiza inmediatamente.
 
-El `@tanstack/react-router` ha configurado automáticamente tu nueva ruta y observarás que el archivo recién creado ya contiene la ruta:
+El `@tanstack/react-router` ha configurado automáticamente tu nueva ruta y observarás que el archivo que acabas de crear ya está poblado con la ruta:
 
 ```tsx
 import { createFileRoute } from '@tanstack/react-router'
@@ -64,23 +64,23 @@ function RouteComponent() {
 }
 ```
 
-Si navegas a `http://localhost:4200/game`, ¡verás que se renderiza tu nueva página!
+Ahora, si navegas a `http://localhost:4200/game`, ¡verás que tu nueva página se ha renderizado!
 
 <Image src={baselineGamePng} alt="baseline-game.png" width="800" height="600" />
 
 Actualicemos también el archivo `index.tsx` para cargar nuestra nueva ruta `/game` por defecto. Observa cómo al actualizar el campo `to`, tienes una lista de rutas tipadas para elegir.
 
 <Tabs>
 <TabItem label="routes/index.tsx">
-<E2ECode path="dungeon-adventure/4/routes/index.tsx.template" lang="tsx" />
+<E2EDiff before="dungeon-adventure/4/routes/index.tsx.old.template" after="dungeon-adventure/4/routes/index.tsx.template" lang="tsx" />
 </TabItem>
 </Tabs>
 
 Finalmente podemos eliminar la carpeta `packages/game-ui/src/routes/welcome/` ya que no es necesaria.
 
 ### Actualizaciones de diseño
 
-El diseño predeterminado se asemeja más a una aplicación empresarial estilo SaaS que a un juego. Reconfiguraremos el diseño y aplicaremos un tema más acorde a un juego de mazmorras.
+El diseño predeterminado está más orientado a aplicaciones empresariales estilo SaaS que a un juego. Vamos a reconfigurar el diseño y rediseñar el tema para que se asemeje más a un juego de estilo mazmorra.
 
 Realicemos los siguientes cambios en `packages/game-ui/src`:
 
@@ -100,7 +100,7 @@ Ahora eliminemos el archivo `packages/game-ui/src/hooks/useAppLayout.tsx` ya que
 
 ### Integración del Agente de Historia
 
-A continuación crearemos un hook para interactuar con nuestro Agente de Historia.
+A continuación crearemos un hook para inicializar un cliente que interactúe con nuestro Agente de Historia.
 
 <Tabs>
 <TabItem label="hooks/useStoryAgent.tsx">
@@ -116,12 +116,12 @@ Esto realiza lo siguiente:
 - Retorna un iterador asíncrono para consumir fragmentos de mensajes transmitidos
 
 :::tip
-Notarás que la integración con nuestra Game API ya está configurada - no necesitamos hacer nada gracias al generador `api-connection`. Por favor vota [+1 en este issue de GitHub](https://github.com/awslabs/nx-plugin-for-aws/issues/326) si deseas una experiencia similar para agentes.
+Notarás que la integración con nuestra Game API ya está configurada - no tenemos que hacer nada manualmente ya que usamos el generador `api-connection`. Por favor da +1 a [este issue de GitHub](https://github.com/awslabs/nx-plugin-for-aws/issues/326) si deseas una experiencia similar para agentes.
 :::
 
 ### Páginas del juego
 
-Creemos las páginas del juego que consumirán nuestras APIs y completarán la implementación. Actualiza los siguientes archivos en `packages/game-ui/src/routes/game`:
+Creemos las páginas del juego que llamarán a nuestras APIs y completarán la implementación del juego. Actualiza los siguientes archivos en `packages/game-ui/src/routes/game`:
 
 <Tabs>
 <TabItem label="index.tsx">
@@ -132,24 +132,24 @@ Creemos las páginas del juego que consumirán nuestras APIs y completarán la i
 <E2ECode path="dungeon-adventure/4/routes/game/$playerName.tsx.template" lang="tsx" />
 
 <Aside type="tip">
-La sintaxis `$playerName` indica a `@tanstack/react-router` que trate `playerName` como un [parámetro de ruta](https://tanstack.com/router/v1/docs/framework/react/guide/path-params). Además implementamos el método `validateSearch` que asegura que el parámetro de consulta `genre` tenga un tipo fuerte según nuestro enum de géneros.
+La sintaxis `$playerName` indicará a `@tanstack/react-router` que trate `playerName` como un [parámetro de ruta](https://tanstack.com/router/v1/docs/framework/react/guide/path-params). Adicionalmente, implementamos el método `validateSearch` que asegura que el parámetro de consulta `genre` esté tipado según nuestro enum de géneros.
 </Aside>
 </TabItem>
 </Tabs>
 
-Al realizar estos cambios, ¡tu servidor de desarrollo local (http://localhost:4200/) debería tener el juego listo para jugar!
+Al realizar estos cambios, ¡tu servidor de desarrollo local (http://localhost:4200/) debería tener ahora el juego listo para jugar!
 
-<Drawer title="Compilar y desplegar" trigger="También puedes compilar y desplegar tu código en Cloudfront si prefieres.">
+<Drawer title="Compilar e implementar" trigger="También puedes compilar e implementar tu código en Cloudfront si lo prefieres.">
 
 Para compilar tu código, ejecuta:
 
 <NxCommands commands={['run-many --target build --all']} />
 
-Ahora despliega tu aplicación:
+Ahora implementa tu aplicación:
 
 <NxCommands commands={['run @dungeon-adventure/infra:deploy dungeon-adventure-infra-sandbox/*']} />
 
-Una vez desplegado, navega a tu URL de Cloudfront que puedes encontrar en las salidas del despliegue de CDK.
+Una vez implementado, navega a tu URL de Cloudfront que puedes encontrar inspeccionando las salidas del despliegue de CDK.
 
 </Drawer>
 
@@ -158,4 +158,4 @@ Una vez desplegado, navega a tu URL de Cloudfront que puedes encontrar en las sa
 <Image src={gameConversationPng} alt="game-conversation.png" width="500" height="400" />
 </div>
 
-¡Felicidades! Has construido y desplegado tu Juego de Mazmorras con Agentes Inteligentes. 🎉🎉🎉
+¡Felicidades! Has construido y desplegado tu Juego de Aventuras de Mazmorras con Agentes. 🎉🎉🎉