Context Crawler: KI-gestützte Website- und Repository-Analyse für better-i18n

Wie better-i18n KI-Kontext aus deinem Produkt aufbaut

Die meisten Lokalisierungs-Workflows beginnen mit einem manuellen Schritt: Jemand taggt Strings, exportiert Dateien und hofft, dass nichts übersehen wurde. better-i18n verfolgt einen anderen Ansatz. Der Context Crawler kombiniert zwei leistungsstarke Analysemodi — Website-Crawling und Repository-Scanning — um automatisch reichhaltigen Kontext aufzubauen, der KI-Übersetzungen deutlich präziser macht.

Das Ergebnis ist ein Workflow, bei dem dein KI-Übersetzer deine Brand, deinen Produkt-Wortschatz und deinen Tech-Stack versteht, bevor er auch nur einen einzigen String übersetzt.

Website-Analyse: Firecrawl-gestützte Brand-Erkennung

Der Website-Analysemodus des Context Crawlers nutzt die Firecrawl API, um systematisch Inhalte von jeder URL zu crawlen und zu extrahieren, die du angibst. Dies ist kein einfaches HTML-Scraping — Firecrawl verarbeitet JavaScript-gerenderte Seiten, SPAs und dynamische Inhalte, um das zu erfassen, was Nutzer tatsächlich sehen.

So funktioniert die Website-Analyse

1. URL angeben — Gib die Marketing-Website deines Produkts, die Dokumentation oder eine beliebige Web-Property ein. Der Crawler akzeptiert jede öffentlich zugängliche URL.
2. Firecrawl-Extraktion — Die Firecrawl API rendert Seiten, folgt internen Links und extrahiert strukturierte Inhalte einschließlich Überschriften, Fließtext, Navigations-Labels, CTAs und Metadaten.
3. Terminologie-Erkennung — KI-Analyse identifiziert wiederkehrende Begriffe, Markensprache, Produktnamen, Feature-Namen und domänenspezifisches Vokabular auf allen gecrawlten Seiten.
4. Kandidaten-Vorschlag — Erkannte Begriffe werden als Glossar-Kandidaten mit vorgeschlagenen Definitionen, Kontext-Notizen und Häufigkeitsdaten vorgeschlagen. Jeder Kandidat enthält die Quell-URLs, wo er gefunden wurde.

Was die Website-Analyse erfasst

• Brand-Terminologie — Produktnamen, Feature-Namen, Pricing-Tier-Labels und geprägte Begriffe, die konsistent auf deiner Website erscheinen
• Navigationsmuster — Menü-Labels, Breadcrumb-Text und CTA-Sprache, die den Wortschatz deines Produkts definieren
• Domain-Vokabular — Branchenspezifische Begriffe, die dein Produkt verwendet und die präzise, konsistente Übersetzung erfordern
• Ton- und Voice-Signale — Ob dein Content formal, casual, technisch oder Marketing-orientiert ist — Kontext, der KI hilft, mit dem passenden Register zu übersetzen

Anwendungsfälle für die Website-Analyse

• Neues Projekt-Setup — Crawle deine Marketing-Website, bevor du mit der Lokalisierung beginnst, um in Minuten statt Wochen ein Glossar und ein Kontext-Profil zu bootstrappen
• Wettbewerbsanalyse — Crawle Competitor-Websites in Zielmärkten, um zu verstehen, wie sie ähnliche Konzepte übersetzen, und informiere so deine eigenen Glossar-Entscheidungen
• Content-Audit — Crawle periodisch neu, um neue Terminologie zu erkennen, die seit deinem letzten Glossar-Update entstanden ist

Repository-Analyse: Framework- und Terminologie-Erkennung

Der Repository-Analysemodus des Context Crawlers verbindet sich mit deinem GitHub-Repository und führt eine tiefgehende Analyse deiner Codebase durch, um übersetzungsrelevanten Kontext zu extrahieren.

So funktioniert die Repository-Analyse

1. GitHub-Repo verbinden — Gib die Repository-URL an. Der Crawler greift auf öffentliche Repos direkt zu, private Repos über deine GitHub-Integration.
2. Framework-Erkennung — Der Analyzer identifiziert deinen Tech-Stack: React, Next.js, Vue, Angular, Svelte, Flutter, React Native und andere. Dies bestimmt, nach welchen i18n-Patterns gesucht und wie dein Code geparst wird.
3. i18n-Pattern-Erkennung — Basierend auf dem erkannten Framework findet der Analyzer bestehende Translation-Function-Calls (t(), useTranslations(), $t(), tr() usw.) und mappt, wie dein Projekt seine Übersetzungen strukturiert.
4. Terminologie-Extraktion — Der Analyzer identifiziert hardcodierte Strings, Komponenten-Namen, Route-Labels und andere nutzerseitige Texte, die deinen Produkt-Wortschatz repräsentieren.
5. Kontext-Profil-Generierung — Alle Erkenntnisse werden in ein Kontext-Profil kompiliert, das erkannte Frameworks, i18n-Library-Nutzung, Namespace-Struktur und Terminologie-Kandidaten enthält.

