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

Wenn Sie die Signaturerfahrung von Firma.dev in Ihrer App einbetten, möchten Sie wahrscheinlich, dass sie mit der Sprache Ihres Benutzers übereinstimmt. Dieser Leitfaden erklärt, wie Firma.dev Lokalisierung handhabt und wie Sie es in Ihre Integration steuern können.

Wie Firma.dev die Sprache erkennt

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

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

2. Lokaler Speicher — Bei Rückkehrbesuchen überprüft Firma.dev, ob eine zwischengespeicherte Sprachpräferenz vorliegt. Dies ermöglicht eine sofortige Sprachauswahl ohne Netzwerkanfrage.

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

Wenn die erkannte Sprache nicht eine der 7 unterstützten Sprachen ist, wird Firma.dev standardmäßig auf Englisch zurückgesetzt.

Unterstützte Sprachen

Firma.dev unterstützt diese Sprachen von Haus aus:

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

Steuerung der Sprache bei eingebetteten Signaturen

Wenn Sie den Signaturfluss in einem iframe einbetten, funktioniert die Browser-Erkennung nicht zuverlässig. Das iframe erbt den Kontext der übergeordneten Seite, nicht die Browsereinstellungen des Nutzers. Sie müssen die Sprache explizit übergeben.

Fügen Sie den ?lang= Parameter zur Signatur-URL hinzu:

<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 die Signaturoberfläche unabhängig von den Browsereinstellungen des Nutzers auf Spanisch dargestellt wird.

Abrufen von Signatur-URLs und Rendern des iFrames

So erhalten Sie die Signatur-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 zum Senden einer Signaturanfrage

Um die Lokalisierung Ihrer App beizubehalten, fügen Sie den Sprachparameter hinzu, wenn Sie die iframe-Quelle einstellen:

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 die Signaturerfahrung konsistent mit dem Rest Ihrer Anwendung.

Beste Praktiken

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

• Verwenden Sie den lang-Parameter bei eingebetteten Signaturen — Verlassen Sie sich nicht auf die Browsererkennung in iframe-Kontexten. Übergeben Sie die Sprache explizit, um eine konsistente Erfahrung sicherzustellen.

• Passen Sie die Sprache Ihrer Anwendung an — Wenn Sie Firma.dev einbetten, übergeben Sie die gleiche Sprache, die Ihre Anwendung verwendet, damit sich die Signaturerfahrung nahtlos anfühlt.

• Lassen Sie die Benutzer wählen — Für direkte Firma.dev-Links (z.B. in E-Mails) lassen Sie den lang-Parameter weg und überlassen Sie die automatische Erkennung von Firma.dev. Benutzer, die eine Präferenz festgelegt 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 Vorlageneditor — Zum Erstellen und Bearbeiten von Dokumentvorlagen

• Einbettbarer Signaturanforderungseditor — Zum Konfigurieren von Empfängern und Sendeoptionen

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

Ein Hinweis zur Infrastruktur

Firma.dev wird in der EU (AWS Paris Region) gehostet, was sich gut mit mehrsprachiger Unterstützung kombinieren lässt, wenn Sie europäische Märkte bedienen. Die Plattform unterstützt GDPR und eIDAS (SES und AdES Ebenen) 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 das Verhalten der Sprachpersistenz.

Bereit zum Bauen? Holen Sie sich jetzt Ihren API-Schlüssel und beginnen Sie mit der Integration lokalisierter E-Signaturen. Keine Kreditkarte erforderlich.