How to Localize Your E-Signature Flows for International Users

If you're embedding Firma.dev's signing experience in your app, you probably want it to match your user's language. This guide walks through how Firma.dev handles localization and how to control it in your integration.

How Firma.dev Detects Language

Firma.dev uses a 3-tier detection system, checked in this order:

1. URL parameter (?lang=xx) — Highest priority. If you pass a language code in the URL, that's what the user sees.

2. Local storage — On return visits, Firma.dev checks for a cached language preference. This provides instant language selection without a network request.

3. Browser detection — Falls back to the user's browser or system language setting.

If the detected language isn't one of the 7 supported languages, Firma.dev defaults to English.

Supported Languages

Firma.dev supports these languages out of the box:

All UI elements, buttons, labels, notifications, emails, and error messages are fully translated in each language.

Controlling Language in Embedded Signing

When you embed the signing flow in an iframe, browser detection doesn't work reliably. The iframe inherits the parent page's context, not the user's browser settings. You need to pass the language explicitly.

Append the ?lang= parameter to the signing URL:

<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>

Source: Localization Guide

This forces the signing interface to render in Spanish regardless of the user's browser settings.

Fetching Signing URLs and Rendering the Iframe

Here's how to get the signing URL from the API and render it dynamically:

// 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)

Source: Sending a Signing Request Guide

To match your app's locale, append the language parameter when setting the iframe source:

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}`

This keeps the signing experience consistent with the rest of your application.

Best Practices

These guidelines come directly from Firma.dev's documentation:

• Use the lang parameter in embedded signing — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.

• Match your application's locale — When embedding Firma.dev, pass the same locale your application is using so the signing experience feels seamless.

• Let users choose — For direct Firma.dev links (e.g., in emails), omit the lang parameter and let Firma.dev's automatic detection handle it. Users who have set a preference will see their chosen language.

Source: Localization Guide

Localization in Other Embeddable Components

The ?lang= parameter works the same way for Firma.dev's other embeddable components:

• Embeddable template editor — For building and editing document templates

• Embeddable signing request editor — For configuring recipients and sending options

Both use JWT authentication and support all 7 languages. See the Embeddable Signing Request Editor Guide for implementation details.

A Note on Infrastructure

Firma.dev is hosted in the EU (AWS Paris region), which pairs well with multilingual support if you're serving European markets. The platform supports GDPR and eIDAS (SES and AdES levels) for regional compliance needs.

Next Steps

For the complete technical reference, check out the Localization Guide in the docs. It covers edge cases like mixed-language teams and language persistence behavior.

Ready to build? Get your API key now and start integrating localized e-signatures. No credit card required.