Ein Produkt, viele Kunden: Übersetzungen pro Kunde mit Tenants, ein Beispiel Schritt für Schritt

Übersetzungen pro Kunde (auch Tenant-Overrides genannt) lassen ein Produkt die Sprache jedes Kunden sprechen, im wörtlichen wie im kommerziellen Sinn: Dieselbe App sagt bei einer Praxis "Patient" und bei einer anderen "Klient", nennt hier eine Stornierungsfrist von 24 Stunden und dort eine von 48 Stunden und zeigt den Namen des Kunden statt Ihres eigenen, während alles andere ein gemeinsamer Satz an Übersetzungen bleibt. Dieser Beitrag vergleicht die Wege, auf denen Teams das bauen, und geht dann einen echten Lauf durch: ein Basisprojekt, drei Kunden-Tenants, ihre Overrides, was passiert ist, als sich der Basistext geändert hat, und wie die App den richtigen Kunden lädt.

Fünf Wege, wie Teams Formulierungen pro Kunde umsetzen

Die ersten vier brauchen kein spezielles Tooling, und der zweite ist für wenige Kunden ein völlig solides i18next-Setup. Der Rest dieses Beitrags handelt vom fünften, bei dem ein weiterer Kunde ein weiterer Tenant ist, keine weitere Kopie.

Das Beispiel

ClinicDesk ist eine Termin-App für Praxen, die als White-Label verkauft wird. Ihre drei Kunden sind für dieses Beispiel erfunden:

Das Basisprojekt hat 15 Keys in Englisch, Deutsch und Französisch (Französisch fügt eine Pluralform hinzu).

Schritt 1: Das Basisprojekt

Die Basis enthält die Formulierungen des Produkts selbst: Navigation, Buttons, den Buchungsablauf, eine Erinnerungs-SMS, die Stornierungsregel. Wir haben die 15 englischen Keys mit je einem Satz Kontext gemeldet, und die automatische Übersetzung hat Deutsch und Französisch gefüllt. Die Stornierungsregel wurde zum Beispiel zu "Sie können bis zu 24 Stunden vor Ihrem Termin kostenfrei stornieren." und "Vous pouvez annuler sans frais jusqu'à 24 heures avant votre rendez-vous."

Schritt 2: Ein Tenant pro Kunde

Auf der Multi-Tenant-Seite des Projekts erhält jeder Kunde einen Tenant: ein eigenes Projekt, angelegt aus der Basis. Mit aktiviertem can't deviate from parent (der Standard) hat ein Tenant immer die Sprachen und Namespaces der Basis, eine neue Sprache in der Basis erscheint also in jedem Tenant.

Jeder Tenant hat seine eigene Projekt-ID, eigene Nutzer und eigene API-Keys. Die Leute eines Kunden können Sie gezielt nur in dessen Tenant einladen, und sie sehen die anderen Kunden nicht; Ihr eigenes Team erreicht als Mitglieder Ihrer Organisation alle Tenants.

Schritt 3: Die eigenen Formulierungen jedes Kunden

Overrides sind gewöhnliche Bearbeitungen im Tenant: im Editor, über die API oder, wie hier, über den MCP-Server. Wir haben die englischen Overrides für jeden Kunden geschrieben: sechs für Physio North, drei für Praxis am See, einen für Smile Dental:

Eines hatten wir nicht eingeplant: Sobald die englischen Overrides von Physio North gespeichert waren, hat die automatische Übersetzung des Tenants daraus Entwürfe auf Deutsch und Französisch erstellt, jeden mit einem Konfidenzwert und zum Review markiert. Wir haben die Support-Zeile in beiden Sprachen umgeschrieben und die anderen fünf Entwürfe für das Review des Kunden stehen lassen. Für die 48-Stunden-Regel von Praxis am See entstanden die Entwürfe auf dieselbe Weise ("48 heures" auf Französisch); den französischen Entwurf haben wir behalten, den deutschen ersetzt. Das passiert, wenn im Tenant die automatische Übersetzung aktiviert ist (er übernimmt die Einstellung beim Anlegen von der Basis) und der Override über die API, die CLI oder MCP als Key ankommt, den der Tenant noch nicht hatte; ein Override, der im Editor eingetippt wird, oder eine zweite Änderung an einem bestehenden Override erhält keinen Entwurf, ausser Sie fordern eine Übersetzung an.

Im Editor des Tenants listet der Filter overridden jeden Override auf, die automatischen Entwürfe eingeschlossen:

Schritt 4: Die Basis ändert sich

Dann haben wir einen Basistext geändert: Die englische Support-Zeile wurde zu "Questions? Our support team replies within one business day.", gepusht mit angeforderter automatischer Übersetzung, sodass Deutsch und Französisch neu übersetzt wurden. (Ohne diese Anforderung behält ein geänderter Quelltext seine Übersetzungen und markiert sie zum Review.) Zwei Tenants überschreiben diesen Key, einer nicht:

• Smile Dental (kein Override) zeigte die neue Zeile sofort, auf Deutsch "Haben Sie Fragen? Unser Support-Team antwortet Ihnen innerhalb eines Werktages.", und seine Dateien auf dem CDN enthielten sie, ohne dass jemand den Tenant veröffentlicht hätte (die Version veröffentlicht automatisch; sonst wird der Tenant neu veröffentlicht, wenn Sie die Basis veröffentlichen).
• Physio North und Praxis am See behielten ihre eigenen Zeilen. Ein Abruf der Rohdaten des Tenants (durch jemanden mit Zugriff auf die Basis) zeigt neben jedem Override, welchen Basiswert er ersetzt, sodass ein Agent oder ein Skript sie vergleichen kann.

