So lokalisieren Sie Ihre elektronischen Unterschriftenabläufe für internationale Nutzer

Wenn Sie das Signiererlebnis von Firma.dev in Ihre App einbetten, möchten Sie wahrscheinlich, dass es der Sprache Ihres Nutzers entspricht. Diese Anleitung erklärt, wie Firma.dev Lokalisierung handhabt und wie Sie diese in Ihre Integration steuern können.

Wie Firma.dev die Sprache erkennt

Firma.dev verwendet ein 3-stufiges Erkennungssystem, das in dieser Reihenfolge geprüft wird:

1. URL-Parameter (?lang=xx) — Höchste Priorität. Wenn Sie einen Sprachcode in die URL einfügen, sieht der Benutzer diese.

2. Lokaler Speicher — Bei erneuten Besuchen prüft Firma.dev auf eine zwischengespeicherte Sprachpräferenz. Dies bietet eine sofortige Sprachauswahl ohne Netzwerkanfrage.

3. Browser-Erkennung — Fällt auf die Sprach- oder Systemeinstellung des Browsers des Benutzers zurück.

Wenn die erkannte Sprache nicht eine der 7 unterstützten Sprachen ist, wählt Firma.dev standardmäßig Englisch.

Unterstützte Sprachen

Firma.dev unterstützt diese Sprachen standardmäßig:

Alle UI-Elemente, Schaltflächen, Beschriftungen, Benachrichtigungen, E-Mails und Fehlermeldungen sind in jeder Sprache vollständig übersetzt.

Steuern der Sprache in eingebettetem Signieren

Wenn Sie den Signierfluss in einem iframe einbetten, funktioniert die Brower-Erkennung nicht zuverlässig. Das iframe übernimmt den Kontext der übergeordneten Seite, nicht die Browsereinstellungen des Benutzers. Sie müssen die Sprache explizit übergeben.

Hängen Sie den ?lang= Parameter an die Signier-URL an:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>

Quelle: Lokalisierungsleitfaden

Dies erzwingt, dass das Signier-Interface auf Spanisch gerendert wird, unabhängig von den Browsereinstellungen des Benutzers.

Abrufen von Signier-URLs und Rendern des Iframes

So erhalten Sie die Signier-URL von der API und rendern sie dynamisch:

// fetch signing request
const r = await fetch('/internal/signing-request/' + signingRequestId)
const json = await r.json()

// get recipient signing URL
const recipient = json.recipients[0]
const signingUrl = recipient.signing_url || `https://app.firma.dev/signing/${recipient.id}`

// render iframe
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-root').appendChild(iframe)

// fetch signing request
const r = await fetch('/internal/signing-request/' + signingRequestId)
const json = await r.json()

// get recipient signing URL
const recipient = json.recipients[0]
const signingUrl = recipient.signing_url || `https://app.firma.dev/signing/${recipient.id}`

// render iframe
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-root').appendChild(iframe)

// fetch signing request
const r = await fetch('/internal/signing-request/' + signingRequestId)
const json = await r.json()

// get recipient signing URL
const recipient = json.recipients[0]
const signingUrl = recipient.signing_url || `https://app.firma.dev/signing/${recipient.id}`

// render iframe
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-root').appendChild(iframe)

Quelle: Leitfaden zur Sendung einer Signaturanfrage

Um die Lokale Ihrer App zu entsprechen, fügen Sie den Sprachparameter hinzu, wenn Sie die iframe-Quelle festlegen:

const userLocale = getCurrentUserLocale() // returns 'es', 'de', 'fr', etc.
iframe.src = `${signingUrl}?lang=${userLocale}`

const userLocale = getCurrentUserLocale() // returns 'es', 'de', 'fr', etc.
iframe.src = `${signingUrl}?lang=${userLocale}`

const userLocale = getCurrentUserLocale() // returns 'es', 'de', 'fr', etc.
iframe.src = `${signingUrl}?lang=${userLocale}`

Dies hält das Signiererlebnis konsistent mit dem Rest Ihrer Anwendung.

Best Practices

Diese Richtlinien stammen direkt aus der Dokumentation von Firma.dev:

• Verwenden Sie den lang-Parameter beim eingebetteten Signieren — Verlassen Sie sich nicht auf die Browser-Erkennung in iframe-Kontexten. Übergeben Sie die Sprache explizit, um ein konsistentes Erlebnis zu gewährleisten.

• Passen Sie die Lokale Ihrer Anwendung an — Beim Einbetten von Firma.dev sollten Sie die gleiche Lokale übergeben, die Ihre Anwendung verwendet, damit das Signiererlebnis nahtlos ist.

• Lassen Sie die Benutzer wählen — Für direkte Links von Firma.dev (z. B. in E-Mails) lassen Sie den lang-Parameter weg und lassen Sie die automatische Erkennung von Firma.dev dies übernehmen. Benutzer, die eine Präferenz eingestellt haben, sehen ihre gewählte Sprache.

Quelle: Lokalisierungsleitfaden

Lokalisierung in anderen einbettbaren Komponenten

Der ?lang= Parameter funktioniert auf die gleiche Weise für andere einbettbare Komponenten von Firma.dev:

• Einbettbarer Vorlage Editor — Zum Erstellen und Bearbeiten von Dokumentvorlagen

• Einbettbarer Signaturanfrage-Editor — Zum Konfigurieren von Empfängern und Versandoptionen

Beide verwenden JWT-Authentifizierung und unterstützen alle 7 Sprachen. Siehe den Leitfaden für den einbettbaren Signaturanfrage-Editor für Implementierungsdetails.

Ein Hinweis zur Infrastruktur

Firma.dev wird in der EU (AWS Paris-Region) gehostet, was sich gut mit mehrsprachiger Unterstützung verbinden lässt, wenn Sie europäische Märkte bedienen. Die Plattform unterstützt die DSGVO und eIDAS (SES- und AdES-Stufen) für regionale Compliance-Anforderungen.

Nächste Schritte

Für die vollständige technische Referenz schauen Sie sich den Lokalisierungsleitfaden in den Dokumenten an. Er behandelt Randfälle wie Teams mit gemischten Sprachen und Verhalten bei Sprachpersistence.

Bereit sich zu bauen? API-Schlüssel holen und beginnen Sie mit der Integration von lokalisierten E-Signaturen. Keine Kreditkarte erforderlich.