Vokabeltrainer

Überblick

Der Vokabeltrainer stellt japanische Wörter nicht isoliert dar. Zu jedem Eintrag gehören eine Hiragana-Lesung, eine Erklärung und drei Beispielsätze. Schwierige Begriffe aus diesen Texten können zusätzlich über Glossareinträge erklärt und mit den jeweiligen Fundstellen verknüpft werden.

Backend

Python 3.14, Flask, Psycopg

Datenbank

PostgreSQL

Cache und API-Drosselung

Redis in der Produktionskonfiguration

Frontend

Jinja-Templates, JavaScript ohne Framework, CSS

Sprachen der Oberfläche

Deutsch, Englisch, Japanisch über Flask-Babel

Zugang

Öffentliche Leseansicht ohne Anmeldung

Die Oberfläche ist auf Lesen, Entdecken und Nachschlagen ausgelegt. Es gibt derzeit weder Vokabeltests mit Punktebewertung noch Spaced Repetition oder dauerhaft gespeicherte Lernstände.

Lernen und Nachschlagen

Der Trainer besitzt zwei Ansichten, zwischen denen gewechselt werden kann.

Zufälliger Wortschatz

Im Zufallsmodus erscheinen Karten mit japanischen Wörtern. Die Hiragana-Lesung ist zunächst verdeckt und kann einzeln aufgedeckt werden. Erklärungen, Beispielsätze und ergänzende Glossarwörter lassen sich bei Bedarf aufklappen.

Weitere Wörter werden in Stapeln geladen. Der Browser versucht, unmittelbare Wiederholungen zu vermeiden; eine vollständig wiederholungsfreie Auswahl ist weder garantiert noch vorgesehen.

Gezieltes Nachschlagen

Im Nachschlagemodus lassen sich Vokabeln über einen Suchbegriff, die Wortschatzquelle und ein Set eingrenzen. Ergebnisse werden schrittweise nachgeladen, anstatt den gesamten Bestand auf einmal zu übertragen.

Die beiden Ansichten verwalten ihre eigenen Filter, geladenen Karten und Scrollpositionen. Beim Wechsel bleibt der jeweilige Zustand während des aktuellen Seitenbesuchs erhalten. Nach dem Neuladen der Seite beginnt die Ansicht erneut.

Wortschatz und Glossar

Der dokumentierte Importbestand umfasst:

Vokabelsets

64

Vokabeln insgesamt

3.110

Davon Hauptvokabeln

2.647

Davon Glossarvokabeln

463

Beispielsätze

9.330

Setmitgliedschaften

3.110

Feldgenaue Glossarverweise

3.430

Die Hauptvokabeln bilden den eigentlichen Lern- und Nachschlagebestand. Das Glossar ergänzt Begriffe, die zum Verständnis der japanischen Erklärungen und Beispielsätze benötigt werden.

Durch die Hilfwörter aus dem Glossar kann ein einfach formulierter japanischer Erklärungstext zusätzliche sprachliche Hilfe anbieten, ohne für jedes Wort eine deutsche Übersetzung vorauszusetzen.

Technische Architektur

Die Anwendung verwendet serverseitig erzeugtes HTML und eine eigenständige JavaScript-Oberfläche. Die eigentlichen Vokabeldaten liegen in PostgreSQL. Der Zugriff erfolgt über ein Repository, das die Datenbankverbindungen des gemeinsamen Psycopg-Pools nutzt.

Beim Aufruf der Trainerseite wird ein vorbereiteter Datenausschnitt in das HTML eingebettet. Dadurch kann die Oberfläche sofort mit Karten starten, ohne zunächst eine eigene API-Abfrage abwarten zu müssen – sofern der Cache verfügbar ist. Spätere Suchanfragen, Detailabrufe und nachgeladene Ergebnisse werden über die JSON-API bezogen.

Datenmodell und Import

Die Datenbank trennt Wortschatz, Sets, Beispielsätze und Glossarbeziehungen. Eine Vokabel kann mehreren Sets zugeordnet sein, ohne dafür mehrfach gespeichert zu werden.

Sets

Gruppieren Vokabeln und enthalten Metadaten zu Besitzer und Sichtbarkeit

Vokabeln

Speichern Wort, Hiragana, Erklärung, Suchschreibweise und Quelle

Setmitgliedschaften

Verbinden Sets und Vokabeln über eine eigene Zuordnungstabelle

Beispielsätze

Ordnen einer Vokabel bis zu drei nummerierte Positionen zu; beim Import sind genau drei erforderlich

Glossarverweise

Verbinden Hauptvokabeln und Hilfswörter einschließlich ihrer Fundstelle

Die Einträge verwenden UUIDs als Datenbankidentitäten; beim Import neu erzeugte IDs basieren auf UUIDv7. Ursprüngliche Kennungen aus den Quelldateien dienen separat dazu, Einträge bei wiederholten Importen wiederzuerkennen.

Vor dem Befüllen der Datenbank werden die JSON-Dateien auf ihre Struktur, Pflichtfelder, eindeutigen Kennungen, drei unterschiedliche Beispiele und gültige Glossarverknüpfungen geprüft. Der Import kann neue Einträge und Beziehungen ergänzen, ist aber kein Migrations- oder vollständiges Synchronisationssystem: Bereits gespeicherte Texte werden bei einer erneuten Initialisierung nicht automatisch aktualisiert und entfernte Quellen nicht automatisch gelöscht.

