Translate accessibility guide updates

es/guides/accessibility.mdx

@@ -7,20 +7,20 @@ keywords: ["documentación accesible", "WCAG", "a11y", "lectores de pantalla", "
 
 Cuando creas documentación accesible, priorizas un diseño de contenido que haga tu documentación usable por la mayor cantidad posible de personas, independientemente de cómo accedan o interactúen con ella.
 
-La documentación accesible mejora la experiencia de uso para todos. Tu contenido es más claro, está mejor estructurado y es más fácil de navegar.
+La documentación accesible mejora la experiencia de uso para todos. Tu contenido es más claro, está mejor estructurado y es más fácil de navegar, ya sea que las personas accedan a él con un lector de pantalla, navegación por teclado, un dispositivo móvil o conexiones de red lentas.
 
-Esta guía ofrece algunas prácticas recomendadas para crear documentación accesible, pero no es exhaustiva. Debes considerar la accesibilidad como un proceso continuo. Las tecnologías y los estándares cambian con el tiempo, lo que presenta nuevas oportunidades para mejorar la documentación.
+Esta guía cubre las prácticas recomendadas para crear documentación accesible. La accesibilidad es un proceso continuo. Las tecnologías y los estándares evolucionan, y siempre hay oportunidades de mejorar. Empieza por los cambios de alto impacto e integra la accesibilidad en tu flujo de trabajo.
 
 <div id="what-is-accessibility">
   ## ¿Qué es la accesibilidad?
 </div>
 
-La accesibilidad (a veces abreviada como a11y por el número de letras entre la primera y la última de “accessibility”) consiste en diseñar y crear intencionalmente sitios web y herramientas que puedan utilizar el mayor número posible de personas. Las personas con discapacidades temporales o permanentes deben tener el mismo nivel de acceso a las tecnologías digitales. Y diseñar con la accesibilidad en mente beneficia a todos, incluidas las personas que acceden a tu sitio web desde dispositivos móviles o redes lentas.
+La accesibilidad (a veces abreviada como a11y por el número de letras entre la primera y la última de "accessibility") consiste en diseñar y crear intencionalmente sitios web y herramientas que puedan utilizar el mayor número posible de personas. Las personas con discapacidades temporales o permanentes deben tener el mismo nivel de acceso a las tecnologías digitales. Y diseñar con la accesibilidad en mente beneficia a todos, incluidas las personas que acceden a tu sitio web desde dispositivos móviles o redes lentas.
 
 La documentación accesible sigue los estándares de accesibilidad web, principalmente las [Pautas de Accesibilidad para el Contenido Web (WCAG)](https://www.w3.org/WAI/WCAG22/quickref/). Estas pautas ayudan a garantizar que tu contenido sea perceptible, operable, comprensible y sólido.
 
-<div id="getting-started-with-accessibility">
-  ## Introducción a la accesibilidad
+<div id="get-started-with-accessibility">
+  ## Comienza con la accesibilidad
 </div>
 
 Hacer que tu documentación sea accesible es un proceso. No tienes que solucionarlo todo de una vez ni puedes hacerlo solo una vez.
@@ -46,7 +46,7 @@ El mejor flujo de trabajo es el que mejor se adapta a tu equipo. Aquí tienes un
 **Fase 1: Imágenes y estructura**
 
 - Revisa todas las imágenes para asegurarte de que tengan texto alternativo descriptivo.
-- Revisa el texto de los enlaces y reemplaza frases genéricas como “haz clic aquí”.
+- Revisa el texto de los enlaces y reemplaza frases genéricas como "haz clic aquí".
 - Corrige problemas en la jerarquía de encabezados en toda tu documentación.
 
 **Fase 2: Navegación y medios**
@@ -122,14 +122,14 @@ Los encabezados del mismo nivel deben tener nombres únicos.
   ### Escribe texto de enlace descriptivo
 </div>
 
-El texto del enlace debe ser significativo y estar relacionado con el destino. Evita frases vagas como &quot;haz clic aquí&quot; o &quot;leer más&quot;.
+El texto del enlace debe ser significativo y estar relacionado con el destino. Evita frases vagas como "haz clic aquí" o "leer más".
 
 ```mdx
-<!-- Good -->
-Learn how to [configure your navigation](/organize/navigation).
+<!-- Bueno -->
+Aprende cómo [configurar tu navegación](/organize/navigation).
 
 <!-- Relación poco clara entre el texto del enlace y el destino -->
-[Learn more](/organize/navigation).
+[Más información](/organize/navigation).
 ```
 
 
@@ -149,27 +149,43 @@ Usa las tablas con moderación y solo para datos tabulares cuyo significado prov
 
 Cuando uses tablas, incluye encabezados para que los lectores de pantalla puedan asociar los datos con la columna correcta:
 
-```mdx
-| Función | Estado |
-| ------- | ------ |
-| Búsqueda  | Activa |
-| Analytics | Activa |
+<CodeGroup>
+
+```mdx Estructura de tabla adecuada
+| Función | Estado | Última actualización |
+| ------- | ------ | -------------------- |
+| Búsqueda  | Activa | 2024-03-15   |
+| Analytics | Activa | 2024-03-10 |
+| Exportaciones | Beta | 2024-03-20 |
+```
+
+```mdx Estructura de tabla deficiente
+| Búsqueda | Activa | 2024-03-15 |
+| Analytics | Activa | 2024-03-10 |
+| Exportaciones | Beta | 2024-03-20 |
 ```
 
+</CodeGroup>
+
+El ejemplo deficiente carece de encabezados, lo que hace imposible que los lectores de pantalla anuncien qué representa cada columna.
 
 <div id="write-descriptive-alt-text">
   ## Escribe texto alternativo descriptivo
 </div>
 
 El texto alternativo hace que las imágenes sean accesibles para las personas que usan lectores de pantalla y aparece cuando las imágenes no se cargan. Las imágenes en tu documentación deben incluir texto alternativo que describa la imagen y deje claro por qué está incluida. Incluso con texto alternativo, no debes depender únicamente de las imágenes para transmitir información. Asegúrate de que tu contenido describa lo que comunica la imagen.
 
+<Tip>
+Obtén más información sobre cómo trabajar con imágenes en la [guía de medios](/es/guides/media).
+</Tip>
+
 <div id="write-effective-alt-text">
   ### Escribe texto alternativo eficaz
 </div>
 
-* **Sé específico**: Describe lo que muestra la imagen, no solo que es una imagen.
-* **Sé conciso**: Limítate a una o dos frases.
-* **Evita redundancias**: No empieces con &quot;Imagen de&quot; porque los lectores de pantalla ya saben que el texto alternativo está asociado a una imagen. Sin embargo, incluye descripciones como &quot;Captura de pantalla de&quot; o &quot;Diagrama de&quot; si ese contexto es importante para la imagen.
+- **Sé específico**: Describe lo que muestra la imagen, no solo que es una imagen.
+- **Sé conciso**: Limítate a una o dos frases.
+- **Evita redundancias**: No empieces con "Imagen de" porque los lectores de pantalla ya saben que el texto alternativo está asociado a una imagen. Sin embargo, incluye descripciones como "Captura de pantalla de" o "Diagrama de" si ese contexto es importante para la imagen.
 
 ```mdx
 <!-- Bueno -->
@@ -232,11 +248,41 @@ Si personalizas los colores del tema, verifica que las relaciones de contraste c
 
 Prueba tanto el modo claro como el oscuro. El comando `mint a11y` comprueba el contraste de color.
 
+<CodeGroup>
+
+```json Ejemplo de buen contraste
+{
+  "colors": {
+    "primary": "#0066CC",
+    "background": {
+      "light": "#FFFFFF",
+      "dark": "#1A1A1A"
+    }
+  }
+}
+```
+
+```json Ejemplo de contraste deficiente
+{
+  "colors": {
+    "primary": "#FFCC00",
+    "background": {
+      "light": "#FFFFFF",
+      "dark": "#333333"
+    }
+  }
+}
+```
+
+</CodeGroup>
+
+En el ejemplo deficiente, el amarillo (#FFCC00) sobre blanco tiene un contraste insuficiente. El fondo del modo oscuro (#333333) es demasiado claro para una legibilidad óptima.
+
 <div id="dont-rely-on-color-alone">
   ### No dependas solo del color
 </div>
 
-Si usas el color para transmitir información, incluye también una etiqueta de texto o un icon. Por ejemplo, no marques los errores únicamente con texto rojo. Incluye un icono de error o la palabra "Error".
+Si usas el color para transmitir información, incluye también una etiqueta de texto o un icono. Por ejemplo, no marques los errores únicamente con texto rojo. Incluye un icono de error o la palabra "Error".
 
 <div id="use-clear-concise-language">
   ### Usa un lenguaje claro y conciso
@@ -247,6 +293,10 @@ Si usas el color para transmitir información, incluye también una etiqueta de
 - Evita las oraciones demasiado largas.
 - Usa la voz activa.
 
+<Tip>
+Consulta la [guía de estilo y tono](/es/guides/style-and-tone) para conocer más prácticas recomendadas de redacción.
+</Tip>
+
 <div id="make-code-examples-accessible">
   ## Haz que los ejemplos de código sean accesibles
 </div>
@@ -266,7 +316,7 @@ Declara siempre el lenguaje para el resaltado de sintaxis. Esto ayuda a los lect
 
 ````mdx
 ```javascript
-function obtenerDatosUsuario(id) {
+function getUserData(id) {
   return fetch(`/api/users/${id}`);
 }
 ```
@@ -361,19 +411,73 @@ mint a11y
 
 El comando verifica:
 
-* Falta de texto alternativo en imágenes y videos.
-* Contraste de color insuficiente.
+- Falta de texto alternativo en imágenes y videos.
+- Contraste de color insuficiente.
 
-Cuando finalice el análisis, revisa los problemas detectados y corrígelos en tu contenido. Ejecuta el comando de nuevo para verificar tus correcciones.
+<div id="interpret-the-output">
+  #### Interpreta el resultado
+</div>
 
-Usa flags para comprobar problemas de accesibilidad específicos.
+Cuando se complete el análisis, verás un informe como este:
 
 ```bash
-# Check only for missing alt text
+Accessibility Issues Found:
+
+❌ Missing alt text (3 issues)
+  - /guides/quickstart.mdx:45 - Image missing alt text
+  - /api-reference/users.mdx:12 - Image missing alt text
+  - /guides/setup.mdx:89 - Video missing title attribute
+
+⚠️  Color contrast (2 issues)
+  - Primary color (#FFCC00) on light background fails WCAG AA (2.1:1)
+  - Link color (#FF6B6B) on dark background fails WCAG AA (3.2:1)
+
+✅ 0 issues found in 15 other pages
+```
+
+<div id="fix-common-issues">
+  #### Soluciona problemas comunes
+</div>
+
+**Texto alternativo faltante**: Añade texto alternativo descriptivo a la imagen o video:
+
+```mdx
+<!-- Antes -->
+![](/images/dashboard.png)
+
+<!-- Después -->
+![Dashboard que muestra tres proyectos activos y dos invitaciones pendientes](/images/dashboard.png)
+```
+
+**Fallos de contraste de color**: Actualiza los colores del tema en `docs.json`:
+
+```json
+{
+  "colors": {
+    "primary": "#0066CC",  // Cambiado de #FFCC00
+    "light": "#3399FF",
+    "dark": "#004C99"
+  }
+}
+```
+
+Ejecuta `mint a11y` nuevamente para verificar tus correcciones.
+
+<div id="use-flags-for-targeted-checks">
+  #### Usa flags para comprobaciones específicas
+</div>
+
+Usa flags para comprobar problemas de accesibilidad específicos:
+
+```bash
+# Verifica solo el texto alternativo faltante
 mint a11y --skip-contrast
 
 # Verifica solo problemas de contraste de color
 mint a11y --skip-alt-text
+
+# Falla el pipeline de CI/CD si se encuentran problemas
+mint a11y --fail-on-error
 ```
 
 
@@ -398,6 +502,44 @@ Para realizar pruebas más completas:
 - **Extensiones del navegador**: Instala [axe DevTools](https://www.deque.com/axe/browser-extensions/) o [WAVE](https://wave.webaim.org/extension/) para analizar páginas y detectar problemas.
 - **Pautas WCAG**: Revisa las [Pautas de Accesibilidad para el Contenido Web](https://www.w3.org/WAI/WCAG22/quickref/) para conocer los estándares en detalle.
 
+<div id="frequently-asked-questions">
+  ## Preguntas frecuentes
+</div>
+
+<AccordionGroup>
+
+<Accordion title="¿Necesito que mi documentación cumpla con WCAG AA o AAA?">
+La mayoría de las organizaciones aspiran a cumplir con el Nivel AA de WCAG 2.1, que es el estándar para muchos requisitos legales y ofrece un buen equilibrio entre accesibilidad y viabilidad. El Nivel AAA es más estricto y puede no ser alcanzable para todos los tipos de contenido.
+
+Empieza con el Nivel AA como base. El comando `mint a11y` comprueba requisitos comunes del Nivel AA, como el contraste de color y el texto alternativo.
+</Accordion>
+
+<Accordion title="¿Cómo pruebo mi documentación con un lector de pantalla?">
+En Mac, usa el VoiceOver integrado (pulsa <kbd>Cmd</kbd> + <kbd>F5</kbd> para activarlo). En Windows, descarga [NVDA](https://www.nvaccess.org/) (gratuito y de código abierto). Navega por tu documentación usando solo el lector de pantalla y escucha si los encabezados se anuncian correctamente, si el texto de los enlaces es descriptivo, si las imágenes tienen texto alternativo y si el orden de lectura es lógico. No necesitas ser experto para detectar los problemas más importantes.
+</Accordion>
+
+<Accordion title="¿Cuál es la diferencia entre el texto alternativo y los pies de imagen?">
+**El texto alternativo** lo leen los lectores de pantalla y aparece cuando las imágenes no se cargan. Describe lo que muestra la imagen y por qué es relevante. El texto alternativo es obligatorio para la accesibilidad.
+
+**Los pies de imagen** aparecen debajo de las imágenes para todos los usuarios. Aportan contexto adicional, atribución o explicación. Los pies de imagen son opcionales y complementan al texto alternativo.
+
+Usa ambos cuando una imagen necesite descripción (texto alternativo) y contexto adicional (pie de imagen).
+</Accordion>
+
+<Accordion title="¿Puedo usar emojis en documentación accesible?">
+Sí, pero con moderación. Los lectores de pantalla anuncian en voz alta los nombres de los emojis, por lo que varios emojis seguidos resultan disruptivos. Por ejemplo, 🎉 se convierte en "party popper" y 🚀 en "rocket", de modo que 🎉 🚀 se convierte en "party popper rocket". Evita usar emojis para transmitir información crítica. Si se eliminara el emoji, el significado debería seguir siendo claro. Cuando tengas dudas, usa texto.
+</Accordion>
+
+<Accordion title="¿Cómo gestiono la accesibilidad de los ejemplos de código?">
+Especifica el lenguaje en cada bloque de código para el resaltado de sintaxis. Proporciona contexto antes y después de los bloques de código para que las personas que usan lectores de pantalla entiendan qué hace el código, ya que los lectores de pantalla suelen omitir el código en sí. Divide los ejemplos largos en fragmentos más pequeños y usa nombres de variables descriptivos que tengan sentido al leerse en voz alta.
+</Accordion>
+
+<Accordion title="¿Qué pasa si no puedo solucionar todos los problemas de accesibilidad de inmediato?">
+Prioriza por impacto. Soluciona primero el texto alternativo faltante, la navegación por teclado deficiente y el contraste de color insuficiente, ya que son los que afectan a más usuarios. Luego siguen la jerarquía deficiente de encabezados y el texto de enlace impreciso. Documenta los problemas conocidos junto con un plan para abordarlos. El progreso es mejor que la perfección.
+</Accordion>
+
+</AccordionGroup>
+
 <div id="additional-resources">
   ## Recursos adicionales
 </div>
@@ -406,4 +548,4 @@ Sigue aprendiendo sobre accesibilidad con estos recursos de confianza:
 
 - **[WebAIM](https://webaim.org/)**: Artículos y tutoriales prácticos sobre accesibilidad web
 - **[The A11y Project](https://www.a11yproject.com/)**: Recursos de accesibilidad de la comunidad y una lista de comprobación
-- **[W3C Web Accessibility Initiative (WAI)](https://www.w3.org/WAI/)**: Normas oficiales de accesibilidad y guías
+- **[W3C Web Accessibility Initiative (WAI)](https://www.w3.org/WAI/)**: Normas oficiales de accesibilidad y guías