Cómo localizar tus flujos de firma electrónica para usuarios internacionales

Si estás incrustando la experiencia de firma de Firma.dev en tu aplicación, probablemente querrás que coincida con el idioma de tu usuario. Esta guía explica cómo gestiona Firma.dev la localización y cómo controlarla en tu integración.

Cómo detecta el idioma Firma.dev

Firma.dev utiliza un sistema de detección en 3 niveles, comprobado en este orden:

1. Parámetro de URL (?lang=xx) — Máxima prioridad. Si pasas un código de idioma en la URL, eso es lo que verá el usuario.

2. Almacenamiento local — En visitas posteriores, Firma.dev comprueba si hay una preferencia de idioma almacenada en caché. Esto proporciona una selección de idioma instantánea sin una solicitud de red.

3. Detección del navegador — Recurre al navegador del usuario o a la configuración de idioma del sistema.

Si el idioma detectado no es uno de los 7 idiomas compatibles, Firma.dev usa el inglés por defecto.

Idiomas compatibles

Firma.dev admite estos idiomas de forma nativa:

Todos los elementos de la interfaz, botones, etiquetas, notificaciones, correos electrónicos y mensajes de error están completamente traducidos en cada idioma.

Control del idioma en la firma incrustada

Cuando incrustas el flujo de firma en un iframe, la detección del navegador no funciona de forma fiable. El iframe hereda el contexto de la página principal, no la configuración del navegador del usuario. Debes pasar el idioma explícitamente.

Añade el parámetro ?lang= a la URL de firma:

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

Fuente: Guía de localización

Esto obliga a que la interfaz de firma se muestre en español independientemente de la configuración del navegador del usuario.

Obtención de URLs de firma y renderizado del iframe

Así es como obtener la URL de firma desde la API y renderizarla dinámicamente:

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

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

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

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

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

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

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

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

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

Fuente: Guía para enviar una solicitud de firma

Para que coincida con la configuración regional de tu app, añade el parámetro de idioma al establecer el origen del iframe:

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

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

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

Esto mantiene la experiencia de firma coherente con el resto de tu aplicación.

Buenas prácticas

Estas directrices provienen directamente de la documentación de Firma.dev:

• Usa el parámetro lang en la firma incrustada — No dependas de la detección del navegador en contextos de iframe. Pasa el idioma explícitamente para garantizar una experiencia coherente.

• Coincide con la configuración regional de tu aplicación — Al incrustar Firma.dev, pasa la misma configuración regional que usa tu aplicación para que la experiencia de firma resulte fluida.

• Deja que los usuarios elijan — Para enlaces directos de Firma.dev (p. ej., en correos electrónicos), omite el parámetro lang y deja que la detección automática de Firma.dev lo gestione. Los usuarios que hayan establecido una preferencia verán su idioma elegido.

Fuente: Guía de localización

Localización en otros componentes incrustables

El parámetro ?lang= funciona igual para los demás componentes incrustables de Firma.dev:

• Editor de plantillas incrustable — Para crear y editar plantillas de documentos

• Editor incrustable de solicitudes de firma — Para configurar destinatarios y opciones de envío

Ambos usan autenticación JWT y admiten los 7 idiomas. Consulta la Guía del editor incrustable de solicitudes de firma para obtener detalles de implementación.

Una nota sobre la infraestructura

Firma.dev está alojado en la UE (región de AWS París), lo que encaja bien con el soporte multilingüe si atiendes a mercados europeos. La plataforma admite GDPR y eIDAS (niveles SES y AdES) para necesidades de cumplimiento regional.

Próximos pasos

Para la referencia técnica completa, consulta la Guía de localización en la documentación. Cubre casos límite como equipos multilingües y el comportamiento de persistencia del idioma.

¿Listo para empezar? Obtener clave API y empieza a integrar firmas electrónicas localizadas. No se requiere tarjeta de crédito.