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

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

Cómo Firma.dev Detecta el Idioma

Firma.dev utiliza un sistema de detección de 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 ve el usuario.

2. Almacenamiento local — En visitas de retorno, Firma.dev verifica una preferencia de idioma almacenada. Esto proporciona una selección de idioma instantánea sin una solicitud de red.

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

Si el idioma detectado no es uno de los 7 idiomas soportados, Firma.dev predetermina a inglés.

Idiomas Soportados

Firma.dev soporta estos idiomas directamente:

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

Control de Idioma en la Firma Embebida

Cuando integras el flujo de firma en un iframe, la detección del navegador no funciona de manera confiable. El iframe hereda el contexto de la página principal, no la configuración del navegador del usuario. Necesitas 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 fuerza a la interfaz de firma a funcionar en español independientemente de la configuración del navegador del usuario.

Obtención de URLs de Firma y Representación del Iframe

Aquí se explica cómo obtener la URL de firma de la API y representarla dinámicamente:

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

Fuente: Guía de Envío de Solicitud de Firma

Para coincidir con la configuración local de tu aplicación, añade el parámetro de idioma al configurar la fuente del iframe:

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

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

Mejores Prácticas

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

• Utiliza el parámetro lang en firmas embebidas — No confíes en la detección del navegador en contextos de iframe. Pasa el idioma explícitamente para asegurar una experiencia consistente.

• Coincide con la configuración local de tu aplicación — Al integrar Firma.dev, pasa la misma configuración de idioma que usa tu aplicación para que la experiencia de firma se sienta fluida.

• Deja que los usuarios elijan — Para enlaces directos de Firma.dev (por ejemplo, en correos electrónicos), omite el parámetro lang y deja que la detección automática de Firma.dev lo maneje. Los usuarios que han configurado una preferencia verán su idioma escogido.

Fuente: Guía de Localización

Localización en Otros Componentes Embebibles

El parámetro ?lang= funciona de la misma manera para otros componentes embebibles de Firma.dev:

• Editor de plantillas embebible — Para construir y editar plantillas de documentos

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

Ambos usan autenticación JWT y soportan los 7 idiomas. Consulta la Guía del Editor de Solicitudes de Firma Embebible para detalles de implementación.

Una Nota sobre la Infraestructura

Firma.dev está alojado en la UE (región de AWS París), lo cual se adapta bien al soporte multilingüe si estás sirviendo a mercados europeos. La plataforma soporta 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 los documentos. Cubre casos desafíos como equipos de idiomas mixtos y el comportamiento de persistencia del idioma.

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