Das Schema enthält bereits Besitzer- und Sichtbarkeitsfelder für Sets und Vokabeln. Die heutige API verwendet ausschließlich die öffentliche Lesesicht; das ist noch keine Funktion zum Erstellen eigener Wortlisten.

Suche und HTTP-API

Die öffentliche API stellt die Einträge in mehreren Formen bereit:

GET /api/vocabtrainer

Zufällige Hauptvokabeln

GET /api/vocabtrainer/sets

Öffentliche Sets und deren Umfang

GET /api/vocabtrainer/entries

Suche und gefilterte Ergebnislisten

GET /api/vocabtrainer/entries/<vocab_id>

Einzelner öffentlicher Eintrag

GET /api/vocabtrainer/entries/<vocab_id>/glossary

Zugehörige Glossarwörter

GET /api/vocabtrainer/entries/<vocab_id>/usages

Hauptvokabeln, die ein Glossarwort verwenden

Die Suche arbeitet als literale Präfixsuche über Wort, Hiragana und eine zusätzliche Suchschreibweise. Sie ist derzeit keine Volltextsuche und führt weder automatische Umschrift noch Unicode-Normalisierung durch.

Längere Listen verwenden einen UUID-Cursor (after) statt einer Seitennummer. Eine Antwort enthält die aktuellen items und gegebenenfalls next_after für die nächste Seite. Standardmäßig werden 20 Einträge geladen; das API-Limit liegt bei maximal 100 Einträgen pro Anfrage.

Beispielsätze und Glossarhilfen werden serverseitig in Sammelabfragen ergänzt, damit nicht für jede angezeigte Karte eine separate Datenbankanfrage benötigt wird.

Cache und Performance

Die Startansicht nutzt einen vorbereiteten Snapshot aus 20 zufälligen Hauptvokabeln und 20 Nachschlageeinträgen. Dieser Snapshot liegt je nach Konfiguration im Prozessspeicher oder gemeinsam in Redis.

Snapshot mit 60 Minuten TTL

Schneller Start der Trainerseite ohne synchronen Datenbankabruf für den Preload

Hintergrundprüfung im Abstand von 30 Sekunden

Fehlenden oder abgelaufenen Snapshot neu aufbauen

Redis-Sperre beim Neuaufbau

Gleichzeitige Cache-Neuberechnung durch mehrere Worker begrenzen

Gebündelte Datenbankabfragen

Beispielsätze und Hilfswörter effizient ergänzen

Virtualisierte Kartenliste

Nur den sichtbaren Bereich und einen Puffer im DOM darstellen

Speicherfenster mit Zielgröße 200 Karten je Modus

Browserseitigen Ressourcenverbrauch begrenzen

Ein Nachteil des Snapshot-Modells ist bewusst in Kauf genommen: Fehlt der Cache beim Kaltstart oder nach Ablauf, kann die HTML-Seite vorübergehend mit HTTP 503 antworten. Die Anfrage wartet nicht auf einen synchronen Cacheaufbau. Auch Änderungen am importierten Bestand erscheinen nicht zwingend sofort in bereits gespeicherten Snapshots.

Die Virtualisierung des Scrollbereichs reduziert die Zahl gleichzeitig vorhandener DOM-Elemente. Ältere, bereits aus dem Speicherfenster entfernte Ergebnisse lassen sich durch Zurückscrollen allerdings nicht erneut laden; eine neue Suche setzt die Ergebnisliste zurück.

Sicherheit und Internationalisierung

Die API prüft erlaubte Parameter, bindet Suchwerte in SQL-Abfragen und begrenzt Ergebnisgrößen. Alle Vokabel-API-Endpunkte teilen sich pro Client-IP ein Limit von 60 Anfragen pro Minute und 300 pro Stunde. Fehler werden mit passenden HTTP-Statuscodes behandelt; interne Datenbankfehler gelangen nicht als Detailmeldungen an Besucher.

Die Oberfläche ist in Deutsch, Englisch und Japanisch verfügbar. Die Vokabeleinträge selbst bleiben unabhängig von der gewählten Oberflächensprache auf Japanisch. Für bekannte importierte Sets werden die Anzeigenamen lokalisiert; die gespeicherten Setnamen bleiben unverändert.

Für die Bedienbarkeit berücksichtigt das Frontend unter anderem Tastaturinteraktionen, Statusmeldungen für assistive Technologien und die japanische IME-Eingabe während der Suche.

Grenzen und Weiterentwicklung

Der Vokabeltrainer ist derzeit vor allem ein Wortschatz-Browser mit Lernhilfen, noch kein vollständiges Lernmanagementsystem. Insbesondere sind folgende Funktionen nicht umgesetzt:

• Persönliche Vokabeln und selbst verwaltete Sets über eine Schreib-API.
• Lernfortschritt, Antwortbewertung oder Spaced Repetition.
• Dauerhaft gespeicherte Karten- und Suchzustände.
• Volltextsuche, automatische Umschrift oder alphabetische Ergebnissortierung.

Auf technischer Seite bleiben der aufwendigere Zufallsabruf bei stark wachsendem Datenbestand, die nicht garantiert stabile Seitensicht zwischen Cursoranfragen und das vorübergehende Fehlen eines abgelaufenen Cache-Snapshots bekannte Grenzen.

Die Grundlage ist dennoch erweiterbar: Das relationale Datenmodell erlaubt mehrere Sets pro Vokabel, trennt öffentliche von privaten Inhalten und bildet die Glossarbeziehungen unabhängig von der Oberfläche ab.