Was die Repository-Analyse erkennt

• Framework und i18n-Library — Automatische Erkennung deines Stacks, damit KI-Übersetzungen die korrekten Formatierungskonventionen verwenden (ICU MessageFormat, i18next-Interpolation, Flutter ARB usw.)
• Namespace-Struktur — Wie dein Projekt Translation-Keys organisiert, damit neue Übersetzungen dieselben Patterns folgen
• Bestehende Terminologie — Bereits in deiner Codebase verwendete Begriffe, die helfen zu identifizieren, was zum Glossar hinzugefügt werden sollte
• String-Patterns — Häufige Patterns in deinen nutzerseitigen Strings (Datumsformate, Zahlenformate, Pluralisierungsansätze), die Übersetzungsregeln informieren

AST-basierte Key-Erkennung

Jenseits des Kontext-Aufbaus parst der scan-Befehl des CLI deinen Quellcode auf Syntax-Tree-Ebene, nicht mit fehleranfälligem Regex-Matching. Er versteht React JSX, useTranslations und getTranslations-Patterns nativ. Das bedeutet, er kann zwischen einem nutzerseitigen String wie <h1>Welcome back</h1> und einem technischen String wie className="flex items-center" unterscheiden, ohne False Positives.

Was erkannt wird:

• Hardcodierter JSX-Text — Inhalte wie <h1>Hello</h1>, die in t()-Calls eingebettet werden sollten
• Hardcodierte JSX-Attribute — Nutzerseitige Attribute wie <img alt="Company logo" />
• Toast- und Notification-Strings — Calls wie toast.error("Something went wrong")
• Locale-basierte Ternary-Logik — Patterns wie locale === 'en' ? 'Hi' : 'Hola', die manuelles Locale-Handling anzeigen
• String-Variablen — Variablen mit Text, der nutzerseitig erscheint

Was intelligent ignoriert wird:

