PIACERE · Tu espacio personal para aprender italiano

Aplicación web para aprender italiano desde el español, empezando por el nivel A1 del MCER: ruta estructurada, vocabulario con repetición espaciada, gramática consultable, comprensión lectora y oral, escritura con corrección, conversación guiada, pronunciación y cultura italiana.

Funciona sin ninguna API de pago. La IA (Anthropic) es opcional y solo amplía la corrección de textos y la conversación libre.

---

Puesta en marcha

Requisitos: Node.js 20 o superior.

npm install
npm run dev          # http://localhost:3000

Producción:

npm run build
npm start

Scripts

Script	Qué hace
npm run dev	Servidor de desarrollo
npm run build / npm start	Build y servidor de producción
npm test	Tests unitarios y de contenido (Vitest)
npm run typecheck	Genera los tipos de rutas y comprueba TypeScript
npm run lint	ESLint (reglas de Next y de React)
npm run check	typecheck + lint + test
npm run e2e	Prueba end-to-end en navegador real (Playwright). Requiere la app en marcha; BASE_URL permite apuntar a otro servidor

Configuración opcional (.env.local)

Copia .env.example como .env.local.

• ANTHROPIC_API_KEY: activa la corrección de textos con IA y la conversación libre. La clave solo se usa en el servidor (rutas /api/ai/*), nunca llega al navegador. Es un servicio de pago por uso. Además de configurarla, cada usuario tiene que dar su consentimiento en Ajustes → Privacidad, porque sus textos se envían al servicio.
• ANTHROPIC_MODEL: modelo a usar (por defecto claude-opus-5-5).

Sin clave, la app lo indica y usa la corrección por reglas y la conversación guiada.

---

Qué incluye

Fase 1 · Base funcional ✅

• Inicio que responde a «¿qué hago hoy?»: recomendación principal con su motivo, plan del día, nivel estimado, unidad actual, racha, objetivo diario, palabras pendientes, fortalezas y puntos débiles, actividad reciente, logros y un descubrimiento cultural. Sin datos ficticios: si no hay actividad, se muestra un estado vacío.
• Evaluación inicial adaptativa (≈ 9-16 preguntas, unos 5 minutos): vocabulario que reconoces y que produces, comprensión de frases y de un texto, gramática (avanza o retrocede según aciertes) y audio si hay voz italiana. Genera un perfil por destreza, un punto de partida y sugiere unidades que podrías saltar tras una prueba de producción.
• Ruta A1: 3 módulos y 12 unidades (Roma → Palermo), cada una con 6 lecciones: palabras nuevas → gramática → práctica → comprensión + producción → repaso (con reciclaje de unidades anteriores) → evaluación (70 % para superar). Además: prueba de salto (80 %, solo producción) y comprobación de retención a partir de 7 días.
• Vocabulario: ~195 entradas con artículo, género, plural, sílaba tónica, ejemplo, uso, cognados y falsos amigos. Repaso espaciado (SM-2 adaptado) con dos tarjetas por palabra: reconocer y producir. Biblioteca con filtros, palabras difíciles, registro de palabras que ya produces y 9 modos de práctica (flashcards en ambos sentidos, elegir, relacionar, completar, escribir, artículo, plural, dictado).
• Contenido: 442 ejercicios redactados a mano (más los generados a partir del vocabulario), 196 palabras y expresiones, 12 unidades.
• Gramática: 17 fichas con las 10 secciones (qué expresa, cuándo, cómo se forma, tablas, ejemplos, comparación con el español, errores típicos de hispanohablantes, excepciones, práctica y resumen).
• Corrección automática determinista y explicada (ver abajo).
• Progreso: perfil por destreza, «visto no es aprendido», vocabulario por nivel de dominio, temas practicados, errores recurrentes con ejemplos, resumen semanal, historial de sesiones, escritura y logros.
• Persistencia en el navegador, con validación, migraciones, exportación e importación de copias de seguridad.

Fase 2 · Comprensión y producción ✅

• Comprensión lectora: 6 textos graduados (chat, anuncio, correo, relato, noticia adaptada, postal) con pregunta previa, preguntas globales, de detalle e inferencia, pistas de vocabulario, traducción opcional y actividad posterior.
• Comprensión oral: 6 audios con síntesis de voz a 3 velocidades. Primero se escucha sin transcripción; la transcripción y la traducción solo aparecen después de responder. Incluye dictados y huecos.
• Escritura: frases a partir de pistas y 16 tareas (describir, mensajes, diario, experiencias, opinión). Corrección con texto original, versión corregida, errores clasificados (error / poco natural / estilo) con explicación en español, versión más natural (con IA), sugerencia y texto modelo. Historial de textos.
• Cultura: 9 piezas (café, expresiones coloquiales, Pinocchio, «Volare», «La vita è bella», regiones, la mesa, Florencia, Befana), cada una con objetivos lingüísticos, expresiones, ejercicios y fuentes enlazadas.

Fase 3 · Funciones avanzadas (parcial)

• ✅ Conversación guiada sin IA: 6 situaciones (presentarse, bar, direcciones, rutina, gustos, hotel). Respondes con tus palabras; el motor reconoce la intención, extrae datos (tu nombre, lo que pides) y señala calcos del español. Botones de repetir, más despacio, «¿qué significa?» y pistas en dos niveles.
• ✅ Conversación libre con IA (si está configurada y consentida), con salida estructurada y validada: respuesta, traducción, corrección y pista.
• ✅ Pronunciación: 8 temas (dobles, v/b, c/g, gn/gli, sc, z, acento tónico, vocales) con pares mínimos, modelo de audio, grabación local para compararte y comprobación de palabras reconocidas.
• ✅ Reconocimiento de voz del navegador para dictar respuestas (con consentimiento).
• ⏳ Evaluación fonética real: no implementada. Está preparada la interfaz PronunciationAssessor (src/lib/services/pronunciation.ts); ver abajo.
• ⏳ Adaptación de dificultad más sofisticada y niveles A2/B1: la arquitectura los admite; falta el contenido.

---

Cómo corrige

src/lib/grading/ — sin IA, determinista y con tests.

1. Normaliza mayúsculas, puntuación, espacios y apóstrofos tipográficos.
2. Acepta todas las respuestas válidas de cada ejercicio (con o sin pronombre, órdenes alternativos, variantes de registro) y explica las diferencias cuando las hay.
3. Errores previstos: respuestas incorrectas típicas con un comentario específico (sono 30 anni → la edad va con avere).
4. Acentos: una tilde olvidada es un error menor, salvo cuando cambia el significado (e/è, si/sì, da/dà…).
5. Consonantes dobles y erratas (una letra, transposiciones) cuentan como «correcto con un detalle», pero nunca en las terminaciones, porque en italiano marcan género, número y persona (parlo/parla). En ejercicios de forma (conjugar, artículo, plural) no hay tolerancia.
6. Si es incorrecta, busca la respuesta más cercana, muestra la comparación palabra por palabra y detecta interferencias del español (y, muy, porque, el/los, -ción, a il…).

Durante la práctica, lo fallado vuelve al final de la lección, y si un tema falla dos veces se inserta un ejercicio de refuerzo de ese tema.

Repetición espaciada

src/lib/srs/srs.ts. Variante de SM-2: facilidad 1,3-3,0, intervalos crecientes, un fallo devuelve la tarjeta a reaprendizaje en 10 minutos. Las palabras difíciles tienen intervalos más cortos y repetir aciertos el mismo día no infla el intervalo. Una palabra se considera dominada solo cuando ambas tarjetas (reconocer y producir) superan los 21 días.

Racha y puntos

Los XP premian el aprendizaje demostrado (superar evaluaciones y comprobaciones de retención da más puntos; repetir contenido ya superado da la mitad). La racha es flexible: un día de descanso por semana no la rompe. El tiempo de estudio es aproximado: solo cuenta con la pestaña visible y actividad en el último minuto.

---

Arquitectura

Next.js 16 (App Router, Cache Components) + React 19 + TypeScript + Tailwind CSS 4. Zod para validación. Vitest y Playwright para pruebas.

src/
  app/                 Rutas (páginas finas que montan componentes)
    api/ai/            Rutas de servidor para la IA (status, evaluate, chat)
  components/          Interfaz (cliente). exercise/ = reproductor de ejercicios
  content/             CONTENIDO EDUCATIVO, separado de la interfaz
    types.ts           Modelo de datos del contenido
    curriculum.ts      Niveles → módulos → unidades
    units/             Unidad = vocabulario + lecciones + notas para hispanohablantes
    grammar/           Fichas de gramática con sus ejercicios
    comprehension.ts, writing.ts, culture.ts, scenarios.ts, pronunciation.ts, placement.ts
  lib/
    grading/           Corrección, normalización, interferencias, patrones Unicode
    srs/               Repetición espaciada
    learning/          Generadores de ejercicios a partir del vocabulario
    placement/         Evaluación inicial adaptativa
    progress/          Reductores puros (core), métricas (derived), logros, recomendaciones
    conversation/      Motor de conversación guiada
    writing/           Corrección de textos por reglas
    state/             Esquema persistente (zod) y store del cliente
    storage/           Adaptadores de persistencia y repositorio
    services/          Voz (TTS/STT/grabación), cliente de IA, evaluación fonética
    ai/                Servidor de IA: esquemas y llamadas (server-only)
e2e/flows.mjs          Prueba end-to-end de los flujos principales

Principios: la lógica educativa son funciones puras (lib/progress/core.ts) que reciben el estado y devuelven el nuevo; la interfaz solo las despacha. El contenido son datos tipados: añadir una lección no requiere tocar componentes.

Persistencia

El progreso se guarda en localStorage (clave piacere:state) detrás de una interfaz StorageAdapter (src/lib/storage/adapter.ts). Al cargar, el estado se valida con zod y pasa por migraciones versionadas; si los datos están corruptos se guarda una copia aparte y se empieza de cero, avisando. Se guarda con un pequeño retardo y al ocultar la página, y se sincroniza entre pestañas.

Limitación: los datos viven en este navegador. Exporta copias de seguridad desde Ajustes.

Migrar a una base de datos (p. ej. Supabase/PostgreSQL): implementar otro StorageAdapter (load/save/backup/clear/subscribe) que lea y escriba el estado del usuario autenticado, protegido con Row Level Security (user_id = auth.uid()). El resto de la app no cambia. Para escalar, el estado puede normalizarse en tablas (srs_cards, attempts, activities…) siguiendo el esquema de src/lib/state/schema.ts.

IA

src/lib/ai/server.ts (solo servidor). Usa @anthropic-ai/sdk con salida estructurada (messages.parse + esquemas zod) y vuelve a validar la respuesta: nunca se decide nada a partir de texto libre del modelo. Tiene manejo de errores tipados (clave inválida, límite de uso, conexión), detección de respuestas incompletas o declinadas y respaldo del servidor (fallbacks: "default"). Los ejercicios cerrados nunca dependen de la IA.

Voz

• Texto a voz: Web Speech API del navegador (gratis). La calidad depende de las voces instaladas; si no hay voz italiana se avisa. Adaptador TtsAdapter para sustituirla por un servicio externo.
• Reconocimiento: SpeechRecognition del navegador. En Chrome/Edge el audio se envía al proveedor del navegador, por eso se pide consentimiento en Ajustes. Solo indica qué palabras se han reconocido: no evalúa sonidos.
• Grabación: MediaRecorder, el audio no sale del dispositivo.
• Evaluación fonética (pendiente): implementar PronunciationAssessor en una ruta de servidor con un servicio especializado, por ejemplo Azure AI Speech – Pronunciation Assessment (admite it-IT). Necesita AZURE_SPEECH_KEY y AZURE_SPEECH_REGION; se factura por hora de audio procesado (hay un nivel gratuito limitado; consulta la tarifa vigente).

Derechos de autor

No se reproducen letras de canciones, guiones ni capítulos protegidos. El fragmento de Pinocchio (1883) es de dominio público. Los recursos externos (YouTube, RaiPlay Sound, Wikipedia, Wikisource…) se enlazan, no se descargan, y cada actividad funciona aunque el enlace deje de estar disponible.

---

Añadir contenido

• Una unidad: crea src/content/units/uNN-nombre.ts con vocabKit() y kit() (ver las existentes), y añádela a un módulo en src/content/curriculum.ts.
• Un nivel (A2): añade sus módulos en LEVELS y marca available: true.
• Una ficha de gramática: añádela en src/content/grammar/ y en GRAMMAR.
• Lecturas, audios, cultura, escritura, conversación: añade objetos en el archivo correspondiente de src/content/.

Los tests de contenido (src/content/__tests__/content.test.ts) comprueban automáticamente: ids únicos, referencias válidas, que cada respuesta aceptada se corrige como correcta, que ningún error previsto coincide con una respuesta válida, que las fichas de ordenar pueden formar todas las respuestas, que los textos modelo cumplen sus propios requisitos y que cada ejemplo de conversación es reconocido por el motor.

Pruebas

• npm test: 81 tests (corrección, SRS, progreso, racha, evaluación inicial, generadores, persistencia, conversación y validación de todo el contenido).
• npm run e2e: recorre en Chromium la evaluación, lecciones con todos los tipos de ejercicio, persistencia tras recargar, repaso, lectura, escucha, escritura, conversación, cultura, pronunciación, navegación móvil (sin desbordamiento horizontal) y comprueba que no hay errores de consola.

Próximos pasos sugeridos

1. Contenido A2 (passato prossimo, imperfetto, pronombres de objeto, comparativos).
2. Audio grabado por hablantes nativos para las actividades de escucha.
3. Sincronización entre dispositivos (adaptador Supabase + autenticación).
4. Evaluación fonética con un servicio especializado.
5. Ajuste de la dificultad de los ejercicios según el historial de cada tema.