Das ist die Regel, die man sich merken sollte: Keys, die ein Kunde nicht angefasst hat, folgen der Basis; Keys, die ein Kunde geändert hat, bleiben seine, bis der Override gelöscht wird, danach erbt der Tenant wieder die Basis. Overrides, die eine Verbesserung der Basis verpassen, sind das Hauptrisiko dieses Musters: Wenn sich der Quelltext der Basis ändert, werden die überschriebenen Übersetzungen eines Tenants zum Review markiert (ausser die Änderung wurde neu übersetzt, wie in diesem Lauf), ein Override in der Quellsprache bekommt aber kein Signal. Der Editor des Basisprojekts hat eine direkte Antwort auf "Wer ist betroffen?": Wählen Sie einen Key und eine Sprache, und check tenants listet die Tenants, die Sie öffnen können und die ihn überschreiben, mit ihren Werten.

Schritt 5: Den richtigen Kunden laden

Die veröffentlichten Dateien jedes Tenants auf dem CDN kombinieren die Basis bereits mit den Overrides des Kunden: Die englische Datei von Physio North sagt "Clients" und "Physio North", die von Smile Dental "Patients" und "Smile Dental". Die App muss nur wissen, welchen Kunden sie bedient, anhand der Subdomain, des Logins oder eines Konfigurationswerts, und die Projekt-ID dieses Tenants an das Backend übergeben:

import i18next from 'i18next'
import LocizeBackend from 'i18next-locize-backend'

// one tenant project ID per customer; customers without own wording load the base
const TENANT_PROJECT_IDS = {
  'physio-north': '<physio north tenant project id>',
  'praxis-am-see': '<praxis am see tenant project id>',
  'smile-dental': '<smile dental tenant project id>'
}
const BASE_PROJECT_ID = '<base project id>'

i18next.use(LocizeBackend).init({
  fallbackLng: 'en',
  backend: {
    projectId: TENANT_PROJECT_IDS[customer] ?? BASE_PROJECT_ID,
    version: 'latest'
  }
})

Weil die Dateien zur Laufzeit geladen werden, geht die Änderung eines Kunden ohne ein Release Ihrer App live; wie schnell Nutzer sie sehen, hängt vom Caching ab, beschrieben in Übersetzungen ohne Redeploy aktualisieren. Wenn Sie Übersetzungen stattdessen bündeln, laden Sie die Dateien jedes Tenants auf dieselbe Weise in Ihrem Build herunter.

Kosten und Zugriff

• Pläne: Tenants werden mit ihrem Basisprojekt abgerechnet. Growth enthält 5, Professional 10, Professional Plus 20, Enterprise 50; weitere gibt es in Paketen (Preise).
• Wörter: Nur überschriebene Werte zählen, die 14 englischen Keys, die Smile Dental erbt, werden also nicht erneut berechnet.
• Aufschlüsselung pro Tenant: Das Tenants-Panel zeigt Admins eine Schätzung, was die Nutzung jedes Tenants zu Ihren Preisen wert ist, um Kosten an Kunden weiterzugeben.
• Zugriff: Kunden können in ihrem Tenant arbeiten, ohne einander zu sehen; die Mitglieder Ihrer Organisation erreichen jeden Tenant.

Worauf Sie achten sollten

• Overrides frieren einen Key für diesen Kunden ein. Wenn Sie einen Basistext verbessern, prüfen Sie die Tenants, die ihn überschreiben; das Löschen eines Overrides gibt den Key an die Basis zurück.
• Überschreiben Sie jede Sprache, die ein Kunde verwendet. Ein englischer Override allein lässt die anderen Sprachen des Tenants beim Basistext, ein Kunde könnte also auf Englisch 48 Stunden lesen und auf Deutsch 24. Entwürfe, die aus einem Override entstehen, sind ebenfalls Overrides: Sie zählen als Wörter und folgen der Basis nicht mehr.
• Legen Sie fest, wer was überschreiben darf. Ein Kunde, der seinen eigenen Tenant bearbeitet, kann jeden Key ändern, auch Rechtstexte. Halten Sie Compliance-Formulierungen in der Basis und vereinbaren Sie mit den Kunden, welche Keys ihnen gehören.
• Sprachen pro Kunde. Ist "can't deviate from parent" ausgeschaltet, kann ein Tenant Sprachen haben, die die Basis nicht hat, und Sprachen, die der Basis hinzugefügt werden, werden ihm dann nicht automatisch hinzugefügt. Entscheiden Sie pro Tenant.
• Verschiedene Produkte sind keine Tenants. Wenn die Apps zweier Kunden kaum mehr als einen Login-Screen gemeinsam haben, sind separate Projekte einfacher.

Ausprobieren

Die Multi-Tenant-Dokumentation behandelt die Einstellungen und Optionen. Jedes Konto startet mit einer 14-tägigen Testversion mit allen Funktionen und ohne Kreditkarte, genug, um ein Basisprojekt und zwei Tenants anzulegen, ein paar Keys zu überschreiben und die Dateien jedes Kunden in Ihrer App zu laden.

Häufig gestellte Fragen