Skip to content

Latest commit

 

History

History
484 lines (381 loc) · 16.9 KB

README.es.md

File metadata and controls

484 lines (381 loc) · 16.9 KB

🌐 Se você quer ler a versão em português deste README, clique aqui. If you want to read the English version of this README, click here.

SimplifAI - Extensión Chrome para Accesibilidad Web

Chrome Extension License: Apache 2.0 ISO 24495-1 Prototype

Important

Este proyecto es un prototipo experimental. No es un producto oficial de Google y no tiene ningún mecanismo de soporte. Fue creado para explorar las posibilidades de los modelos Gemini y fomentar ideas de accesibilidad a través de IA generativa. Úselo bajo su propio riesgo.

SimplifAI es una extensión de Chrome que utiliza Inteligencia Artificial (Google Gemini API) para simplificar contenido web, haciendo la información más accesible según los principios de la ISO 24495-1 (Lenguaje Sencillo).

📋 Índice

📚 Fundamentación Teórica

ISO 24495-1: Lenguaje Sencillo

SimplifAI se basa en la ISO 24495-1 (Plain language - Part 1: Governing principles and guidelines), norma internacional que establece principios y directrices para una comunicación clara y accesible.

Principios del Lenguaje Sencillo (ISO 24495-1)

  1. Enfoque en el usuario: Adaptar el lenguaje al público objetivo
  2. Claridad: Usar palabras comunes y frases cortas
  3. Estructura lógica: Organizar información de forma coherente
  4. Diseño accesible: Facilitar la lectura visual
  5. Verificación: Probar con usuarios reales

Implementación en SimplifAI

La extensión aplica estos principios a través de:

  • Reducción de complejidad: Los textos se reducen hasta un 50%
  • Vocabulario simplificado: Sustitución de términos técnicos por sinónimos comunes
  • Estructura clara: Párrafos cortos (2-3 frases) con jerarquía mantenida
  • Explicación de siglas: Los acrónimos se explican entre paréntesis
  • Voz activa: Preferencia por construcciones directas

🎯 Funcionalidades

1. Onboarding Guiado (Wizard)

  • 3 pasos simples: Idioma → Configuración API → Éxito
  • Multilingüe desde el inicio: Pantalla inicial muestra PT/ES/EN simultáneamente
  • Selección de modelo Gemini: Elija entre Gemini 2.5 (gratuito) y Gemini 3.0 (requiere billing)
  • Validación de API key: Prueba automática antes de guardar
  • Redirección automática: Si intenta usar sin configurar, abre el wizard

2. Simplificación de Contenido con IA

  • Análisis semántico profundo usando Google Gemini API
  • Soporte a múltiples modelos: Gemini 2.5 Flash y Gemini 3.0 Flash Preview
  • Reducción de hasta 50% del texto original manteniendo significado
  • Preservación de la jerarquía de títulos y secciones
  • Eliminación automática de contenido secundario y publicidad

3. Generación de Audio (Text-to-Speech)

  • Motor TTS: Gemini 2.5 Flash Preview TTS
  • Calidad: 24 kHz, 16-bit PCM, mono
  • Chunking inteligente: División por párrafos y frases
  • Procesamiento paralelo: Hasta 5 chunks simultáneos
  • Reproducción progresiva: Inicio antes de la conclusión total
  • Retry automático: Tolerancia a fallos de API
  • Controles: Play, pause, stop con barra de progreso

4. Descripción de Imágenes con IA

  • Análisis contextual usando Gemini API
  • Detecta e ignora: iconos, logos, banners, anuncios
  • Lazy loading: Soporte a imágenes con carga diferida
  • Contexto del artículo: Descripciones específicas basadas en el contenido
  • Validación de dimensiones (>50x50px)

5. Diccionario Contextual Integrado

  • Activación: Doble clic o selección + atajo (Alt+D)
  • Prevención de alucinaciones: Validación de siglas y términos técnicos
  • Popup flotante: Posicionado cerca de la selección
  • Multi-idioma: Definiciones en el idioma configurado
  • Contexto: Considera el artículo para términos ambiguos

