From ec15d3f3d61ae8d4899105b5da7776b5ce2c6617 Mon Sep 17 00:00:00 2001
From: Bryan <bgoswaldo@gmail.com>
Date: Sun, 1 Nov 2026 19:15:26 -0600
Subject: [PATCH 1/3] docs(readme): translate to English and document
 accessibility

Also lists the supported peer ranges and the accessibilityLabels prop,
and links the contributing guide.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 README.md | 537 ++++++++++++++++++++++++++++--------------------------
 1 file changed, 281 insertions(+), 256 deletions(-)

diff --git a/README.md b/README.md
index 72f96b8..bca475a 100644
--- a/README.md
+++ b/README.md
@@ -2,54 +2,55 @@
 
 > npm: [`@acertijosapps/react-native-md-document`](https://www.npmjs.com/package/@acertijosapps/react-native-md-document)
 
-Visor de documentos **Markdown-como-PDF** para React Native: documento inmutable, con paso
-de hoja animado, zoom, subrayado persistente, text-to-speech con resaltado sincronizado y
-tema claro/oscuro. Sin librerías de terceros para el contenido (parser y render propios); el
-storage, el origen del documento y el motor de voz son inyectables.
+**Markdown-as-PDF** document viewer for React Native: an immutable document with animated
+page-turning, zoom, persistent highlights, text-to-speech with synchronized word highlighting
+and a light/dark theme. No third-party libraries for the content (own parser and renderer); the
+storage, the document source and the speech engine are injectable.
 
-## Vista previa
+## Preview
 
-Documento de demostración (`example/`) en tema claro y oscuro: banner con tokens de marca,
-estilos en línea, resaltado y adaptación de color por tema.
+Demo document (`example/`) in light and dark themes: banner with brand tokens, inline styles,
+highlights and per-theme color adaptation.
 
-| Claro | Oscuro |
+| Light | Dark |
 |---|---|
-| <img src="https://unpkg.com/@acertijosapps/react-native-md-document/media/showcase-light.png" alt="Tema claro" width="300" /> | <img src="https://unpkg.com/@acertijosapps/react-native-md-document/media/showcase-dark.png" alt="Tema oscuro" width="300" /> |
-
-## Características
-
-- **Render Markdown** + **HTML embebido**: encabezados, párrafos, listas, blockquote, code,
-  `hr`, estilos en línea (negrita, cursiva, código, tachado, enlaces), **tablas** y HTML con
-  estilos inline (color, fondo, centrado, tamaños, anchos de columna).
-- **Paso de hoja** animado (Reanimated + Gesture Handler), un gesto = una página.
-- **Zoom** por pinch + arrastre, compuesto con el flip y el tap.
-- **Subrayado** por palabra, **persistente entre sesiones** (storage inyectable).
-- **Text-to-speech** con resaltado de la palabra hablada (incluso en tablas), pausa/reanudar,
-  velocidad, y auto-avance de página siguiendo la lectura.
-- **Tema claro/oscuro** (`auto` sigue el SO) con tokens de color adaptables por tema.
-- **Orígenes**: URL remota, ruta local del dispositivo, ruta del proyecto.
-- **Orientación** vertical y horizontal (re-pagina al rotar).
-- **Modo libro**: en tablets y plegables en horizontal muestra dos páginas lado a lado, con
-  el volteo de hoja desde el lomo. Activo por defecto; se desactiva con `dualPage={false}`.
-
-## Requisitos
-
-| Plataforma | Mínimo | Nota |
+| <img src="https://unpkg.com/@acertijosapps/react-native-md-document/media/showcase-light.png" alt="Light theme" width="300" /> | <img src="https://unpkg.com/@acertijosapps/react-native-md-document/media/showcase-dark.png" alt="Dark theme" width="300" /> |
+
+## Features
+
+- **Markdown** + **embedded HTML**: headings, paragraphs, lists, blockquotes, code, `hr`,
+  inline styles (bold, italic, code, strikethrough, links), **tables** and HTML with inline
+  styles (color, background, centering, sizes, column widths).
+- Animated **page turning** (Reanimated + Gesture Handler), one gesture = one page.
+- **Zoom** with pinch + drag, composed with the flip and the tap.
+- **Per-word highlights**, **persistent across sessions** (injectable storage).
+- **Text-to-speech** with the spoken word highlighted (even inside tables), pause/resume,
+  speed, and automatic page advance that follows the reading.
+- **Light/dark theme** (`auto` follows the OS) with color tokens that adapt per theme.
+- **Sources**: remote URL, local device path, bundled project file.
+- **Portrait and landscape** orientation (re-paginates on rotation).
+- **Book mode**: on tablets and foldables in landscape it shows two pages side by side, with
+  the page turning from the spine. On by default; turn it off with `dualPage={false}`.
+- **Accessible**: screen readers (VoiceOver, TalkBack) hear the current page, can turn pages
+  with a swipe up/down, and skip the pages hidden behind the flip animation.
+
+## Requirements
+
+| Platform | Minimum | Note |
 |---|---|---|
-| **iOS** | 13.0 | Deployment target del módulo nativo (`react-native-md-document.podspec`). TTS con resaltado por palabra incluido. |
-| **Android** | 7.0 (API 24) | `minSdkVersion` del módulo. El TTS habla en API 24+, pero el **resaltado por palabra** durante la lectura usa `onRangeStart`, que requiere **Android 8.0 (API 26)**. |
-| **React Native** | 0.76 | Probado con RN 0.76.5 / Expo SDK 52. |
-| **Peer deps** | `react-native-reanimated` ≥ 3.16 · `react-native-gesture-handler` ≥ 2.20 | Únicas dependencias visuales. |
+| **iOS** | 13.0 | Deployment target of the native module (`react-native-md-document.podspec`). TTS with per-word highlighting included. |
+| **Android** | 7.0 (API 24) | The module's `minSdkVersion`. TTS speaks on API 24+, but the **per-word highlighting** while reading uses `onRangeStart`, which requires **Android 8.0 (API 26)**. |
+| **React Native** | 0.76 | Tested with RN 0.76.5 / Expo SDK 52. |
+| **Peer deps** | `react-native-reanimated` ≥ 3.16 and < 4 · `react-native-gesture-handler` ≥ 2.20 and < 3 | The only visual dependencies. Reanimated 4 and Gesture Handler 3 are not supported yet. |
 
 ### Android 16 KB (page size)
 
-**Compatible.** `react-native-md-document` **no incluye código nativo compilado**
-(`.so`): el módulo `DocumentSpeech` es Kotlin puro y se compila al dex de la
-app. Al no aportar binarios, no hay librerías desalineadas de nuestra parte —
-la librería cumple el requisito de 16 KB de Android 15 (Google Play, `targetSdk
-35`) por construcción, en cualquier tamaño de página.
+**Compatible.** `react-native-md-document` **ships no compiled native code** (`.so`): the
+`DocumentSpeech` module is plain Kotlin and is compiled into the app's dex. Since it adds no
+binaries, none of our libraries can be misaligned — the library meets Android 15's 16 KB
+requirement (Google Play, `targetSdk 35`) by construction, on any page size.
 
-## Instalación
+## Installation
 
 ```sh
 # npm
@@ -59,7 +60,7 @@ npm install @acertijosapps/react-native-md-document react-native-gesture-handler
 yarn add @acertijosapps/react-native-md-document react-native-gesture-handler react-native-reanimated
 ```
 
-`react-native-reanimated` requiere su plugin de Babel (último en la lista):
+`react-native-reanimated` requires its Babel plugin (last in the list):
 
 ```js
 // babel.config.js
@@ -69,7 +70,7 @@ module.exports = {
 };
 ```
 
-La app debe envolver la raíz en `GestureHandlerRootView`:
+The app must wrap its root in `GestureHandlerRootView`:
 
 ```tsx
 import { GestureHandlerRootView } from 'react-native-gesture-handler';
@@ -79,92 +80,91 @@ export default function App() {
 }
 ```
 
-Para el **text-to-speech nativo**, el módulo `DocumentSpeech` se autoenlaza como cualquier
-paquete RN:
+For **native text-to-speech**, the `DocumentSpeech` module is autolinked like any RN package:
 
 ```sh
-npx pod-install          # iOS (o: cd ios && pod install)
-# Android: autolinking por gradle, sin pasos extra
+npx pod-install          # iOS (or: cd ios && pod install)
+# Android: Gradle autolinking, no extra steps
 ```
 
-### Dependencias opcionales
+### Optional dependencies
 
-- **Almacenamiento del subrayado**: la librería **no** depende de
-  `@react-native-async-storage/async-storage`. El store es inyectable
-  (`getItem`/`setItem`, sync o async): sirve AsyncStorage, MMKV, SQLite o el
-  tuyo. Instálalo **solo si** quieres persistir subrayados con esa opción; para
-  subrayado en memoria usa `createMemoryHighlightStore()`, y sin subrayado no
-  necesitas nada. Ver [Subrayado persistente](#subrayado-persistente).
+- **Highlight storage**: the library does **not** depend on
+  `@react-native-async-storage/async-storage`. The store is injectable
+  (`getItem`/`setItem`, sync or async): AsyncStorage, MMKV, SQLite or your own will do. Install
+  it **only if** you want to persist highlights with that option; for in-memory highlights use
+  `createMemoryHighlightStore()`, and if you don't highlight you need nothing. See
+  [Persistent highlights](#persistent-highlights).
 
-Únicas dependencias obligatorias: `react-native-reanimated` y
-`react-native-gesture-handler` (los peers).
+The only required dependencies are `react-native-reanimated` and
+`react-native-gesture-handler` (the peers).
 
-## Inicio rápido
+## Quick start
 
 ```tsx
 import { DocumentViewer, parse } from '@acertijosapps/react-native-md-document';
 
-const doc = parse('# Hola\n\nUn documento **Markdown**.');
+const doc = parse('# Hello\n\nA **Markdown** document.');
 
 export function Viewer() {
     return <DocumentViewer document={doc} />;
 }
 ```
 
-`DocumentViewer` mide el contenido, lo pagina al tamaño del viewport y habilita flip + zoom.
-`parse(source)` devuelve un `MDDocument` inmutable con `plainText` (la proyección de texto que
-usan highlight y TTS).
+`DocumentViewer` measures the content, paginates it to the viewport size and enables flip +
+zoom. `parse(source)` returns an immutable `MDDocument` with `plainText` (the text projection
+that highlights and TTS rely on).
 
-## Orígenes del documento
+## Document sources
 
-`useDocumentSource` cubre los tres orígenes:
+`useDocumentSource` covers the three sources:
 
 ```tsx
 import { DocumentViewer, useDocumentSource } from '@acertijosapps/react-native-md-document';
 
 function Screen() {
-    // Proyecto (bundled): string o { markdown }
+    // Project (bundled): string or { markdown }
     const { document, isLoading, error, reload } = useDocumentSource({ markdown: MD_STRING });
-    // URL remota: fetch integrado
+    // Remote URL: built-in fetch
     // useDocumentSource({ uri: 'https://example.com/doc.md' })
-    // Ruta local del dispositivo
+    // Local device path
     // useDocumentSource({ uri: 'file:///…/doc.md' })
 
     if (!document) {
-        return null; // isLoading / error / reload disponibles
+        return null; // isLoading / error / reload are available
     }
     return <DocumentViewer document={document} />;
 }
 ```
 
-Detección de string: con `http(s)://`, `file:`, `content:`, `asset:` o que empiece con `/` se
-trata como URI; cualquier otro string es Markdown crudo.
+String detection: a string starting with `http(s)://`, `file:`, `content:`, `asset:` or `/` is
+treated as a URI; any other string is raw Markdown.
 
-### Carga gestionada por el visor
+### Viewer-managed loading
 
-Si no quieres cablear el hook a mano, pasa `source` directo a `DocumentViewer`: carga solo y
-expone los estados de carga.
+If you don't want to wire the hook by hand, pass `source` straight to `DocumentViewer`: it
+loads on its own and exposes the loading states.
 
 ```tsx
 <DocumentViewer
     source={{ uri: 'https://example.com/doc.md' }}
-    onLoadComplete={(doc) => console.log('listo', doc.length)}
+    onLoadComplete={(doc) => console.log('ready', doc.length)}
     onLoadError={(err) => console.warn(err.message)}
     renderLoading={() => <ActivityIndicator />}
     renderError={(err, retry) => (
         <View>
             <Text>{err.message}</Text>
-            <Button title="Reintentar" onPress={retry} />
+            <Button title="Retry" onPress={retry} />
         </View>
     )}
 />
 ```
 
-Usa `document` (control total: highlights/TTS necesitan `document.plainText` antes de render) o
-`source` (el visor gestiona la carga). Los cuatro props anteriores solo aplican con `source`.
+Use `document` (full control: highlights/TTS need `document.plainText` before rendering) or
+`source` (the viewer manages the loading). The four props above only apply with `source`.
 
-Para orígenes que `fetch` no cubre (asset del bundle, `file://` en Android) se inyecta un
-lector — la librería **no fuerza** `expo-file-system` ni `expo-asset`:
+For sources that `fetch` doesn't cover (a bundled asset, `file://` on Android) you inject a
+reader — the library **does not force** `expo-file-system` or `expo-asset`:
 
 ```tsx
 import * as FileSystem from 'expo-file-system';
@@ -175,33 +175,33 @@ useDocumentSource(
 );
 ```
 
-## Subrayado persistente
+## Persistent highlights
 
 ```tsx
 import { DocumentViewer, createKeyValueHighlightStore, useHighlights } from '@acertijosapps/react-native-md-document';
 import AsyncStorage from '@react-native-async-storage/async-storage';
 
-const store = createKeyValueHighlightStore(AsyncStorage); // sirve para AsyncStorage/MMKV
+const store = createKeyValueHighlightStore(AsyncStorage); // works with AsyncStorage/MMKV
 
 function Screen({ document }) {
     const { highlights, toggleWordAt, remove, clear, isLoaded } = useHighlights({
         docId: 'doc-1',
         plainText: document.plainText,
-        store, // sin store: solo en memoria
+        store, // no store: in memory only
     });
     return (
         <DocumentViewer
             document={document}
             highlights={highlights}
-            onWordPress={toggleWordAt} // toca una palabra para subrayar / quitar
+            onWordPress={toggleWordAt} // tap a word to highlight / remove it
         />
     );
 }
 ```
 
-Cada subrayado es `{ id, start, end, color? }` en el espacio de offsets de la proyección. Como
-el documento es **inmutable**, ese espacio es estable entre sesiones, tamaños de pantalla y
-re-render. `createMemoryHighlightStore()` sirve para tests/demo.
+Each highlight is `{ id, start, end, color? }` in the projection's offset space. Because the
+document is **immutable**, that space is stable across sessions, screen sizes and re-renders.
+`createMemoryHighlightStore()` is handy for tests/demos.
 
 ## Text-to-speech
 
@@ -213,8 +213,8 @@ import {
     useTextToSpeech,
 } from '@acertijosapps/react-native-md-document';
 
-// Motor nativo propio (iOS AVSpeechSynthesizer / Android TextToSpeech).
-// Cae al mock (por timer, sin audio) si el módulo nativo no está enlazado.
+// Own native engine (iOS AVSpeechSynthesizer / Android TextToSpeech).
+// Falls back to the mock (timer-based, no audio) if the native module isn't linked.
 function makeEngine() {
     try {
         return createNativeSpeechEngine();
@@ -229,24 +229,24 @@ function Screen({ document }) {
     const tts = useTextToSpeech({
         plainText: document.plainText,
         engine,
-        options: { rate: 1 }, // multiplicador de velocidad
+        options: { rate: 1 }, // speed multiplier
     });
 
     const onPress = () => {
         if (tts.status === 'speaking') tts.pause();
         else if (tts.status === 'paused') tts.resume();
-        else tts.play(pageStart); // arranca en el inicio de la página actual
+        else tts.play(pageStart); // starts at the beginning of the current page
     };
 
     return (
         <>
             <DocumentViewer
                 document={document}
-                active={tts.activeRange} // resalta la palabra hablada y auto-avanza de página
+                active={tts.activeRange} // highlights the spoken word and auto-advances the page
                 onPageChange={(index, count, startOffset) => setPageStart(startOffset)}
             />
             <Button
-                title={tts.status === 'speaking' ? 'Pausa' : tts.status === 'paused' ? 'Reanudar' : 'Leer'}
+                title={tts.status === 'speaking' ? 'Pause' : tts.status === 'paused' ? 'Resume' : 'Read'}
                 onPress={onPress}
             />
         </>
@@ -254,49 +254,51 @@ function Screen({ document }) {
 }
 ```
 
-- `useTextToSpeech` devuelve `{ status, activeRange, index, count, play, pause, resume, stop }`.
-  `status` es `'idle' | 'speaking' | 'paused'`.
-- `play(fromOffset?)` arranca en la utterance que cubre ese offset (usa `pageStartOffset` de
-  `onPageChange` para leer desde la página actual). `pause`/`resume` conservan la posición
-  (nativo: mitad de utterance). `stop` reinicia.
-- `activeRange` es la palabra hablada en offsets de proyección; el visor la resalta con
-  `colors.activeWord` y **auto-avanza de página** para seguir la lectura.
-- `options.rate` es un multiplicador (1 = normal). Android lo aplica directo; iOS usa una
-  curva sobre la velocidad por defecto de `AVSpeechUtterance`.
-- El motor es inyectable (`SpeechEngine`): nativo propio, mock, o el tuyo
-  (`speak`, `stop`, opcional `pause`/`resume`).
+- `useTextToSpeech` returns `{ status, activeRange, index, count, play, pause, resume, stop }`.
+  `status` is `'idle' | 'speaking' | 'paused'`.
+- `play(fromOffset?)` starts at the utterance that covers that offset (use `pageStartOffset`
+  from `onPageChange` to read from the current page). `pause`/`resume` keep the position
+  (native: mid-utterance). `stop` resets.
+- `activeRange` is the spoken word in projection offsets; the viewer highlights it with
+  `colors.activeWord` and **auto-advances the page** to follow the reading.
+- `options.rate` is a multiplier (1 = normal). Android applies it directly; iOS uses a curve
+  over the default `AVSpeechUtterance` rate.
+- The engine is injectable (`SpeechEngine`): the built-in native one, the mock, or your own
+  (`speak`, `stop`, optional `pause`/`resume`).
 
-## Tema y tokens de color
+## Theme and color tokens
 
 ```tsx
 <DocumentViewer
     document={doc}
-    colorScheme="auto" // 'auto' (default, sigue el SO) | 'light' | 'dark'
-    theme={{ colors: { link: '#c026d3' } }} // override parcial sobre la paleta del modo activo
+    colorScheme="auto" // 'auto' (default, follows the OS) | 'light' | 'dark'
+    theme={{ colors: { link: '#c026d3' } }} // partial override over the active mode's palette
 />
 ```
 
 `useDocTheme(colorScheme, override, colorTokens?)`, `useColorMode(colorScheme)`, `lightTheme`,
-`darkTheme` y `mergeTheme` están exportados para teñir tu propio chrome con la misma resolución.
+`darkTheme` and `mergeTheme` are exported so you can tint your own chrome with the same
+resolution.
 
-### Documentos con color que se adaptan al tema
+### Theme-adaptive colored documents
 
-Un `.md` con HTML embebido que hardcodea colores (`background:#FFFFFF`, `color:#006847`) **no
-cambia** en modo oscuro. El sub-estándar: el archivo usa **tokens** `var(--token)` en vez de
-literales, y el visor los resuelve contra la paleta activa. Mezclar literales y tokens es
-válido (retrocompatible).
+A `.md` with embedded HTML that hardcodes colors (`background:#FFFFFF`, `color:#006847`) does
+**not** change in dark mode. The sub-standard: the file uses `var(--token)` **tokens** instead
+of literals, and the viewer resolves them against the active palette. Mixing literals and
+tokens is valid (backwards compatible).
 
 ```html
-<div style="background: var(--accent); color: var(--on-accent);">…barra…</div>
-<p style="color: var(--accent-text); font-style: italic;">…nota…</p>
-<p style="color: var(--text);">…cuerpo…</p>
+<div style="background: var(--accent); color: var(--on-accent);">…banner…</div>
+<p style="color: var(--accent-text); font-style: italic;">…note…</p>
+<p style="color: var(--text);">…body…</p>
 ```
 
-Dos clases de token:
+Two kinds of token:
 
-- **Base — los define la librería** (su propia paleta light/dark, sin adivinar):
+- **Base — defined by the library** (its own light/dark palette, no guessing):
   `--page-bg`, `--text`, `--heading`, `--rule`, `--link`, `--code`, `--highlight`.
-- **Marca/custom — los provee el consumidor** por prop `colorTokens`, con valores por modo:
+- **Brand/custom — provided by the consumer** through the `colorTokens` prop, with per-mode
+  values:
 
 ```tsx
 <DocumentViewer
@@ -309,100 +311,126 @@ Dos clases de token:
 />
 ```
 
-Un token que no es base **ni** está en `colorTokens` del modo activo se **omite** (la librería
-no inventa colores). El fondo de página y el texto salen siempre de la paleta base, así que un
-documento sin tokens de marca ya respeta claro/oscuro.
+A token that is not a base token **and** is not in the active mode's `colorTokens` is
+**omitted** (the library never invents colors). The page background and the text always come
+from the base palette, so a document without brand tokens already respects light/dark.
 
-## Gestos
+## Gestures
 
-- **Swipe horizontal** → pasa de página (flip). Un gesto = una página.
-- **Pinch** → zoom; con zoom, **arrastrar** mueve la página (el flip se bloquea). Prop
+- **Horizontal swipe** → turns the page (flip). One gesture = one page.
+- **Pinch** → zoom; while zoomed, **dragging** moves the page (the flip is locked). Prop
   `maxScale` (default 3).
-- **Tap** en una palabra → `onWordPress(offset)`.
+- **Tap** on a word → `onWordPress(offset)`.
 
-El pan solo captura arrastre real (umbral), dejando pasar el tap.
+The pan only captures a real drag (threshold), letting the tap through.
 
-## Orientación
+## Accessibility
 
-El visor es *size-driven*: al rotar, mide el nuevo tamaño y **re-pagina** solo. Habilitá
-landscape en la config nativa de tu app (Expo: `app.json` `orientation: "default"`; RN puro:
-`UISupportedInterfaceOrientations` en iOS y `android:screenOrientation` en Android). En
-horizontal, usá `SafeAreaProvider` de `react-native-safe-area-context` con
-`initialMetrics={initialWindowMetrics}` para insets correctos desde el primer frame. En
-tablets y plegables, el horizontal activa el [modo libro](#modo-libro-dos-páginas).
+The viewer works with VoiceOver (iOS) and TalkBack (Android) out of the box:
 
-## Modo libro (dos páginas)
+- An invisible **adjustable control** at the top of the viewer announces the position
+  ("Page 3 of 12", or "Pages 3 and 4 of 12" in [book mode](#book-mode-two-pages)). Swipe up or
+  down on it (or use the actions menu) to go to the next or previous page.
+- The pages stacked behind the current one for the flip animation are **hidden from the
+  accessibility tree**, so the screen reader only reads what is visible.
+- Headings are exposed with the `header` role.
 
-En tablets y plegables en horizontal, el visor divide el área en dos páginas y las voltea
-como un libro abierto. Está **activo por defecto**; se desactiva con `dualPage={false}`.
+The spoken strings are in English; override any of them with `accessibilityLabels`:
 
-| Horizontal · claro | Horizontal · oscuro |
+```tsx
+<DocumentViewer
+    document={doc}
+    accessibilityLabels={{
+        control: 'Páginas del documento',
+        pages: (first, last, total) =>
+            first === last ? `Página ${first} de ${total}` : `Páginas ${first} y ${last} de ${total}`,
+        nextPage: 'Página siguiente',
+        previousPage: 'Página anterior',
+    }}
+/>
+```
+
+## Orientation
+
+The viewer is *size-driven*: on rotation it measures the new size and **re-paginates** by
+itself. Enable landscape in your app's native config (Expo: `app.json` `orientation:
+"default"`; bare RN: `UISupportedInterfaceOrientations` on iOS and `android:screenOrientation`
+on Android). In landscape, use `SafeAreaProvider` from `react-native-safe-area-context` with
+`initialMetrics={initialWindowMetrics}` for correct insets from the first frame. On tablets
+and foldables, landscape turns on [book mode](#book-mode-two-pages).
+
+## Book mode (two pages)
+
+On tablets and foldables in landscape, the viewer splits the area into two pages and turns
+them like an open book. It is **on by default**; turn it off with `dualPage={false}`.
+
+| Landscape · light | Landscape · dark |
 |---|---|
-| <img src="https://unpkg.com/@acertijosapps/react-native-md-document/media/book-landscape-light.png" width="420" alt="iPad en horizontal con dos páginas del documento lado a lado" /> | <img src="https://unpkg.com/@acertijosapps/react-native-md-document/media/book-landscape-dark.png" width="420" alt="iPad en horizontal con dos páginas en tema oscuro" /> |
+| <img src="https://unpkg.com/@acertijosapps/react-native-md-document/media/book-landscape-light.png" width="420" alt="iPad in landscape with two pages of the document side by side" /> | <img src="https://unpkg.com/@acertijosapps/react-native-md-document/media/book-landscape-dark.png" width="420" alt="iPad in landscape with two pages in the dark theme" /> |
 
-En vertical se mantiene una sola hoja completa, igual que en un móvil:
+In portrait it keeps a single full page, just like on a phone:
 
-<img src="https://unpkg.com/@acertijosapps/react-native-md-document/media/book-portrait.png" width="300" alt="iPad en vertical con una sola página" />
+<img src="https://unpkg.com/@acertijosapps/react-native-md-document/media/book-portrait.png" width="300" alt="iPad in portrait with a single page" />
 
-### Cuándo se activa
+### When it turns on
 
-Se activa solo cuando se cumplen las tres condiciones:
+It only turns on when all three conditions hold:
 
-- La pantalla es de tamaño **tablet o plegable**: el lado corto de la ventana mide al menos
-  600 dp (el mismo criterio `sw600dp` de Android). Un móvil, incluso en horizontal, mantiene
-  una sola página.
-- El visor mide **más ancho que alto** (horizontal).
-- El visor mide al menos `dualPageMinWidth` dp de ancho (600 por defecto).
+- The screen is **tablet or foldable** sized: the window's short side is at least 600 dp (the
+  same `sw600dp` criterion Android uses). A phone, even in landscape, keeps a single page.
+- The viewer is **wider than tall** (landscape).
+- The viewer is at least `dualPageMinWidth` dp wide (600 by default).
 
-La decisión usa el tamaño real del visor, no el modelo del dispositivo, así que también aplica
-a plegables abiertos y a split-screen. Al rotar, el visor cambia de modo solo y conserva el
-punto de lectura.
+The decision uses the viewer's real size, not the device model, so it also applies to
+unfolded foldables and split-screen. On rotation the viewer switches mode by itself and keeps
+your reading position.
 
 ### Props
 
-| Prop | Tipo | Default | Descripción |
+| Prop | Type | Default | Description |
 |---|---|---|---|
-| `dualPage?` | `boolean` | `true` | Activa el modo libro. `false` fuerza siempre una sola página |
-| `dualPageMinWidth?` | `number` | `600` | Ancho mínimo (dp) del visor para mostrar dos páginas |
-| `spreadGap?` | `number` | `0` | Espacio (dp) entre las dos páginas; sirve para reservar la bisagra de un plegable |
+| `dualPage?` | `boolean` | `true` | Turns on book mode. `false` always forces a single page |
+| `dualPageMinWidth?` | `number` | `600` | Minimum viewer width (dp) to show two pages |
+| `spreadGap?` | `number` | `0` | Space (dp) between the two pages; use it to reserve a foldable's hinge |
 
 ```tsx
-// Siempre una sola página, también en tablets
+// Always a single page, also on tablets
 <DocumentViewer document={doc} dualPage={false} />
 ```
 
-### Comportamiento
+### Behavior
 
-- **Un gesto voltea un pliego** (dos páginas). La hoja derecha gira desde el lomo al avanzar,
-  y la izquierda al retroceder. El zoom por pinch y el arrastre actúan sobre el pliego completo.
-- **Paginación:** se calcula con el ancho de una página, así que el documento tiene más páginas
-  que en vertical. Al cambiar de modo se conserva el texto que estabas leyendo.
-- **`onPageChange(pageIndex, pageCount, pageStartOffset, pagesPerView)`:** en modo libro
-  `pageIndex` es la página **izquierda** del pliego y `pagesPerView` vale `2` (en una sola
-  página, `1`). Úsalo para mostrar "Págs. 1-2 de N".
-- **Text-to-speech:** la lectura avanza al pliego que contiene la palabra activa.
-- **Subrayado:** no cambia; sigue usando los mismos offsets del texto.
+- **One gesture turns one spread** (two pages). The right page rotates from the spine when
+  going forward, and the left one when going back. Pinch zoom and drag act on the whole
+  spread.
+- **Pagination:** it is computed with the width of one page, so the document has more pages
+  than in portrait. When the mode changes, the text you were reading is preserved.
+- **`onPageChange(pageIndex, pageCount, pageStartOffset, pagesPerView)`:** in book mode
+  `pageIndex` is the spread's **left** page and `pagesPerView` is `2` (on a single page, `1`).
+  Use it to show "Pages 1-2 of N".
+- **Text-to-speech:** the reading advances to the spread that contains the active word.
+- **Highlights:** unchanged; they keep using the same text offsets.
 
-## Plegables
+## Foldables
 
-Un plegable **abierto y plano** se comporta como una tablet: en horizontal muestra dos
-páginas, sin configuración extra.
+An **unfolded, flat** foldable behaves like a tablet: in landscape it shows two pages, with no
+extra setup.
 
-Cuando el dispositivo está **medio abierto en postura libro** (bisagra vertical), la bisagra
-queda entre las dos mitades de la pantalla. Para que ninguna página se dibuje sobre el
-pliegue, pasa su ancho en `spreadGap`: el hueco queda centrado entre las páginas.
+When the device is **half-open in book posture** (vertical hinge), the hinge sits between the
+two halves of the screen. To keep either page from being drawn over the crease, pass its width
+in `spreadGap`: the gap is centered between the pages.
 
-La librería **no detecta la bisagra ni depende de ninguna librería de plegables**. Si tu app
-usa [`@acertijosapps/react-native-fold`](https://www.npmjs.com/package/@acertijosapps/react-native-fold),
-conéctalas así:
+The library **does not detect the hinge and does not depend on any foldable library**. If your
+app uses [`@acertijosapps/react-native-fold`](https://www.npmjs.com/package/@acertijosapps/react-native-fold),
+connect them like this:
 
 > [!WARNING]
-> La detección de bisagra en **iOS requiere iOS 27.1 o superior y compilar la app con Xcode
-> 27.1 o superior** (SDK de iOS 27.1). Con un Xcode anterior la app compila, pero las APIs de
-> bisagra se omiten y `useFold()` devuelve siempre `null` en iOS, incluso en un iPhone Duo.
-> `react-native-fold` además exige **React Native ≥ 0.80 con New Architecture y React ≥ 19.1**.
-> Estos requisitos aplican a tu app solo si instalas esa librería; `react-native-md-document`
-> no los exige.
+> Hinge detection on **iOS requires iOS 27.1 or later and building the app with Xcode 27.1 or
+> later** (iOS 27.1 SDK). With an older Xcode the app builds, but the hinge APIs are skipped
+> and `useFold()` always returns `null` on iOS, even on an iPhone Duo. `react-native-fold`
+> also requires **React Native ≥ 0.80 with the New Architecture and React ≥ 19.1**. These
+> requirements apply to your app only if you install that library; `react-native-md-document`
+> does not require them.
 
 ```tsx
 import { FoldProvider, useFold } from '@acertijosapps/react-native-fold';
@@ -429,115 +457,112 @@ export default function App() {
 }
 ```
 
-Notas:
+Notes:
 
-- `useFold()` devuelve `null` fuera de postura plegada (pantalla exterior, dispositivos sin
-  bisagra o iOS anterior a 27.1); con `?.` y un valor por defecto de `0` el visor se comporta
-  como en una tablet normal.
-- `bounds.width` ya viene en dp: en Android es la línea del pliegue y en iOS incluye los
-  márgenes que reserva el sistema (unos 40 pt en el iPhone Duo).
-- El hueco se centra entre las dos páginas. Funciona cuando el visor ocupa todo el ancho de
-  la ventana; si lo acotas con paneles laterales, la bisagra puede no coincidir con el centro
-  del visor.
-- Si no usas plegables o no instalas `react-native-fold`, no necesitas nada de esto: el modo libro
-  funciona igual en tablets y plegables abiertos.
+- `useFold()` returns `null` outside a folded posture (outer display, devices without a hinge,
+  or iOS older than 27.1); with `?.` and a default of `0` the viewer behaves like on a regular
+  tablet.
+- `bounds.width` is already in dp: on Android it is the fold line, and on iOS it includes the
+  margins the system reserves (about 40 pt on the iPhone Duo).
+- The gap is centered between the two pages. It works when the viewer takes the full window
+  width; if you constrain it with side panels, the hinge may not line up with the viewer's
+  center.
+- If you don't use foldables or don't install `react-native-fold`, you need none of this: book
+  mode works the same on tablets and unfolded foldables.
 
-## Markdown y HTML soportado
+## Supported Markdown and HTML
 
-**Markdown**: encabezados ATX (`#`…`######`), párrafos, listas ordenadas/no-ordenadas
-(anidadas), blockquote, code fence, regla horizontal, tablas GFM, y estilos en línea
-`**negrita**`, `*cursiva*`, `` `código` ``, `~~tachado~~`, `[enlace](url)`.
+**Markdown**: ATX headings (`#`…`######`), paragraphs, ordered/unordered lists (nested),
+blockquotes, code fences, horizontal rules, GFM tables, and the inline styles `**bold**`,
+`*italic*`, `` `code` ``, `~~strikethrough~~`, `[link](url)`.
 
-**HTML embebido**: si el documento empieza con HTML de bloque, se parsea como subconjunto HTML
-(`div`, `p`, `h1..6`, `table`/`tr`/`td`/`col`, `strong`, `em`, `span`, …) honrando el atributo
-`style`: `text-align`, `color`, `background`, `font-size`, `font-weight`, `font-style`,
-`text-transform`, `border-top`, `margin-top`, anchos de `<col>`. Útil para conversiones
-docx→HTML de alta fidelidad. Los colores adaptables usan tokens (ver arriba).
+**Embedded HTML**: if the document starts with block-level HTML, it is parsed as an HTML subset
+(`div`, `p`, `h1..6`, `table`/`tr`/`td`/`col`, `strong`, `em`, `span`, …) honoring the `style`
+attribute: `text-align`, `color`, `background`, `font-size`, `font-weight`, `font-style`,
+`text-transform`, `border-top`, `margin-top`, `<col>` widths. Useful for high-fidelity
+docx→HTML conversions. Adaptive colors use tokens (see above).
 
-**Límites (v1)**: sin imágenes ni enlaces de navegación; un bloque más alto que la página
-scrollea dentro de su hoja; el HTML es un subconjunto (sin `colspan`, imágenes ni CSS externo).
+**Limits (v1)**: no images or navigation links; a block taller than the page scrolls inside
+its sheet; HTML is a subset (no `colspan`, images or external CSS).
 
 ## API
 
-| Export | Tipo | Descripción |
+| Export | Type | Description |
 |---|---|---|
-| `parse(source)` | fn | Markdown/HTML → `MDDocument` (con `plainText`) |
-| `DocumentViewer` | componente | Visor completo: paginación + flip + zoom |
-| `MarkdownView` | componente | Render simple con scroll (sin paginar) |
-| `PaginatedDocument` | componente | Paginación controlada (`pageIndex`) sin flip |
-| `useDocumentSource(source, opts?)` | hook | Carga URL / local / proyecto (`readUri` inyectable) |
+| `parse(source)` | fn | Markdown/HTML → `MDDocument` (with `plainText`) |
+| `DocumentViewer` | component | Full viewer: pagination + flip + zoom |
+| `MarkdownView` | component | Simple scrolling render (no pagination) |
+| `PaginatedDocument` | component | Controlled pagination (`pageIndex`) without flip |
+| `useDocumentSource(source, opts?)` | hook | Loads URL / local / project (`readUri` injectable) |
 | `useHighlights(params)` | hook | `{ highlights, toggleWordAt, add, remove, clear, isLoaded }` |
-| `createKeyValueHighlightStore(kv)` · `createMemoryHighlightStore()` | fn | Stores de subrayado |
+| `createKeyValueHighlightStore(kv)` · `createMemoryHighlightStore()` | fn | Highlight stores |
 | `useTextToSpeech(params)` | hook | `{ status, activeRange, play, pause, resume, stop, index, count }` |
-| `createNativeSpeechEngine()` · `createMockSpeechEngine(opts?)` | fn | Motores de voz |
-| `useDocTheme` · `useColorMode` · `lightTheme` · `darkTheme` · `mergeTheme` · `resolveThemeColor` | tema | Resolución, paletas y tokens |
+| `createNativeSpeechEngine()` · `createMockSpeechEngine(opts?)` | fn | Speech engines |
+| `useDocTheme` · `useColorMode` · `lightTheme` · `darkTheme` · `mergeTheme` · `resolveThemeColor` | theme | Resolution, palettes and tokens |
 
-### Props de `DocumentViewer`
+### `DocumentViewer` props
 
-| Prop | Tipo | Default | Descripción |
+| Prop | Type | Default | Description |
 |---|---|---|---|
-| `document?` | `MDDocument` | — | Documento ya parseado con `parse(...)`. Requerido si no pasas `source` |
-| `source?` | `DocumentSource` | — | Origen a cargar internamente (`{ markdown }` / `{ uri }` / string). El visor gestiona la carga y expone los callbacks/render props de abajo |
-| `readUri?` | `ReadUri` | `fetch` | Lector inyectable para `source` con `uri` (p. ej. `expo-file-system` para `file://`) |
-| `colorScheme?` | `'auto' \| 'light' \| 'dark'` | `'auto'` | Tema; `auto` sigue el SO |
-| `theme?` | `Partial<DocTheme>` | paleta del modo | Override parcial de colores/tamaños |
-| `colorTokens?` | `{ light?: Record<string,string>; dark?: Record<string,string> }` | — | Tokens de marca por modo, para `var(--token)` |
-| `highlights?` | `Highlight[]` | `[]` | Subrayados a pintar (`{ id, start, end, color? }`) |
-| `active?` | `ActiveRange \| null` | `null` | Palabra hablada por el TTS; se resalta y auto-avanza de página |
-| `onWordPress?` | `(offset: number) => void` | — | Tap en una palabra (para subrayar/quitar) |
-| `onPageChange?` | `(pageIndex: number, pageCount: number, pageStartOffset: number, pagesPerView: number) => void` | — | Notifica cambio de página. En modo libro `pageIndex` es la página izquierda y `pagesPerView` vale `2` |
-| `maxScale?` | `number` | `3` | Zoom máximo por pinch |
-| `dualPage?` | `boolean` | `true` | Muestra dos páginas en horizontal cuando el visor es lo bastante ancho. `false` fuerza una sola página |
-| `dualPageMinWidth?` | `number` | `600` | Ancho mínimo (dp) del visor para activar el modo libro |
-| `spreadGap?` | `number` | `0` | Espacio (dp) entre las dos páginas, p. ej. el ancho de la bisagra de un plegable |
-| `onLoadComplete?` | `(document: MDDocument) => void` | — | Se dispara cuando la carga del `source` termina con éxito |
-| `onLoadError?` | `(error: Error) => void` | — | Se dispara cuando la carga del `source` falla |
-| `renderLoading?` | `() => React.ReactNode` | — | Componente a mostrar mientras carga el `source` |
-| `renderError?` | `(error: Error, retry: () => void) => React.ReactNode` | — | Componente a mostrar si la carga falla; `retry` reintenta |
-
-Pasa **`document`** (ya parseado, control total de carga/highlights/TTS) **o** **`source`**
-(el visor carga solo y usa `onLoadComplete` / `onLoadError` / `renderLoading` / `renderError`).
-Los callbacks y render props solo aplican con `source`.
-
-`MarkdownView` y `PaginatedDocument` comparten `theme` / `colorScheme` / `colorTokens` /
-`highlights` / `active` / `onWordPress`; `PaginatedDocument` añade `pageIndex` y
+| `document?` | `MDDocument` | — | Document already parsed with `parse(...)`. Required if you don't pass `source` |
+| `source?` | `DocumentSource` | — | Source to load internally (`{ markdown }` / `{ uri }` / string). The viewer manages the loading and exposes the callbacks/render props below |
+| `readUri?` | `ReadUri` | `fetch` | Injectable reader for a `source` with `uri` (e.g. `expo-file-system` for `file://`) |
+| `colorScheme?` | `'auto' \| 'light' \| 'dark'` | `'auto'` | Theme; `auto` follows the OS |
+| `theme?` | `Partial<DocTheme>` | the mode's palette | Partial override of colors/sizes |
+| `colorTokens?` | `{ light?: Record<string,string>; dark?: Record<string,string> }` | — | Brand tokens per mode, for `var(--token)` |
+| `highlights?` | `Highlight[]` | `[]` | Highlights to paint (`{ id, start, end, color? }`) |
+| `active?` | `ActiveRange \| null` | `null` | Word spoken by the TTS; it is highlighted and the page auto-advances |
+| `onWordPress?` | `(offset: number) => void` | — | Tap on a word (to highlight/remove it) |
+| `onPageChange?` | `(pageIndex: number, pageCount: number, pageStartOffset: number, pagesPerView: number) => void` | — | Notifies a page change. In book mode `pageIndex` is the left page and `pagesPerView` is `2` |
+| `maxScale?` | `number` | `3` | Maximum pinch zoom |
+| `dualPage?` | `boolean` | `true` | Shows two pages in landscape when the viewer is wide enough. `false` forces a single page |
+| `dualPageMinWidth?` | `number` | `600` | Minimum viewer width (dp) to turn on book mode |
+| `spreadGap?` | `number` | `0` | Space (dp) between the two pages, e.g. the width of a foldable's hinge |
+| `accessibilityLabels?` | `Partial<ViewerAccessibilityLabels>` | English | Strings spoken by screen readers: `control`, `pages(first, last, total)`, `nextPage`, `previousPage` |
+| `onLoadComplete?` | `(document: MDDocument) => void` | — | Fires when loading the `source` succeeds |
+| `onLoadError?` | `(error: Error) => void` | — | Fires when loading the `source` fails |
+| `renderLoading?` | `() => React.ReactNode` | — | Component to show while the `source` loads |
+| `renderError?` | `(error: Error, retry: () => void) => React.ReactNode` | — | Component to show if loading fails; `retry` tries again |
+
+Pass **`document`** (already parsed, full control over loading/highlights/TTS) **or**
+**`source`** (the viewer loads on its own and uses `onLoadComplete` / `onLoadError` /
+`renderLoading` / `renderError`). The callbacks and render props only apply with `source`.
+
+`MarkdownView` and `PaginatedDocument` share `theme` / `colorScheme` / `colorTokens` /
+`highlights` / `active` / `onWordPress`; `PaginatedDocument` adds `pageIndex` and
 `onPagesChange?(count)`.
 
-## Arquitectura
+## Architecture
 
-La pieza clave es la **proyección** `MDDocument.plainText`: la concatenación de todo el texto
-visible en orden de lectura. Cada token de texto lleva `[start, end)` en ese espacio, con la
-invariante `token.text === plainText.slice(start, end)`. Sobre ella se apoyan el subrayado
-persistente y el resaltado de TTS.
+The key piece is the **projection** `MDDocument.plainText`: the concatenation of all the
+visible text in reading order. Every text token carries `[start, end)` in that space, with the
+invariant `token.text === plainText.slice(start, end)`. Persistent highlights and the TTS
+highlighting are built on it.
 
-Módulos internos: `parser`, `render`, `pagination`, `flip`, `highlights`, `source`, `speech`.
+Internal modules: `parser`, `render`, `pagination`, `flip`, `highlights`, `source`, `speech`.
 
-## Desarrollo
+## Development
 
 ```sh
-# npm
-npm test          # parser, paginación, highlights, source, speech, tema
+npm install
+npm test          # parser, pagination, highlights, source, speech, theme, accessibility
 npm run typecheck
 npm run lint
 npm run format
-
-# yarn
-yarn test
-yarn typecheck
-yarn lint
-yarn format
 ```
 
-El ejemplo ejecutable está en `example/` (Expo): ejercita orígenes, tema claro/oscuro con
-tokens, subrayado persistente y TTS.
+The runnable example is in `example/` (Expo): it exercises sources, light/dark theme with
+tokens, persistent highlights and TTS.
 
 ```sh
 cd example
-yarn install          # o: npm install
-npx pod-install ios   # primera vez / tras cambiar deps nativas
-yarn ios              # o: yarn android  (o: npm run ios / npm run android)
+npm install
+npx pod-install ios   # first time / after changing native deps
+npm run ios           # or: npm run android
 ```
 
-## Licencia
+See [CONTRIBUTING.md](https://github.com/acertijosapps/react-native-md-document/blob/main/CONTRIBUTING.md) for the branching model and the release process.
+
+## License
 
 MIT

From af4675c0c290f69d8aee3442c743c8fe5bd43ac0 Mon Sep 17 00:00:00 2001
From: Bryan <bgoswaldo@gmail.com>
Date: Sun, 1 Nov 2026 19:15:26 -0600
Subject: [PATCH 2/3] docs(changelog): translate to English and add the
 unreleased entries

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md | 63 ++++++++++++++++++++++++++++------------------------
 1 file changed, 34 insertions(+), 29 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a14e95e..790f534 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,64 +1,69 @@
 # Changelog
 
-Todas las notas relevantes de este proyecto se documentan aquí.
-Formato basado en [Keep a Changelog](https://keepachangelog.com/es-ES/); versionado [SemVer](https://semver.org/lang/es/).
+All notable changes to this project are documented in this file.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/).
 
-## [Sin liberar]
+## [Unreleased]
 
-### Añadido
+### Added
 
-- CI en GitHub Actions para cada PR y push a `beta` y `main`: typecheck, lint, formato y tests.
-- Hooks de git (`.githooks/`) que exigen Conventional Commits y bloquean commits directos sobre `main` y `beta`, y guía de contribución con el flujo de ramas.
+- Screen reader support (VoiceOver and TalkBack): an invisible adjustable control announces the current page ("Page 3 of 12", or "Pages 3 and 4 of 12" in book mode) and turns pages with the increment/decrement actions. Headings are exposed with the `header` role.
+- `accessibilityLabels` prop on `DocumentViewer` to override the spoken strings, plus the `ViewerAccessibilityLabels` type and the `DEFAULT_ACCESSIBILITY_LABELS` export.
+- GitHub Actions CI for every PR and push to `beta` and `main`: typecheck, lint, formatting and tests.
+- Git hooks (`.githooks/`) that require Conventional Commits and block direct commits on `main` and `beta`, and a contributing guide with the branching model.
 
-### Cambiado
+### Changed
 
-- El repositorio se mudó de GitLab a GitHub (`acertijosapps/react-native-md-document`): `repository` y `bugs` de `package.json` y `source` del podspec, que ahora usa el tag `vX.Y.Z`.
+- Peer dependency ranges now match what the library supports: `react-native` ≥ 0.76, `react` ≥ 18.3.1, `react-native-reanimated` ≥ 3.16 and < 4, `react-native-gesture-handler` ≥ 2.20 and < 3. Reanimated 4 and Gesture Handler 3 are not supported yet.
+- The repository moved from GitLab to GitHub (`acertijosapps/react-native-md-document`): `repository` and `bugs` in `package.json` and `source` in the podspec, which now uses the `vX.Y.Z` tag.
+- The public documentation (README, changelog, contributing guide) is now in English.
 
-### Corregido
+### Fixed
 
-### Eliminado
+- The pages stacked behind the current one for the flip animation are hidden from the accessibility tree, so screen readers no longer read them.
+- The error thrown when the native speech module is not linked now names the published package (`@acertijosapps/react-native-md-document`) instead of the old `react-native-document`, and is in English.
 
 ## [1.2.0] - 2026-10-25
 
-### Añadido
+### Added
 
-- Modo libro: en tablets y plegables en horizontal, el documento se muestra en dos páginas enfrentadas con volteo de página. Props `dualPage` (activo por defecto), `dualPageMinWidth` y `spreadGap` (separación para la bisagra de un plegable).
-- `onPageChange` recibe un cuarto argumento, `pagesPerView` (1 o 2).
-- Secciones «Modo libro» y «Plegables» en el README, con capturas.
+- Book mode: on tablets and foldables in landscape, the document is shown as two facing pages with page-turning. Props `dualPage` (on by default), `dualPageMinWidth` and `spreadGap` (space for a foldable's hinge).
+- `onPageChange` receives a fourth argument, `pagesPerView` (1 or 2).
+- "Book mode" and "Foldables" sections in the README, with screenshots.
 
-### Corregido
+### Fixed
 
-- Paginación en tablets: ya no queda atascada ni deja páginas en blanco por eventos de layout tardíos.
-- El modo libro solo se activa en pantallas de tablet o plegable (lado corto de la ventana de al menos 600 dp); un teléfono en horizontal sigue mostrando una página.
+- Pagination on tablets: it no longer gets stuck or leaves blank pages because of late layout events.
+- Book mode only turns on for tablet- or foldable-sized screens (window short side of at least 600 dp); a phone in landscape still shows a single page.
 
 ## [1.1.2] - 2026-10-13
 
-### Cambiado
+### Changed
 
-- `author`, correo y `homepage` de AcertijosApps en `package.json` y el podspec.
+- `author`, email and `homepage` of AcertijosApps in `package.json` and the podspec.
 
 ## [1.1.1] - 2026-09-19
 
-### Añadido
+### Added
 
-- `homepage`, `repository` y `bugs` en `package.json`, y podspec alineado.
+- `homepage`, `repository` and `bugs` in `package.json`, and an aligned podspec.
 
 ## [1.1.0] - 2026-09-19
 
-### Añadido
+### Added
 
-- Carga del documento por `source` con estados de carga y error (`onLoad*`, `renderLoading`, `renderError`).
+- Loading the document through `source`, with loading and error states (`onLoad*`, `renderLoading`, `renderError`).
 
 ## [1.0.1] - 2026-09-19
 
-### Cambiado
+### Changed
 
-- README con el nombre del paquete publicado y las imágenes por URL absoluta, para que rendericen en npm; `media/` se incluye en el paquete.
-- Podspec renombrado a `react-native-md-document.podspec`.
-- Keywords `android`, `ios` y `zoom`.
+- README with the published package name and absolute image URLs, so they render on npm; `media/` is included in the package.
+- Podspec renamed to `react-native-md-document.podspec`.
+- Keywords `android`, `ios` and `zoom`.
 
 ## [1.0.0] - 2026-09-19
 
-### Añadido
+### Added
 
-- Primera versión pública: visor de Markdown como PDF con volteo de página, zoom, resaltados persistentes, lectura en voz alta (TTS) y tokens de color claro/oscuro, con almacenamiento, fuente y voz inyectables.
+- First public release: Markdown-as-PDF viewer with page-turning, zoom, persistent highlights, text-to-speech (TTS) and light/dark color tokens, with injectable storage, source and speech engine.

From 7ba41515f6fd6c98f53f331c91a66e1fb01e498d Mon Sep 17 00:00:00 2001
From: Bryan <bgoswaldo@gmail.com>
Date: Sun, 1 Nov 2026 19:15:26 -0600
Subject: [PATCH 3/3] docs: translate the contributing guide and git hooks to
 English

Commit messages and PRs are written in English from now on.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 .githooks/README.md  | 26 +++++++-------
 .githooks/commit-msg | 48 ++++++++++++-------------
 .githooks/pre-commit | 28 +++++++--------
 CONTRIBUTING.md      | 86 ++++++++++++++++++++++----------------------
 4 files changed, 94 insertions(+), 94 deletions(-)

diff --git a/.githooks/README.md b/.githooks/README.md
index ad26b93..88e577b 100644
--- a/.githooks/README.md
+++ b/.githooks/README.md
@@ -1,28 +1,28 @@
-# .githooks — enforcement de versionado (Atenea)
+# .githooks — versioning enforcement
 
-Hooks git-native (POSIX, sin dependencias). Corren para **cualquier** commit, hecho por una
-persona o por un agente. Alinean el manual de versionado del equipo.
+Git-native hooks (POSIX, no dependencies). They run for **every** commit, whether made by a
+person or by an agent, and enforce the team's versioning rules.
 
-- **`commit-msg`** — bloquea el commit si el mensaje no sigue Conventional Commits
-  (`<tipo>(<alcance>)(!): descripción`). Avisa (no bloquea) si el tipo no cuadra con el prefijo
-  de la rama.
-- **`pre-commit`** — bloquea commits directos sobre `main` o `beta` (el desarrollo va en ramas
-  temporales). Escape para promoción de release: `ATENEA_ALLOW_PROTECTED=1 git commit ...`.
+- **`commit-msg`** — rejects the commit if the message is not a Conventional Commit
+  (`<type>(<scope>)(!): description`). Warns (does not block) when the type does not match the
+  branch prefix.
+- **`pre-commit`** — blocks direct commits on `main` or `beta` (development happens on
+  temporary branches). Escape for release promotion: `ATENEA_ALLOW_PROTECTED=1 git commit ...`.
 
-## Activación
+## Activation
 
-`core.hooksPath` es config local por clon (no se versiona), así que cada clon la activa una vez.
-El proyecto lo automatiza con un script `prepare` en `package.json`:
+`core.hooksPath` is a per-clone local setting (it is not versioned), so each clone enables it
+once. The project automates it with a `prepare` script in `package.json`:
 
 ```json
 "scripts": { "prepare": "git config core.hooksPath .githooks || true" }
 ```
 
-Así, en cada `yarn install` queda cableado. Manual, si hiciera falta:
+That way every `npm install` wires it up. Manually, if needed:
 
 ```bash
 git config core.hooksPath .githooks
 chmod +x .githooks/*
 ```
 
-Bypass puntual de un hook (no recomendado): `git commit --no-verify`.
+One-off bypass of a hook (not recommended): `git commit --no-verify`.
diff --git a/.githooks/commit-msg b/.githooks/commit-msg
index 7c28129..f72837a 100755
--- a/.githooks/commit-msg
+++ b/.githooks/commit-msg
@@ -1,21 +1,21 @@
 #!/bin/sh
 # ─────────────────────────────────────────────────────────────────────────
-# Atenea · commit-msg · valida Conventional Commits (manual de versionado Venteks)
+# Atenea · commit-msg · validates Conventional Commits (Venteks versioning manual)
 #
-# Git-native: corre para CUALQUIER commit (humano o agente), esté o no Claude.
-# Bloquea el commit si el mensaje no cumple. Escape puntual: git commit --no-verify.
+# Git-native: runs for ANY commit (human or agent), with or without Claude.
+# Blocks the commit if the message does not comply. One-off escape: git commit --no-verify.
 #
-# Formato exigido:  <tipo>(<alcance opcional>)(!): <descripción en imperativo>
-#   tipos: feat fix docs style refactor perf test build ci chore revert
-#   ejemplos:  feat(auth): agregar login por sesión
-#              fix: corregir cálculo de permisos
-#              feat(store)!: cambiar shape del estado (BREAKING CHANGE)
+# Required format:  <type>(<optional scope>)(!): <imperative description>
+#   types: feat fix docs style refactor perf test build ci chore revert
+#   examples:  feat(auth): add session login
+#              fix: correct permission calculation
+#              feat(store)!: change the state shape (BREAKING CHANGE)
 # ─────────────────────────────────────────────────────────────────────────
 
 msg_file="$1"
 first_line="$(head -n 1 "$msg_file")"
 
-# Saltar commits de merge/revert automáticos y fixup/squash.
+# Skip automatic merge/revert commits and fixup/squash.
 case "$first_line" in
   "Merge "*|"Revert "*|"fixup!"*|"squash!"*) exit 0 ;;
 esac
@@ -23,31 +23,31 @@ esac
 pattern='^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\([a-z0-9._/-]+\))?(!)?: .+'
 
 if printf '%s' "$first_line" | grep -Eq "$pattern"; then
-  # Aviso suave: coherencia tipo ↔ prefijo de rama (no bloquea).
-  # Una rama feat/* es un contenedor de feature: acumula fix/docs/refactor/chore/
-  # test intermedios de forma legítima, así que NO se avisa sobre ella. Solo se
-  # revisan fix/* y hotfix/*, que son de propósito único.
+  # Soft warning: type ↔ branch prefix consistency (does not block).
+  # A feat/* branch is a feature container: it legitimately accumulates intermediate
+  # fix/docs/refactor/chore/test commits, so it is NOT warned about. Only fix/* and
+  # hotfix/* are checked, since they have a single purpose.
   branch="$(git symbolic-ref --short HEAD 2>/dev/null || echo '')"
   type="$(printf '%s' "$first_line" | sed -E 's/^([a-z]+).*/\1/')"
   case "$branch" in
-    fix/*)     [ "$type" = "fix" ]  || printf '⚠️  Atenea: rama fix/* pero commit "%s" (¿debería ser fix?)\n' "$type" >&2 ;;
-    hotfix/*)  [ "$type" = "fix" ]  || printf '⚠️  Atenea: rama hotfix/* pero commit "%s" (¿debería ser fix?)\n' "$type" >&2 ;;
+    fix/*)     [ "$type" = "fix" ]  || printf '⚠️  Atenea: fix/* branch but commit "%s" (should it be fix?)\n' "$type" >&2 ;;
+    hotfix/*)  [ "$type" = "fix" ]  || printf '⚠️  Atenea: hotfix/* branch but commit "%s" (should it be fix?)\n' "$type" >&2 ;;
   esac
   exit 0
 fi
 
 cat >&2 <<'EOF'
-✕ Atenea · commit rechazado: el mensaje no sigue Conventional Commits.
+✕ Atenea · commit rejected: the message does not follow Conventional Commits.
 
-  Formato:  <tipo>(<alcance>)(!): <descripción en imperativo>
-  Tipos:    feat fix docs style refactor perf test build ci chore revert
+  Format:   <type>(<scope>)(!): <imperative description>
+  Types:    feat fix docs style refactor perf test build ci chore revert
 
-  Ejemplos válidos:
-    feat(auth): agregar login por sesión
-    fix: corregir cálculo de permisos
-    feat(store)!: cambiar shape del estado
+  Valid examples:
+    feat(auth): add session login
+    fix: correct permission calculation
+    feat(store)!: change the state shape
 
-  Manual de versionado del equipo (plugin Atenea, skill git-flow).
-  Bypass puntual (no recomendado):  git commit --no-verify
+  Team versioning manual (Atenea plugin, git-flow skill).
+  One-off bypass (not recommended):  git commit --no-verify
 EOF
 exit 1
diff --git a/.githooks/pre-commit b/.githooks/pre-commit
index b0b0088..a8d1f34 100755
--- a/.githooks/pre-commit
+++ b/.githooks/pre-commit
@@ -1,13 +1,13 @@
 #!/bin/sh
 # ─────────────────────────────────────────────────────────────────────────
-# Atenea · pre-commit · protege ramas permanentes (manual de versionado Venteks)
+# Atenea · pre-commit · protects the permanent branches (Venteks versioning manual)
 #
-# Regla del md: "nunca desarrolles directo sobre main". El desarrollo va en ramas
-# temporales (feat/ fix/ chore/) desde beta; hotfix/ desde main. Este hook
-# bloquea commits DIRECTOS sobre main o beta.
+# Rule: "never develop directly on main". Development happens on temporary branches
+# (feat/ fix/ chore/ docs/) created from beta; hotfix/ from main. This hook blocks
+# DIRECT commits on main or beta.
 #
-# Escape para promoción/merge de release:  ATENEA_ALLOW_PROTECTED=1 git commit ...
-# Bypass total puntual:                     git commit --no-verify
+# Escape for release promotion/merge:  ATENEA_ALLOW_PROTECTED=1 git commit ...
+# One-off full bypass:                  git commit --no-verify
 # ─────────────────────────────────────────────────────────────────────────
 
 [ "${ATENEA_ALLOW_PROTECTED:-}" = "1" ] && exit 0
@@ -17,17 +17,17 @@ branch="$(git symbolic-ref --short HEAD 2>/dev/null || echo '')"
 case "$branch" in
   main|beta)
     cat >&2 <<EOF
-✕ Atenea · commit directo sobre '$branch' bloqueado.
+✕ Atenea · direct commit on '$branch' blocked.
 
-  El desarrollo va en ramas temporales:
-    feat/<func> · fix/<bug> · chore/<ajuste>   (desde beta)
-    hotfix/<bug>                                  (desde main)
+  Development happens on temporary branches:
+    feat/<feature> · fix/<bug> · chore/<task> · docs/<topic>   (from beta)
+    hotfix/<bug>                                                (from main)
 
-  Crea la rama y muévete a ella:
-    git switch -c feat/mi-cambio
+  Create the branch and switch to it:
+    git switch -c feat/my-change
 
-  Promoción de release (merge a $branch):  ATENEA_ALLOW_PROTECTED=1 git commit ...
-  Bypass puntual (no recomendado):         git commit --no-verify
+  Release promotion (merge into $branch):  ATENEA_ALLOW_PROTECTED=1 git commit ...
+  One-off bypass (not recommended):        git commit --no-verify
 EOF
     exit 1
     ;;
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c14c35f..9494f58 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,82 +1,82 @@
-# Contribuir
+# Contributing
 
-Las contribuciones son bienvenidas. Mantén los cambios pequeños, enfocados y trazables.
+Contributions are welcome. Keep changes small, focused and traceable.
 
-## Flujo de desarrollo
+## Development workflow
 
-Usa la versión de Node de [`.nvmrc`](./.nvmrc) e instala las dependencias desde la raíz:
+Use the Node.js version in [`.nvmrc`](./.nvmrc) and install the dependencies from the root:
 
 ```sh
 npm install
 ```
 
-`npm install` también cablea los hooks de git del repositorio (`core.hooksPath` → `.githooks/`).
+`npm install` also wires the repository git hooks (`core.hooksPath` → `.githooks/`).
 
-El proyecto de ejemplo vive en `example/` (Expo) y consume el código de `src/` directamente, así que los cambios en TypeScript se ven con recarga en caliente.
+The example app lives in `example/` (Expo) and consumes the code in `src/` directly, so TypeScript changes hot-reload there.
 
-### Comandos
+### Commands
 
 ```sh
-npm run typecheck     # tipos con TypeScript
-npm run lint          # ESLint
-npm run format        # Prettier (escribe)
-npm run format:check  # Prettier (solo verifica)
-npm test              # pruebas unitarias (node:test)
+npm run typecheck     # type-check with TypeScript
+npm run lint          # lint with ESLint
+npm run format        # format with Prettier (writes)
+npm run format:check  # check formatting with Prettier
+npm test              # run the unit tests (node:test)
 ```
 
-## Modelo de ramas
+## Branching model
 
-Dos ramas permanentes, ambas protegidas:
+Two permanent branches, both protected:
 
-- **`main`**: producción. Sin pushes directos; los cambios entran solo con un Pull Request aprobado.
-- **`beta`**: candidata a release.
+- **`main`**: production. No direct pushes; changes land only through an approved Pull Request.
+- **`beta`**: release candidate.
 
-Ramas temporales, siempre creadas desde `beta`, en kebab-case:
+Temporary branches, always created from `beta`, in kebab-case:
 
-- `feat/<nombre>` · `fix/<nombre>` · `chore/<nombre>` → Pull Request **a `beta`**, se borran al hacer merge.
-- `hotfix/<nombre>` es la única excepción: sale de `main`, va por PR a `main` y luego se integra de vuelta en `beta`.
+- `feat/<name>` · `fix/<name>` · `chore/<name>` · `docs/<name>` → Pull Request **into `beta`**, deleted after merge.
+- `hotfix/<name>` is the only exception: created from `main`, PR into `main`, then back-merged into `beta`.
 
-Una rama = un cambio enfocado.
+One branch = one focused change.
 
 ## Commits
 
-[Conventional Commits](https://www.conventionalcommits.org/es/):
+Write commit messages and Pull Requests in English, following [Conventional Commits](https://www.conventionalcommits.org/):
 
 ```
-<tipo>(<alcance opcional>)(!): <descripción en imperativo>
+<type>(<optional scope>)(!): <imperative description>
 ```
 
-Tipos: `feat` `fix` `docs` `style` `refactor` `perf` `test` `build` `ci` `chore` `revert`.
+Types: `feat` `fix` `docs` `style` `refactor` `perf` `test` `build` `ci` `chore` `revert`.
 
-Correspondencia con [SemVer](https://semver.org/lang/es/): `feat` → MINOR, `fix` → PATCH, cambio incompatible (`feat!` o `BREAKING CHANGE:`) → MAJOR.
+[SemVer](https://semver.org/) mapping: `feat` → MINOR, `fix` → PATCH, breaking (`feat!` or `BREAKING CHANGE:`) → MAJOR.
 
-Los hooks de [`.githooks/`](./.githooks) corren en cada commit:
+The git hooks in [`.githooks/`](./.githooks) run for every commit:
 
-- `commit-msg` rechaza mensajes que no sean Conventional Commits.
-- `pre-commit` bloquea commits directos sobre `main` y `beta`.
+- `commit-msg` rejects messages that are not Conventional Commits.
+- `pre-commit` blocks direct commits on `main` and `beta`.
 
-Bypass puntual (no recomendado): `git commit --no-verify`.
+One-off bypass (not recommended): `git commit --no-verify`.
 
 ## Changelog
 
-Todo cambio que afecte el comportamiento actualiza [`CHANGELOG.md`](./CHANGELOG.md) ([Keep a Changelog](https://keepachangelog.com/es-ES/)): agrega la entrada bajo `## [Sin liberar]` en la categoría correcta (Añadido · Cambiado · Corregido · Eliminado).
+Any change that affects behavior updates [`CHANGELOG.md`](./CHANGELOG.md) ([Keep a Changelog](https://keepachangelog.com/en/1.1.0/)): add the entry under `## [Unreleased]` in the right category (Added · Changed · Fixed · Removed).
 
 ## Pull Requests
 
-Al abrir un PR:
+When opening a PR:
 
-- Apunta a `beta` (o a `main` solo en `hotfix`).
-- Mantenlo pequeño y centrado en un cambio.
-- Asigna al menos un revisor; el merge requiere su aprobación.
-- Los gates deben estar en verde: `npm run typecheck`, `npm run lint`, `npm run format:check` y `npm test`. El CI ([`.github/workflows/ci.yml`](./.github/workflows/ci.yml)) los corre en cada PR hacia `beta` o `main`.
-- Incluye la entrada de `CHANGELOG.md`.
+- Target `beta` (or `main` only for `hotfix`).
+- Keep it small and focused on one change.
+- Assign at least one reviewer; merge requires their approval.
+- Gates must be green: `npm run typecheck`, `npm run lint`, `npm run format:check` and `npm test`. CI ([`.github/workflows/ci.yml`](./.github/workflows/ci.yml)) runs them on every PR to `beta` or `main`.
+- Include the `CHANGELOG.md` entry.
 
-## Release (`beta` → `main`)
+## Releasing (`beta` → `main`)
 
-1. Confirma que los gates están en verde en `beta`.
-2. Decide el incremento SemVer según los commits desde el último tag.
-3. Actualiza `version` en `package.json`.
-4. Renombra la sección `## [Sin liberar]` del changelog a `## [X.Y.Z] - AAAA-MM-DD` y abre una nueva vacía.
-5. Abre el PR `beta` → `main` y haz merge.
-6. Crea el tag `vX.Y.Z` sobre `main` y súbelo (`git push origin vX.Y.Z`).
-7. Publica desde la raíz del repo con `npm publish` (el README y el `package.json` quedan congelados por versión).
+1. Confirm the gates are green on `beta`.
+2. Decide the SemVer bump from the commits since the last tag.
+3. Update `version` in `package.json`.
+4. Rename the `## [Unreleased]` section of the changelog to `## [X.Y.Z] - YYYY-MM-DD` and open a fresh empty one.
+5. Open the `beta` → `main` PR and merge it.
+6. Tag `vX.Y.Z` on `main` and push it (`git push origin vX.Y.Z`).
+7. Publish from the repository root with `npm publish` (the README and `package.json` are frozen per version).