• Tailwind- und CSS-Klassen-Namen
• URLs, Dateipfade und Bildquellen
• HTML-Entities (&, ")
• Technische Konstanten in SCREAMING_CASE
• Zahlen und nicht-textuelle Werte

better-i18n scan              # Aktuelles Verzeichnis scannen
better-i18n scan --dir ./src  # Bestimmtes Verzeichnis scannen
better-i18n scan --staged     # Nur staged Files (für Pre-Commit-Hooks)
better-i18n scan --ci         # Exit-Code 1 bei gefundenen Problemen
better-i18n scan --format json # JSON-Output für Tooling
better-i18n scan --verbose    # Detaillierter Output mit Scan-Audit

Namespace-Auflösung

Der Scanner nutzt Lexical-Scope-Tracking, um Namespaces automatisch sowohl für Client- als auch für Server-Komponenten aufzulösen. Das ist wichtig, weil erkannte Keys ihren vollständigen Namespace-Pfad enthalten, nicht nur den Key-Namen.

Für Client-Komponenten mit Hooks:

const t = useTranslations('hero');
return <h1>{t('title')}</h1>; // Erkannt als: hero.title

Für Server-Komponenten mit async Functions:

const t = await getTranslations('welcome');
return <h1>{t('title')}</h1>; // Erkannt als: welcome.title

Der Scanner verarbeitet auch die Object-Form (getTranslations({ locale, namespace: 'settings' })) und Root-Scoped-Translatoren ohne Namespace. Dynamische Namespaces mit Variablen oder Template Literals werden im --verbose-Modus gemeldet und von Metriken ausgeschlossen, um False Positives zu vermeiden.

Von der Analyse zum Glossar: Die vollständige Pipeline

Die Website- und Repository-Analysemodi des Context Crawlers fließen direkt in das Glossar-Management-System ein:

1. Crawlen — Website-Analyse via Firecrawl extrahiert Brand-Terminologie; Repo-Analyse erkennt Framework-Kontext und bestehende Begriffe.
2. Vorschlagen — Erkannte Begriffe werden als Glossar-Kandidaten mit Entwurfsstatus vorgeschlagen.
3. Prüfen — Dein Team prüft vorgeschlagene Begriffe, bearbeitet Definitionen und Übersetzungen nach Bedarf.
4. Genehmigen — Genehmigte Begriffe werden sofort in KI-Übersetzung und im Review-Editor durchgesetzt.
5. Synchronisieren — Genehmigte Begriffe können mit DeepL synchronisiert werden für Durchsetzung auf Provider-Ebene.

Diese Pipeline bedeutet, du kannst von „wir haben kein Glossar" zu „unsere KI-Übersetzungen setzen 200 Brand-Begriffe durch" in einem einzigen Nachmittag gelangen.

Sync: Lokales vs. Cloud vergleichen

Der sync-Befehl überbrückt die Lücke zwischen dem, was dein Code verwendet, und dem, was in better-i18n existiert. Er scannt deine Codebase genauso wie scan, fragt dann die better-i18n API ab, um Key-Sets zu vergleichen.

Der Output ist ein übersichtlicher Vergleichsbericht:

• Fehlt in Remote — Keys, die in deinem Code referenziert werden, aber noch nicht zu better-i18n hochgeladen wurden. Das sind Strings, die deine Nutzer möglicherweise unübersetzt sehen.
• Ungenutzt im Code — Keys, die in better-i18n existieren, aber nirgendwo in deinem Quellcode mehr referenziert werden. Das sind Kandidaten für Bereinigung.

better-i18n sync              # Gruppierten Baum-Output
better-i18n sync --summary    # Nur High-Level-Coverage-Metriken
better-i18n sync --format json # JSON-Output für CI-Automatisierung
better-i18n sync -d ./src     # Bestimmtes Verzeichnis scannen

Der Baum-Output gruppiert Keys nach Namespace, sodass leicht erkennbar ist, welche Teile deiner App Lücken aufweisen. Das --verbose-Flag liefert ein tiefgehendes Audit-Log mit Invarianten-Prüfungen, Scoping-Zusammenfassungen und spezifischen Key-Probes.

Coverage-Metriken

Der sync-Befehl liefert prozentbasierte Coverage-Metriken:

• Local-to-Remote-Coverage: Welcher Prozentsatz der in deinem Code verwendeten Keys in better-i18n existiert
• Remote-Nutzung: Welcher Prozentsatz der Keys in better-i18n tatsächlich in deinem Code genutzt wird

Diese Zahlen geben deinem Team jederzeit ein klares Bild der Übersetzungsqualität. Du kannst sie im Terminal-Output einsehen oder aus dem JSON-Output für eigene Dashboards und Reports extrahieren.

CI-Integration

Sowohl scan als auch sync sind für automatisierte Pipelines konzipiert. Nutze --ci mit scan, um Builds zu unterbrechen, wenn hardcodierte Strings erkannt werden, und leite den sync-Output durch jq, um Deploys bei fehlenden Keys zu blockieren.

# GitHub Actions Beispiel
name: i18n Check
on: [push, pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx @better-i18n/cli scan --ci
      - run: |
          npx @better-i18n/cli sync --format json \
            | jq -e '.comparison.missingCount == 0' > /dev/null || exit 1

Für Pre-Commit-Hooks scanne nur staged Files, um schnelles Feedback zu gewährleisten:

npx husky init
echo "npx @better-i18n/cli scan --staged --ci" > .husky/pre-commit

Was dies nicht leistet

Um klare Erwartungen zu setzen:

• Keine visuelle Kontext-Erfassung — das CLI arbeitet auf Code-Ebene, nicht auf der gerenderten UI. Es gibt keine Screenshots oder visuelle Vorschauen, wo Strings erscheinen.
• Kein Echtzeit-Monitoring — scan und sync werden auf Abruf oder in CI-Pipelines ausgeführt; sie sind keine Background-Watcher oder Dateisystem-Observer
• Keine Erkennung veralteter Übersetzungen — der sync-Befehl zeigt fehlende und ungenutzte Keys, erkennt aber nicht, ob eine bestehende Übersetzung im Verhältnis zu einer Quelltext-Änderung veraltet ist

Erste Schritte

Installiere das CLI und führe deinen ersten Scan in unter einer Minute durch:

npm install -g @better-i18n/cli
better-i18n scan --dir ./src

Verbinde dich dann mit deinem better-i18n-Projekt und vergleiche mit der Cloud:

better-i18n sync

Für die Website-Analyse besuche den KI-Kontext-Bereich in deinem Projekt-Dashboard, gib eine URL ein und lass Firecrawl deine Brand-Terminologie extrahieren. Für die Repository-Analyse verbinde dein GitHub-Repo und lass den Analyzer deinen Framework und bestehende Terminologie erkennen.

Siehe die vollständige CLI-Dokumentation für Konfigurationsoptionen, Erkennungsregeln und erweiterte Nutzung.

Bereit, deinen Übersetzungskontext und deine Terminologie-Erkennung zu automatisieren? Erstelle deinen Account und verbinde dein erstes Projekt — oder erfahre, wie das Glossar-Management-System die vom Crawler entdeckten Begriffe durchsetzt.