6. Soporte Multilingüe Avanzado

Idiomas Soportados

  • 🇺🇸 Inglés (EN)
  • 🇧🇷 Portugués (PT)
  • 🇪🇸 Español (ES)

Capacidad de Traducción Automática

SimplifAI puede simplificar en un idioma una página que está en otro:

Ejemplo:

  • Página original: Portugués (noticia de G1)
  • Idioma configurado: Español
  • Resultado: Texto simplificado en español
📄 Original (PT): "O Supremo Tribunal Federal (STF) decidiu..."
📝 Simplificado (ES): "El Tribunal Supremo Federal decidió..."

7. Recursos de Accesibilidad

Atajos de Teclado

Atajo Función
Alt/Cmd + S Simplificar página actual
Alt/Cmd + A Generar/pausar audio (en la página simplificada)

Modo Alto Contraste

  • Activación: Botón en la toolbar de la página simplificada
  • Colores WCAG AAA: Contraste mínimo 7:1
  • Esquema: Texto blanco (#FFFFFF) sobre fondo negro (#000000)
  • Persistencia: Guardado en chrome.storage.sync

Control de Fuente

  • Tamaños: 14px, 16px, 18px, 20px, 22px, 24px
  • Predeterminado: 18px
  • Incremento: ±2px por botón

🏗️ Arquitectura Técnica

Diagrama de Componentes

graph TB
    subgraph "Chrome Extension"
        BG[Background Service Worker]
        CS[Content Script]
        POP[Popup UI]
        
        subgraph "Content Modules"
            META[Metadata Extractor]
            CONT[Content Extractor]
            IMG[Image Processor]
            MD[Markdown Processor]
            OVL[Overlay Manager]
            ORCH[Simplification Orchestrator]
        end
        
        subgraph "Services"
            GEM[Gemini Service]
            AUD[Audio Service]
        end
    end
    
    subgraph "External APIs"
        GEMAPI[Google Gemini API]
        TTS[Gemini TTS API]
    end
    
    CS --> ORCH
    ORCH --> META
    ORCH --> CONT
    ORCH --> IMG
    ORCH --> MD
    ORCH --> OVL
    
    CONT --> GEM
    IMG --> GEM
    AUD --> TTS
    
    GEM --> GEMAPI
    AUD --> GEMAPI
    
    style ORCH fill:#ff6b6b
    style GEM fill:#4ecdc4
    style AUD fill:#95e1d3
    style GEMAPI fill:#f38181
Loading

Flujo de Onboarding (Primera Ejecución)

sequenceDiagram
    participant U as Usuario
    participant BG as Background Script
    participant OB as Onboarding Page
    participant GEM as Gemini Service
    participant ST as Chrome Storage

    Note over BG: Extensión instalada
    BG->>ST: Verifica apiKey
    ST-->>BG: null (no configurado)
    BG->>OB: Abre onboarding.html
    
    Note over OB: Paso 1: Idioma
    OB->>U: Muestra PT/ES/EN
    U->>OB: Selecciona idioma
    OB->>ST: Guarda language
    
    Note over OB: Paso 2: API Key
    OB->>U: Solicita modelo + API key
    U->>OB: Ingresa datos
    OB->>BG: testApiKey(key, model)
    BG->>GEM: validateApiKey(model)
    GEM-->>BG: isValid: true
    BG-->>OB: Validación OK
    OB->>ST: Guarda apiKey + geminiModel
    
    Note over OB: Paso 3: Éxito
    OB->>U: ✅ ¡Listo para usar!
Loading

💾 Instalación y Configuración

Prerrequisitos

Instalación

  1. Clone el repositorio:
git clone https://github.com/su-usuario/SimplifAI.git
cd SimplifAI

  1. Cargue la extensión en Chrome:

    • Acceda a chrome://extensions/
    • Active "Modo de desarrollador" (esquina superior derecha)
    • Haga clic en "Cargar descomprimida"
    • Seleccione la carpeta src/

  2. Configure a través del Wizard de Onboarding:

    • El wizard se abre automáticamente en la primera instalación
    • Paso 1: Elija su idioma (PT/ES/EN)
    • Paso 2: Seleccione el modelo Gemini e ingrese su API Key
    • Paso 3: ¡Listo! Extensión configurada

Nota: Si cierra el wizard antes de configurar e intenta usar la extensión, el wizard se reabrirá automáticamente.

📖 Guía de Uso

Simplificar una Página

Método 1: Ícono de la Extensión

  1. Navegue hasta la página deseada
  2. Haga clic en el ícono SimplifAI
  3. Espere el procesamiento (5-30s)

Método 2: Menú Contextual

  1. Haga clic derecho en la página
  2. Seleccione "Simplificar esta página"

Método 3: Atajo de Teclado

  1. Presione Alt/Cmd + S

Generar Audio

  1. Simplifique la página primero
  2. Haga clic en "🔊 Generar Audio"
  3. Espere el procesamiento progresivo
  4. Use los controles:
    • ▶️ Play/Pause
    • ⏹️ Stop
    • Barra de progreso

Usar el Diccionario

Método 1: Doble Clic

  1. Haga doble clic en la palabra

Método 2: Menú Contextual

  1. Seleccione la palabra
  2. Haga clic derecho
  3. "Definir palabra seleccionada"

📁 Estructura del Proyecto

SimplifAI/
├── src/
│   ├── components/              # Componentes principales
│   │   ├── background.js       # Service Worker (476 líneas)
│   │   ├── content.js          # Content Script principal (218 líneas)
│   │   ├── onboarding.html     # Wizard de primera configuración
│   │   ├── onboarding.js       # Lógica del onboarding (330 líneas)
│   │   ├── popup.html          # Interfaz de configuración
│   │   ├── popup.js            # Lógica del popup (311 líneas)
│   │   ├── simplified.html     # Template de la página simplificada
│   │   └── simplified-page.js  # Lógica de la página simplificada (776 líneas)
│   │
│   ├── content/                 # Módulos de procesamiento (2,210 líneas)
│   │   ├── extractors/
│   │   │   ├── metadata-extractor.js    # Extracción de metadatos (207 líneas)
│   │   │   ├── content-extractor.js     # Extracción de contenido (452 líneas)
│   │   │   ├── author-extractor.js      # Extracción de autores (268 líneas)
│   │   │   ├── hero-image-extractor.js  # Imagen principal (304 líneas)
│   │   │   └── image-mapper.js          # Mapeo de imágenes (292 líneas)
│   │   ├── processors/
│   │   │   ├── image-processor.js       # Procesamiento de imágenes (502 líneas)
│   │   │   └── markdown-processor.js    # Conversión Markdown→HTML (116 líneas)
│   │   ├── ui/
│   │   │   └── overlay-manager.js       # Gestor de UI (224 líneas)
│   │   └── orchestrator/
│   │       └── simplification-orchestrator.js  # Coordinador (370 líneas)
│   │
│   ├── services/                # Servicios core
│   │   ├── gemini.js           # Integración Gemini API (608 líneas)
│   │   └── audio.js            # Servicio TTS (700 líneas)
│   │
│   ├── utils/                   # Utilitarios (2,640 líneas)
│   │   ├── translations.js     # Sistema i18n (340 líneas)
│   │   ├── prompts.js          # Prompts LLM (401 líneas)
│   │   ├── keyboard-shortcuts.js  # Gestor de atajos (118 líneas)
│   │   ├── constants.js        # Constantes y selectores (224 líneas)
│   │   ├── error-handler.js    # Manejo de errores (420 líneas)
│   │   ├── logger.js           # Sistema de logs (260 líneas)
│   │   ├── retry.js            # Lógica de retry (432 líneas)
│   │   └── state-manager.js    # Gestión de estado (445 líneas)
│   │
│   ├── lib/                     # Bibliotecas externas
│   │   └── purify.min.js       # DOMPurify (sanitización HTML)
│   │
│   └── manifest.json            # Manifiesto Chrome Extension V3
│
├── README.md                    # Versión en portugués
├── README.en.md                 # Versión en inglés
├── README.es.md                 # Este archivo
└── LICENSE                      # Licencia Apache 2.0

Métricas del Código

Categoría Archivos Líneas
Components 5 2,118
Content Modules 9 2,735
Services 2 1,308
Utilities 8 2,640
Total JavaScript 24 8,801

🛠️ Tecnologías Utilizadas

Frontend

  • JavaScript ES6+: Vanilla JS, sin frameworks
  • HTML5: Semantic markup
  • CSS3: Grid, Flexbox, Custom Properties
  • Web APIs:
    • Web Audio API (reproducción de audio)
    • Selection API (diccionario)
    • Fetch API (solicitudes)

Chrome APIs (Manifest V3)

  • chrome.storage.sync: Persistencia de configuraciones
  • chrome.runtime: Comunicación entre componentes
  • chrome.scripting: Inyección de scripts
  • chrome.contextMenus: Menú contextual
  • chrome.tabs: Gestión de pestañas

APIs Externas

  • Google Gemini API (modelos configurables por el usuario):
    • gemini-2.5-flash: Simplificación de texto y visión (Free tier disponible)
    • gemini-3-flash-preview: Modelo más reciente (requiere billing account)
    • gemini-2.5-flash-preview-tts: Text-to-Speech (audio)
  • Formatos: JSON, Base64, WAV (24 kHz PCM)

Bibliotecas

  • DOMPurify 3.0+: Sanitización de HTML (prevenir XSS)
  • Readability.js: Extracción de contenido principal (basado en Mozilla Readability)

⚠️ Limitaciones Conocidas

Limitaciones Técnicas

  1. Páginas Restringidas: No funciona en:

    • chrome:// (páginas internas de Chrome)
    • chrome-extension:// (otras extensiones)
    • file:// (archivos locales sin permiso)

  2. APIs Externas:

    • Requiere conexión a internet
    • Sujeto a límites de tasa de Gemini API
    • Gemini TTS puede retornar error 500 intermitente (retry automático)

  3. Extracción de Contenido:

    • Algunos sitios bloquean content scripts
    • SPAs (React, Vue) pueden tener contenido dinámico no capturado
    • Los paywalls no se evitan

Limitaciones de Calidad

  1. Simplificación:

    • Textos muy técnicos pueden perder matices
    • Siglas desconocidas pueden ser preservadas
    • Tablas complejas pueden ser simplificadas en exceso

  2. TTS:

    • Pausas y entonación pueden no ser naturales
    • Nombres propios pueden ser pronunciados incorrectamente
    • Un único idioma de voz (Kore) para todos los idiomas

  3. Imágenes:

    • Imágenes decorativas pueden ser incluidas
    • El contexto puede no ser suficiente para descripciones precisas
    • Imágenes en SVG no son procesadas

Privacidad

  • Datos enviados a Gemini API:
    • Texto completo de la página
    • Imágenes (como Base64)
    • Palabras seleccionadas (diccionario)
  • No recolectamos: Ningún dato de uso, historial o analítica

🤝 Contribuyendo

¡Las contribuciones son bienvenidas! Siga estas directrices:

Proceso

  1. Fork el repositorio
  2. Cree una branch de feature (git checkout -b feature/MiNuevaFuncionalidad)
  3. Commit sus cambios (git commit -am 'Añade nueva funcionalidad X')
  4. Push a la branch (git push origin feature/MiNuevaFuncionalidad)
  5. Abra un Pull Request

Estándares de Código

  • Idioma: Código y comentarios en inglés
  • JSDoc: Documente funciones complejas
  • Linting: Ejecute node -c en archivos modificados
  • Commits: Mensajes descriptivos en portugués, español o inglés

📄 Licencia

Este proyecto está licenciado bajo la Apache License 2.0.

Copyright 2026 SimplifAI Contributors

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

🙏 Agradecimientos

  • Google Gemini por la API poderosa y accesible
  • Comunidad de Lenguaje Sencillo por los estándares ISO 24495-1
  • Desarrolladores de Accesibilidad Web por las mejores prácticas WCAG
  • Todos los contribuidores que hacen posible este proyecto

Desarrollado con ♿ para una web más accesible

Star on GitHub