From 4c830802897450d02d4659a7741525e733c3906d Mon Sep 17 00:00:00 2001
From: "locadex-agent[bot]"
<217277504+locadex-agent[bot]@users.noreply.github.com>
Date: Thu, 9 Oct 2025 23:36:46 +0000
Subject: [PATCH] docs(locadex): update translations
---
docs.json | 23 ++-
es/guides/accessibility.mdx | 398 ++++++++++++++++++++++++++++++++++++
fr/guides/accessibility.mdx | 398 ++++++++++++++++++++++++++++++++++++
zh/guides/accessibility.mdx | 398 ++++++++++++++++++++++++++++++++++++
4 files changed, 1216 insertions(+), 1 deletion(-)
create mode 100644 es/guides/accessibility.mdx
create mode 100644 fr/guides/accessibility.mdx
create mode 100644 zh/guides/accessibility.mdx
diff --git a/docs.json b/docs.json
index 50007456d..a792517e2 100644
--- a/docs.json
+++ b/docs.json
@@ -547,6 +547,13 @@
"fr/guides/migrating-from-mdx"
]
},
+ {
+ "group": "Bonnes pratiques",
+ "icon": "trophy",
+ "pages": [
+ "fr/guides/accessibility"
+ ]
+ },
{
"group": "Git",
"icon": "git-merge",
@@ -845,6 +852,13 @@
"es/guides/migrating-from-mdx"
]
},
+ {
+ "group": "Mejores prácticas",
+ "icon": "trophy",
+ "pages": [
+ "es/guides/accessibility"
+ ]
+ },
{
"group": "Git",
"icon": "git-merge",
@@ -854,7 +868,7 @@
]
},
{
- "group": "Información detallada",
+ "group": "Ideas",
"icon": "chart-line",
"pages": [
"es/guides/improving-docs"
@@ -1143,6 +1157,13 @@
"zh/guides/migrating-from-mdx"
]
},
+ {
+ "group": "最佳实践",
+ "icon": "trophy",
+ "pages": [
+ "zh/guides/accessibility"
+ ]
+ },
{
"group": "Git",
"icon": "git-merge",
diff --git a/es/guides/accessibility.mdx b/es/guides/accessibility.mdx
new file mode 100644
index 000000000..0fce19aa3
--- /dev/null
+++ b/es/guides/accessibility.mdx
@@ -0,0 +1,398 @@
+---
+title: "Accesibilidad"
+description: "Crea documentación que pueda usar la mayor cantidad de personas posible"
+---
+
+Cuando creas documentación accesible, priorizas un diseño de contenido que hace que tu documentación sea utilizable por la mayor cantidad de personas posible, sin importar cómo accedan o interactúen con ella.
+
+La documentación accesible mejora la experiencia de usuario para todos. Tu contenido es más claro, está mejor estructurado y es más fácil de navegar.
+
+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 abre nuevas oportunidades para mejorar la documentación.
+
+
+ ## ¿Qué es la accesibilidad?
+
+
+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.
+
+
+ ## Introducción a la accesibilidad
+
+
+Hacer que tu documentación sea accesible es un proceso. No tienes que solucionarlo todo de una vez ni puedes hacerlo solo una vez.
+
+Si recién empiezas a implementar prácticas de accesibilidad en tu documentación, considera un enfoque por fases: comienza con cambios de alto impacto y avanza a partir de allí.
+
+
+ ### Primeros pasos
+
+
+Estas son tres acciones que puedes realizar ahora mismo para mejorar la accesibilidad de tu documentación:
+
+1. **Ejecuta `mint a11y`** para identificar problemas de accesibilidad en tu contenido.
+2. **Añade texto alternativo** a todas las imágenes.
+3. **Revisa la jerarquía de encabezados** para asegurarte de que haya un H1 por página y que los encabezados sigan un orden secuencial.
+
+
+ ### Planifica tu trabajo de accesibilidad
+
+
+El mejor flujo de trabajo es el que mejor se adapta a tu equipo. Aquí tienes una forma de abordar el trabajo de accesibilidad:
+
+**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í”.
+- Corrige problemas en la jerarquía de encabezados en toda tu documentación.
+
+**Fase 2: Navegación y medios**
+
+- Prueba la navegación con el teclado en tu documentación.
+- Prueba la compatibilidad con lectores de pantalla.
+- Agrega subtítulos y transcripciones a los videos incrustados.
+- Revisa el contraste de color.
+
+**Fase 3: Incorpóralo a tu flujo de trabajo**
+
+- Ejecuta `mint a11y` antes de publicar contenido nuevo.
+- Incluye comprobaciones de accesibilidad en tu proceso de revisión de contenido.
+- Prueba la navegación con el teclado al agregar funciones interactivas.
+- Verifica que los nuevos enlaces externos y los contenidos incrustados incluyan títulos y descripciones adecuados.
+
+Empezar poco a poco e integrar la accesibilidad en tu flujo de trabajo habitual la hace sostenible. Cada mejora ayuda a que más personas accedan a tu documentación con éxito.
+
+
+ ## Estructura tu contenido
+
+
+El contenido bien estructurado es más fácil de navegar y comprender, especialmente para las personas que usan lectores de pantalla y dependen de los encabezados para desplazarse por las páginas, así como para quienes navegan con el teclado.
+
+
+ ### Usa una jerarquía adecuada de encabezados
+
+
+Cada página debe tener un solo encabezado H1, definido por la propiedad `title:` en el frontmatter de la página. Usa los demás encabezados en orden, sin saltarte niveles. Por ejemplo, no pases de H2 a H4.
+
+```mdx
+
+# Título de página (H1)
+
+## Sección principal (H2)
+
+### Subsección (H3)
+
+### Otra subsección (H3)
+
+## Otra sección principal (H2)
+
+
+# Título de página (H1)
+
+## Sección principal (H2)
+
+#### Subsección (H4)
+
+### Otra subsección (H3)
+```
+
+Los encabezados del mismo nivel deben tener nombres únicos.
+
+```mdx
+
+## Consejos de accesibilidad (H2)
+
+### Escribir texto alternativo efectivo (H3)
+
+### Usar contraste de color adecuado (H3)
+
+
+## Consejos de accesibilidad (H2)
+
+### Sugerencia (H3)
+
+### Sugerencia (H3)
+```
+
+
+
+ ### Escribe texto de enlace descriptivo
+
+
+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
+
+Aprende cómo [configurar tu navegación](/organize/navigation).
+
+
+[Más información](/organize/navigation).
+```
+
+
+
+ ### Mantén el contenido fácil de recorrer
+
+
+- Divide los párrafos largos.
+- Usa listas para pasos y opciones.
+- Destaca la información con avisos.
+
+
+ ### Usa una estructura de tabla adecuada
+
+
+Usa las tablas con moderación y solo para datos tabulares cuyo significado provenga de los encabezados de columnas y filas.
+
+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 |
+```
+
+
+
+ ## Escribe texto alternativo descriptivo
+
+
+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.
+
+
+ ### Escribe texto alternativo eficaz
+
+
+* **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
+
+
+
+
+
+```
+
+
+
+ ### Añade texto alternativo a las imágenes
+
+
+Para las imágenes en Markdown, incluye el texto alternativo entre corchetes:
+
+```mdx
+
+```
+
+Para las imágenes en HTML, usa el atributo `alt`:
+
+```html
+
+```
+
+
+
+ ### Añade títulos al contenido incrustado
+
+
+Los iframes y las inserciones de video requieren títulos descriptivos:
+
+```html
+
+```
+
+
+
+ ## Diseña para mejorar la legibilidad
+
+
+Las decisiones de diseño visual afectan cuán accesible es tu documentación para personas con baja visión, daltonismo u otras discapacidades visuales.
+
+
+ ### Asegúrate de un contraste de color suficiente
+
+
+Si personalizas los colores del tema, verifica que las relaciones de contraste cumplan los requisitos de las WCAG:
+
+- Texto de párrafo: relación de contraste mínima de 4.5:1
+- Texto grande: relación de contraste mínima de 3:1
+- Elementos interactivos: relación de contraste mínima de 3:1
+
+Prueba tanto el modo claro como el oscuro. El comando `mint a11y` comprueba el contraste de color.
+
+
+ ### No dependas solo del color
+
+
+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".
+
+
+ ### Usa un lenguaje claro y conciso
+
+
+- Escribe en lenguaje sencillo.
+- Define los términos técnicos la primera vez que los uses.
+- Evita las oraciones largas o enrevesadas.
+- Utiliza la voz activa.
+
+
+ ## Haz que los ejemplos de código sean accesibles
+
+
+Los bloques de código son una parte fundamental de la documentación técnica, pero requieren consideraciones específicas de accesibilidad para garantizar que las personas que usan lectores de pantalla puedan comprenderlos. En general, sigue estas pautas:
+
+- Divide los ejemplos de código largos en fragmentos más pequeños y con sentido.
+- Comenta la lógica compleja dentro del código.
+- Considera proporcionar una descripción en texto para algoritmos complejos.
+- Al mostrar la estructura de archivos, usa bloques de código reales con etiquetas de lenguaje en lugar de arte ASCII.
+
+
+ ### Especifica el lenguaje de programación
+
+
+Declara siempre el lenguaje para el resaltado de sintaxis. Esto ayuda a los lectores de pantalla a anunciar el contexto del código a los usuarios:
+
+````mdx
+```javascript
+function obtenerDatosUsuario(id) {
+ return fetch(`/api/users/${id}`);
+}
+```
+````
+
+
+
+ ### Proporciona contexto del código
+
+
+Proporciona contexto claro para los bloques de código:
+
+````mdx
+La siguiente función obtiene datos de usuario desde la API:
+
+```javascript
+function getUserData(id) {
+ return fetch(`/api/users/${id}`);
+}
+```
+
+Esto devuelve una promesa que se resuelve en el objeto de usuario.
+````
+
+
+
+ ## Accesibilidad de vídeo y multimedia
+
+
+Los vídeos, las animaciones y otros contenidos multimedia necesitan alternativas textuales para que todas las personas puedan acceder a la información que contienen.
+
+
+ ### Agrega subtítulos a los videos
+
+
+Los subtítulos hacen que el contenido de video sea accesible para personas sordas o con discapacidad auditiva. También ayudan a quienes están en entornos sensibles al sonido y a hablantes no nativos:
+
+- Usa subtítulos para todo el contenido hablado en los videos.
+- Incluye efectos de sonido relevantes en los subtítulos.
+- Asegúrate de que los subtítulos estén sincronizados con el audio.
+- Usa puntuación adecuada e identifica a los interlocutores cuando hablen varias personas.
+
+La mayoría de las plataformas de alojamiento de videos admiten subtítulos. Sube archivos de subtítulos o usa subtítulos generados automáticamente como punto de partida y luego revísalos para verificar su precisión.
+
+
+ ### Proporciona transcripciones
+
+
+Las transcripciones ofrecen una forma alternativa de acceder al contenido de video. Se pueden buscar, son más fáciles de consultar y accesibles para los lectores de pantalla:
+
+```mdx
+
+
+
+En este tutorial, veremos cómo configurar la autenticación...
+
+```
+
+Coloca las transcripciones junto al video o proporciona un enlace claro para acceder a ellas.
+
+
+
+ ### Considera alternativas al contenido exclusivamente en video
+
+
+Si la información crítica solo aparece en un video:
+
+- Proporciona la misma información en formato de texto.
+- Incluye capturas de pantalla clave con texto alternativo descriptivo.
+- Crea un tutorial escrito que cubra el mismo material.
+
+Esto garantiza que los usuarios que no pueden acceder al contenido en video puedan igualmente completar su tarea.
+
+
+ ## Prueba tu documentación
+
+
+Probar con regularidad te ayuda a detectar problemas de accesibilidad antes de que los usuarios se encuentren con ellos.
+
+
+ ### Detecta problemas de accesibilidad con `mint a11y`
+
+
+Usa el comando de la CLI `mint a11y` para analizar automáticamente tu documentación en busca de problemas de accesibilidad comunes:
+
+```bash
+mint a11y
+```
+
+El comando verifica:
+
+* Falta de texto alternativo en imágenes
+* Jerarquía incorrecta de encabezados
+* 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.
+
+
+
+ ### Prueba básica de navegación con teclado
+
+
+Navega por tu documentación usando solo el teclado:
+
+1. Pulsa Tab para avanzar por los elementos interactivos.
+2. Pulsa Shift + Tab para retroceder.
+3. Pulsa Enter para activar enlaces y botones.
+4. Comprueba que todos los elementos interactivos sean accesibles y tengan indicadores de foco visibles.
+
+
+ ### Profundiza en las pruebas de accesibilidad
+
+
+Para realizar pruebas más completas:
+
+- **Lectores de pantalla**: Prueba con [NVDA (Windows)](https://www.nvaccess.org/) o [VoiceOver (Mac)](https://www.apple.com/accessibility/voiceover/).
+- **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.
+
+
+ ## Recursos adicionales
+
+
+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
\ No newline at end of file
diff --git a/fr/guides/accessibility.mdx b/fr/guides/accessibility.mdx
new file mode 100644
index 000000000..91970ded4
--- /dev/null
+++ b/fr/guides/accessibility.mdx
@@ -0,0 +1,398 @@
+---
+title: "Accessibilité"
+description: "Créez une documentation utilisable par le plus grand nombre"
+---
+
+Lorsque vous créez une documentation accessible, vous privilégiez une conception du contenu qui la rend utilisable par le plus grand nombre, quel que soit le moyen d’accès et la manière d’interagir avec elle.
+
+La documentation accessible améliore l’expérience utilisateur pour tous. Votre contenu est plus clair, mieux structuré et plus facile à parcourir.
+
+Ce guide propose quelques bonnes pratiques pour créer une documentation accessible, mais il n’est pas exhaustif. Considérez l’accessibilité comme un processus continu. Les technologies et les normes évoluent avec le temps, offrant de nouvelles opportunités d’améliorer la documentation.
+
+
+ ## Qu’est-ce que l’accessibilité ?
+
+
+L’accessibilité (parfois abrégée en a11y, pour le nombre de lettres entre la première et la dernière lettre d’« accessibility ») consiste à concevoir et à développer, de manière intentionnelle, des sites web et des outils utilisables par le plus grand nombre. Les personnes ayant un handicap temporaire ou permanent doivent bénéficier du même niveau d’accès aux technologies numériques. Concevoir pour l’accessibilité profite à tout le monde, y compris aux personnes qui consultent votre site web sur mobile ou via des réseaux lents.
+
+Une documentation accessible respecte les normes d’accessibilité du web, principalement les [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/WCAG22/quickref/). Ces directives aident à garantir que votre contenu est perceptible, opérable, compréhensible et robuste.
+
+
+ ## Premiers pas avec l’accessibilité
+
+
+Rendre votre documentation accessible est un processus. Vous n’avez pas à tout corriger d’un coup et ce n’est pas quelque chose que l’on fait une seule fois.
+
+Si vous commencez tout juste à mettre en place des pratiques d’accessibilité pour votre documentation, envisagez une approche progressive : commencez par les changements à fort impact, puis étoffez progressivement.
+
+
+ ### Premiers pas
+
+
+Voici trois actions que vous pouvez entreprendre dès maintenant pour améliorer l’accessibilité de votre documentation :
+
+1. **Exécutez `mint a11y`** pour identifier les problèmes d’accessibilité dans votre contenu.
+2. **Ajoutez un texte alternatif (alt text)** à toutes les images.
+3. **Vérifiez la hiérarchie des titres** pour garantir un seul H1 par page et des titres qui se suivent dans l’ordre.
+
+
+ ### Planifiez votre travail en matière d’accessibilité
+
+
+Le meilleur flux de travail est celui qui convient à votre équipe. Voici une approche possible de l’accessibilité :
+
+**Phase 1 : Images et structure**
+
+- Passez en revue toutes les images pour vérifier la présence d’un texte alternatif descriptif.
+- Passez en revue les textes de lien et remplacez les formules génériques comme « cliquez ici ».
+- Corrigez les problèmes de hiérarchie des titres dans l’ensemble de votre documentation.
+
+**Phase 2 : Navigation et médias**
+
+- Testez la navigation au clavier sur votre documentation.
+- Testez la compatibilité avec les lecteurs d’écran.
+- Ajoutez des sous-titres et des transcriptions aux vidéos intégrées.
+- Vérifiez le contraste des couleurs.
+
+**Phase 3 : Intégrez-la à votre flux de travail**
+
+- Exécutez `mint a11y` avant de publier un nouveau contenu.
+- Intégrez des vérifications d’accessibilité à votre processus de relecture de contenu.
+- Testez la navigation au clavier lors de l’ajout de fonctionnalités interactives.
+- Vérifiez que les nouveaux liens externes et contenus intégrés incluent des titles et descriptions appropriés.
+
+Commencer modestement et intégrer l’accessibilité à votre flux de travail habituel la rend pérenne. Chaque amélioration aide davantage d’utilisateurs à accéder avec succès à votre documentation.
+
+
+ ## Structurez votre contenu
+
+
+Un contenu bien structuré est plus facile à parcourir et à comprendre, surtout pour les utilisateurs de lecteurs d’écran qui s’appuient sur les titres pour se déplacer dans les pages, ainsi que pour les personnes qui utilisent la navigation au clavier.
+
+
+ ### Utilisez une hiérarchie de titres correcte
+
+
+Chaque page doit comporter un seul titre H1, défini par la propriété `title:` dans le frontmatter de la page. Utilisez ensuite les niveaux de titres dans l’ordre sans en sauter. Par exemple, ne passez pas de H2 à H4.
+
+```mdx
+
+# Titre de la page (H1)
+
+## Section principale (H2)
+
+### Sous-section (H3)
+
+### Autre sous-section (H3)
+
+## Autre section principale (H2)
+
+
+# Titre de la page (H1)
+
+## Section principale (H2)
+
+#### Sous-section (H4)
+
+### Autre sous-section (H3)
+```
+
+Les titres d’un même niveau doivent avoir des noms uniques.
+
+```mdx
+
+## Conseils d'accessibilité (H2)
+
+### Rédiger un texte alternatif efficace (H3)
+
+### Utiliser un contraste de couleur approprié (H3)
+
+
+## Conseils d'accessibilité (H2)
+
+### Conseil (H3)
+
+### Conseil (H3)
+```
+
+
+
+ ### Rédigez un texte de lien descriptif
+
+
+Le texte du lien doit être explicite et refléter la destination. Évitez les formulations vagues comme « cliquez ici » ou « en savoir plus ».
+
+```mdx
+
+Découvrez comment [configurer votre navigation](/organize/navigation).
+
+
+[En savoir plus](/organize/navigation).
+```
+
+
+
+ ### Facilitez le survol du contenu
+
+
+- Scindez les longs paragraphes.
+- Utilisez des listes pour les étapes et les options.
+- Mettez en avant les informations avec des encadrés.
+
+
+ ### Utilisez une structure de tableau appropriée
+
+
+N’utilisez les tableaux qu’avec parcimonie et uniquement pour des données tabulaires dont la signification découle des en-têtes de colonnes et de lignes.
+
+Lorsque vous utilisez des tableaux, incluez des en-têtes afin que les lecteurs d’écran puissent associer les données à la bonne colonne :
+
+```mdx
+| Fonctionnalité | Statut |
+| -------------- | ------ |
+| Recherche | Actif |
+| Analytics | Actif |
+```
+
+
+
+ ## Rédiger un texte alternatif descriptif
+
+
+Le texte alternatif rend les images accessibles aux utilisateurs de lecteurs d’écran et s’affiche lorsque les images ne se chargent pas. Les images de votre documentation doivent comporter un texte alternatif qui décrit l’image et précise clairement pourquoi elle est incluse. Même avec un texte alternatif, ne vous fiez pas uniquement aux images pour transmettre des informations. Assurez-vous que votre contenu décrit ce que l’image communique.
+
+
+ ### Rédigez un texte alternatif efficace
+
+
+* **Soyez précis** : Décrivez ce que montre l’image, pas seulement que c’est une image.
+* **Soyez concis** : Contentez-vous d’une à deux phrases.
+* **Évitez les redondances** : Ne commencez pas par « Image de » car les lecteurs d’écran savent déjà que le texte alternatif est associé à une image. En revanche, incluez des formulations comme « Capture d’écran de » ou « Schéma de » si ce contexte est important pour l’image.
+
+```mdx
+
+
+
+
+
+```
+
+
+
+ ### Ajouter un texte alternatif aux images
+
+
+Pour les images en Markdown, ajoutez un texte alternatif entre crochets :
+
+```mdx
+
+```
+
+Pour les images HTML, utilisez l’attribut « alt » :
+
+```html
+
+```
+
+
+
+ ### Ajouter des titres au contenu intégré
+
+
+Les iframes et les vidéos intégrées doivent avoir des titres descriptifs :
+
+```html
+
+```
+
+
+
+ ## Concevoir pour la lisibilité
+
+
+Les choix de conception visuelle influencent l’accessibilité de votre documentation pour les personnes ayant une basse vision, un daltonisme ou d’autres déficiences visuelles.
+
+
+ ### Assurez un contraste de couleurs suffisant
+
+
+Si vous personnalisez les couleurs de votre thème, vérifiez que les taux de contraste respectent les exigences WCAG :
+
+- Texte courant : taux de contraste minimal de 4,5:1
+- Texte large : taux de contraste minimal de 3:1
+- Éléments interactifs : taux de contraste minimal de 3:1
+
+Testez le mode light et le mode sombre. La commande `mint a11y` vérifie le contraste des couleurs.
+
+
+ ### Ne vous fiez pas uniquement à la couleur
+
+
+Si vous utilisez la couleur pour transmettre une information, ajoutez également un libellé textuel ou une icône. Par exemple, ne signalez pas les erreurs uniquement avec du texte rouge. Ajoutez une icône d’erreur ou le mot « Erreur ».
+
+
+ ### Utilisez un langage clair et concis
+
+
+- Écrivez en langage simple.
+- Définissez les termes techniques lors de leur première occurrence.
+- Évitez les phrases à rallonge.
+- Employez la voix active.
+
+
+ ## Rendre les exemples de code accessibles
+
+
+Les code blocks sont un élément essentiel de la documentation technique, mais ils nécessitent des considérations d’accessibilité spécifiques pour que les utilisateurs de lecteurs d’écran puissent les comprendre. De manière générale, suivez ces recommandations :
+
+- Divisez les longs exemples de code en sections plus petites et cohérentes.
+- Commentez la logique complexe dans le code.
+- Envisagez de fournir une description textuelle pour les algorithmes complexes.
+- Lors de la présentation d’une arborescence de fichiers, utilisez de vrais code blocks avec des labels de langage plutôt que de l’art ASCII.
+
+
+ ### Indiquez le langage de programmation
+
+
+Déclarez toujours la langue pour la coloration syntaxique. Cela aide les lecteurs d’écran à annoncer le contexte du code aux utilisateurs :
+
+````mdx
+```javascript
+function getUserData(id) {
+ return fetch(`/api/users/${id}`);
+}
+```
+````
+
+
+
+ ### Fournir du contexte autour du code
+
+
+Fournissez un contexte clair pour les code block :
+
+````mdx
+La fonction suivante récupère les données utilisateur depuis l'API :
+
+```javascript
+function getUserData(id) {
+ return fetch(`/api/users/${id}`);
+}
+```
+
+Cela retourne une promesse qui se résout vers l'objet utilisateur.
+````
+
+
+
+ ## Accessibilité des vidéos et des contenus multimédias
+
+
+Les vidéos, animations et autres contenus multimédias doivent être accompagnés d’alternatives textuelles afin que tous les utilisateurs puissent accéder aux informations qu’ils contiennent.
+
+
+ ### Ajouter des sous-titres aux vidéos
+
+
+Les sous-titres rendent le contenu vidéo accessible aux personnes sourdes ou malentendantes. Ils aident aussi les utilisateurs dans des environnements sensibles au bruit ainsi que les personnes non natives :
+
+- Utilisez des sous-titres pour tout le contenu parlé des vidéos.
+- Incluez les effets sonores pertinents dans les sous-titres.
+- Assurez-vous que les sous-titres sont synchronisés avec l’audio.
+- Utilisez une ponctuation appropriée et identifiez les locuteurs lorsque plusieurs personnes parlent.
+
+La plupart des plateformes d’hébergement vidéo permettent d’ajouter des sous-titres. Importez des fichiers de sous-titres ou utilisez des sous-titres générés automatiquement comme point de départ, puis vérifiez leur exactitude.
+
+
+ ### Fournir des transcriptions
+
+
+Les transcriptions offrent un autre moyen d’accéder au contenu vidéo. Elles sont consultables par recherche, plus faciles à référencer et accessibles aux lecteurs d’écran :
+
+```mdx
+
+
+
+Dans ce tutoriel, nous allons voir comment configurer l'authentification...
+
+```
+
+Placez les transcriptions à proximité de la vidéo ou fournissez un lien clair pour y accéder.
+
+
+
+ ### Envisagez des alternatives au contenu exclusivement vidéo
+
+
+Si des informations essentielles ne figurent que dans une vidéo :
+
+- Fournissez les mêmes informations sous forme de texte.
+- Ajoutez des captures d’écran clés avec un texte alternatif descriptif.
+- Rédigez un tutoriel qui couvre la même matière.
+
+Ainsi, les utilisateurs qui n’ont pas accès au contenu vidéo peuvent tout de même mener à bien leur tâche.
+
+
+ ## Testez votre documentation
+
+
+Des tests réguliers vous aident à repérer les problèmes d’accessibilité avant que les utilisateurs ne les rencontrent.
+
+
+ ### Vérifiez les problèmes d’accessibilité avec `mint a11y`
+
+
+Utilisez la commande d’interface en ligne de commande (CLI) `mint a11y` pour analyser automatiquement votre documentation à la recherche de problèmes d’accessibilité courants :
+
+```bash
+mint a11y
+```
+
+La commande vérifie :
+
+* Texte alternatif manquant pour les images
+* Hiérarchie des titres incorrecte
+* Contraste des couleurs insuffisant
+
+Lorsque l’analyse est terminée, passez en revue les problèmes signalés et corrigez-les dans votre objet. Exécutez de nouveau la commande pour valider vos corrections.
+
+
+
+ ### Test de base de la navigation au clavier
+
+
+Parcourez votre documentation en utilisant uniquement votre clavier :
+
+1. Appuyez sur Tab pour avancer dans les éléments interactifs.
+2. Appuyez sur Shift + Tab pour revenir en arrière.
+3. Appuyez sur Enter pour activer les liens et les boutons.
+4. Vérifiez que tous les éléments interactifs sont accessibles et affichent un indicateur de focus visible.
+
+
+ ### Approfondissez vos tests d’accessibilité
+
+
+Pour des évaluations plus complètes :
+
+- **Lecteurs d’écran** : Testez avec [NVDA (Windows)](https://www.nvaccess.org/) ou [VoiceOver (Mac)](https://www.apple.com/accessibility/voiceover/).
+- **Extensions de navigateur** : Installez [axe DevTools](https://www.deque.com/axe/browser-extensions/) ou [WAVE](https://wave.webaim.org/extension/) pour analyser les pages et détecter les problèmes.
+- **Directives WCAG** : Consultez les [Web Content Accessibility Guidelines](https://www.w3.org/WAI/WCAG22/quickref/) pour connaître les normes détaillées.
+
+
+ ## Ressources supplémentaires
+
+
+Approfondissez vos connaissances en accessibilité avec ces ressources de confiance :
+
+- **[WebAIM](https://webaim.org/)** : articles et tutoriels pratiques sur l’accessibilité du web
+- **[The A11y Project](https://www.a11yproject.com/)** : ressources communautaires et liste de vérification sur l’accessibilité
+- **[W3C Web Accessibility Initiative (WAI)](https://www.w3.org/WAI/)** : normes officielles et recommandations en matière d’accessibilité
\ No newline at end of file
diff --git a/zh/guides/accessibility.mdx b/zh/guides/accessibility.mdx
new file mode 100644
index 000000000..aa7d5af14
--- /dev/null
+++ b/zh/guides/accessibility.mdx
@@ -0,0 +1,398 @@
+---
+title: "无障碍"
+description: "编写尽可能多的人都能使用的文档"
+---
+
+当你编写无障碍文档时，会优先采用让尽可能多的人都能使用的内容设计，无论他们以何种方式访问和与文档交互。
+
+无障碍文档能提升所有人的使用体验。你的内容会更清晰、结构更合理，也更易于浏览和导航。
+
+本指南提供了一些创建无障碍文档的最佳实践，但并不全面。你应将无障碍视为一项持续的工作。随着时间推移，技术和标准不断变化，这也带来了改进文档的新机会。
+
+
+
+通过以下权威资源继续学习无障碍：
+
+- **[WebAIM](https://webaim.org/)**：关于网页无障碍的实用文章与教程
+- **[The A11y Project](https://www.a11yproject.com/)**：社区驱动的无障碍资源与检查清单
+- **[W3C Web Accessibility Initiative (WAI)](https://www.w3.org/WAI/)**：官方无障碍标准与指南
\ No newline at end of file
+```
+
+
+