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

Wenn Sie das Signatur-Erlebnis von Firma.dev in Ihre App einbetten, möchten Sie wahrscheinlich, dass es der Sprache Ihrer Benutzer entspricht. Dieser Leitfaden beschreibt, wie Firma.dev die Lokalisierung handhabt und wie Sie diese in Ihrer Integration steuern können.

Wie Firma.dev die Sprache erkennt

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

1. URL-Parameter (?lang=xx) — Höchste Priorität. Wenn Sie einen Sprachcode in der URL übergeben, ist es das, was der Benutzer sieht.

2. Lokaler Speicher — Bei wiederholten Besuchen prüft Firma.dev, ob eine Sprachpräferenz im Cache gespeichert ist. Dies ermöglicht eine sofortige Sprachauswahl ohne Netzwerkanfrage.

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

Wenn die erkannte Sprache keine der 7 unterstützten Sprachen ist, verwendet 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.

Steuerung der Sprache beim eingebetteten Signieren

Wenn Sie den Signatur-Ablauf in ein Iframe einbetten, funktioniert die Browser-Erkennung nicht zuverlässig. Das Iframe erbt den Kontext der übergeordneten Seite, nicht die Browsereinstellungen des Benutzers. Sie müssen die Sprache explizit übergeben.

Hängen Sie den Parameter ?lang= an die Signatur-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 zwingt die Signatur-Oberfläche, auf Spanisch zu rendern, unabhängig von den Browsereinstellungen des Benutzers.

Abrufen von Signatur-URLs und Rendern des Iframes

So rufen Sie die Signatur-URL aus der API ab 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 dem Gebietsschema Ihrer App zu entsprechen, hängen Sie beim Festlegen der Iframe-Quelle den Sprachparameter an:

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 Signatur-Erlebnis 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 in Iframe-Kontexten nicht auf die Browser-Erkennung. Übergeben Sie die Sprache explizit, um ein konsistentes Erlebnis zu gewährleisten.

• Passen Sie das Gebietsschema Ihrer Anwendung an — Wenn Sie Firma.dev einbetten, übergeben Sie dasselbe Gebietsschema, das Ihre Anwendung verwendet, damit sich das Signieren nahtlos anfühlt.

• Lassen Sie die Benutzer wählen — Lassen Sie bei direkten Links zu Firma.dev (z. B. in E-Mails) den lang-Parameter weg und überlassen Sie die Erkennung der automatischen Erkennung von Firma.dev. Benutzer, die eine Präferenz eingestellt haben, sehen ihre gewählte Sprache.

Quelle: Lokalisierungsleitfaden

Lokalisierung in anderen einbettbaren Komponenten

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

• Einbettbarer Vorlagen-Editor — Zum Erstellen und Bearbeiten von Dokumentvorlagen

• Einbettbarer Signaturanfragen-Editor — Zum Konfigurieren von Empfängern und Sendeoptionen

Beide nutzen die JWT-Authentifizierung und unterstützen alle 7 Sprachen. Einzelheiten zur Implementierung finden Sie im Leitfaden für den einbettbaren Signaturanfragen-Editor.

Ein Hinweis zur Infrastruktur

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

Nächste Schritte

Die vollständige technische Referenz finden Sie im Lokalisierungsleitfaden in den Dokumenten. Er behandelt Sonderfälle wie gemischtsprachige Teams und das Verhalten bei der Sprachpersistenz.

Bereit zum Entwickeln? API-Schlüssel holen und mit der Integration lokalisierter elektronischer Signaturen beginnen. Keine Kreditkarte erforderlich.