symbion-payload

Symbion für Payload CMS 3 — KI-Übersetzung mit Translation Memory (v1), SEO & Content-Tools (v2) über die Symbion Cloud. Dritter Symbion-Client nach WordPress und Shopware 6.

Status: Translation + SEO komplett, E2E gegen die Live-Cloud bestanden. Ab 0.2.0 mit SEO-Cockpit.

Funktionsweise: Das Plugin registriert pro aktivierter Collection zwei Sidebar-Panels („Symbion Übersetzung" und die Karte „Symbion SEO" mit Cockpit), in der Media-Collection einen Alt-Text-Generator, ein Settings-Global (Formalität, Modell, Glossar) sowie die Endpoints unter /api/symbion/*:

| Endpoint | Funktion | |---|---| | POST /api/symbion/translate | Dokument in Ziel-Locale übersetzen (Draft bei Versions-Collections) | | POST /api/symbion/seo/generate | Meta-Titel/-Beschreibung/Keywords aus dem Seiteninhalt | | POST /api/symbion/seo/analyze | Deep-Analyse des gerenderten Frontends (Score 0–100 + Findings) | | POST /api/symbion/seo/alt | Alt-Text per Vision-Modell (Bild geht als data:-URL — funktioniert auch lokal) | | POST /api/symbion/seo/keywords | Keyword-Reality-Check (Markt- vs. Binnensprache) | | POST /api/symbion/seo/enhance | Optimierungsvorschläge: Meta-Vorschlag, Absätze zu Keyword-Lücken, Sätze je Keyword | | GET /api/symbion/seo/state | Gespeicherter Stand des Cockpits (Score, Analyse, Vorschläge) und Seiten-URL | | GET /api/symbion/status | Diagnose + Feld-Mapping für die Panels |

Die SEO-Panels schreiben Vorschläge in den Form-State (Redakteur prüft und speichert); per API (write: true, Default) landen sie direkt im Dokument. SEO-Optionen:

symbionPayload({
  collections: ['pages'],
  seo: {
    titleField: 'metaTitle',        // Feld für den Meta-Titel
    descriptionField: 'metaDescription',
    mediaCollection: 'media',       // false = Alt-Text-Feature aus
    altField: 'alt',
    pagePath: (doc) => `/${doc.slug}`, // Frontend-Route für Analyse-URL
    // Optional: absolute öffentliche URL, wenn das Frontend nicht unter serverURL
    // läuft (Reverse Proxy / Marken-Domain; Origin oft bewusst noindex). Vorrang
    // vor serverURL + pagePath; darf req.payload nutzen.
    pageUrl: async (doc, req) => `https://www.example.com/${doc.slug}`,
  },
})

SEO-Cockpit (ab 0.2.0)

In der Seitenleiste zeigt eine Karte den Score, eine kleine Google-Vorschau und den Zustand von Titel, Beschreibung und Keywords. „Cockpit öffnen“ zeigt ein großes Overlay mit vier Reitern:

| Reiter | Inhalt | |---|---| | Google | Vorschau des Suchtreffers (Desktop/Mobil), Titel und Beschreibung mit Längenampel, Generierung per KI | | Social | Vorschau für Facebook, X und LinkedIn, eigener Titel, eigene Beschreibung, eigenes Bild | | Keywords | Fokus-Keywords, Vorschläge der KI, Reality-Check mit Alternativen | | Optimieren | Score mit Kategorien, Befunde nach Dringlichkeit, Optimierungsvorschläge zum Übernehmen |

Das Cockpit arbeitet im Formular: Eingaben erscheinen sofort in der Vorschau und werden erst mit dem Speichern des Dokuments übernommen.

symbionPayload({
  collections: ['pages'],
  seo: {
    titleField: 'metaTitle',
    descriptionField: 'metaDescription',
    // Felder für Social-Vorschau und Keywords (alle optional):
    socialTitleField: 'socialTitle',             // text, empfohlen maxLength 60
    socialDescriptionField: 'socialDescription', // textarea, empfohlen maxLength 160
    socialImageField: 'socialImage',             // upload → mediaCollection
    keywordsField: 'focusKeywords',              // text mit hasMany: true
    // true: fehlende Felder legt das Plugin selbst an (ausgeblendet, Pflege im Cockpit)
    injectFields: false,
  },
})

Ohne diese Feldnamen laufen Social und Keywords als reine Vorschau, die Eingaben werden dann nicht gespeichert. Eigene Felder dürfen mit admin: { hidden: true } ausgeblendet sein.

Ausgabe im Frontend: Das Plugin pflegt nur die Daten. Die Tags og:title, og:description, og:image und die X-Karte gibt das Frontend aus, in Next.js über generateMetadata.

SEO wird nicht übersetzt

Meta-Titel, Meta-Beschreibung, Social-Texte und Fokus-Keywords entstehen je Sprache aus dem Seitentext dieser Sprache. Deshalb gilt ab 0.2.0:

• Die Übersetzung lässt die konfigurierten SEO-Felder aus und kopiert sie auch nicht. Die Zielsprache behält ihre eigenen Angaben.
• Generierung, Analyse und Optimierung laden die Seite in der gewählten Sprache ohne Rückfall auf die Standardsprache. Hat die Seite dort noch keinen Inhalt, antwortet der Endpoint mit locale_empty, statt deutschen Text als Englisch zu verarbeiten.
• Der an die KI gesendete Seitentext enthält die SEO-Felder selbst nicht.

Ablauf für eine neue Sprache: Seite übersetzen, in die Sprache wechseln, im Cockpit „Mit KI generieren“.

Änderungen in 0.2.0

• Neu: SEO-Karte und Cockpit (Google, Social, Keywords, Optimieren), Endpoints seo/state und seo/enhance, Optionen für Social- und Keyword-Felder.
• Geändert: SEO-Felder werden nicht mehr übersetzt (siehe oben).
• Behoben: Übersetzte Seiten ließen sich auf Postgres nicht veröffentlichen. Zeilen in lokalisierten Arrays und Blöcken erbten die ID der Standardsprache; sie bekommen jetzt eigene IDs. Seiten, die mit 0.1.x übersetzt wurden, einmal neu übersetzen.
• Behoben: verwandte Keywords der Generierung kamen nie an (Feldname lsi_keywords).

Update von 0.1.x: Migration nötig

0.2.0 legt die Collection symbion-seo-state an (gespeicherter Analyse-Stand je Dokument und Sprache). Neue Felder kommen hinzu, wenn sie in der Collection ergänzt werden oder injectFields: true gesetzt ist. Bei Postgres und SQLite deshalb nach dem Update:

pnpm payload migrate:create symbion_seo_cockpit
pnpm payload migrate

Konzept & Architektur-Entscheidungen: DOCS/TECH/TECH-PAYLOAD-PLUGIN.md

Verwendung (Ziel-Bild)

// payload.config.ts
import { buildConfig } from 'payload'
import { symbionPayload } from 'symbion-payload'

export default buildConfig({
  // Voraussetzung: localization mit den gewünschten Locales aktiviert
  localization: {
    locales: ['de', 'en'],
    defaultLocale: 'de',
  },
  plugins: [
    symbionPayload({
      collections: ['pages', 'posts'],
    }),
  ],
})

| Env | Default | Zweck | |---|---|---| | SYMBION_LICENSE_KEY | — (Pflicht) | Symbion-Lizenz | | SYMBION_API_URL | https://symbion.dev/api/v1 | Cloud-API | | SYMBION_DOMAIN | Host aus config.serverURL | Domain-Verifikation der Lizenz |

Übersetzt werden nur Felder, die selbst oder über einen Vorfahren localized: true sind. Opt-out pro Feld: custom: { symbion: { skip: true } } — das Feld wird nicht übersetzt, sein Wert aber unverändert in die Ziel-Locale kopiert (für Anker, URL-Ziele, Codes).

Entwicklung

npm install
npm run check        # Typecheck + Tests
npm run build        # dist/ (ESM + d.ts)

Vom Repo-Root: npm run payload:check.