Separación silábica personalizada para PDFs en español con IronPDF

Por qué los términos normativos españoles no se separan

Los acrónimos y nombres propios del entorno regulatorio español tienen una particularidad que los diferencia del vocabulario técnico general: son términos fijados por normativa o por uso institucional, y cualquier alteración visual —incluida la separación silábica— puede generar dudas sobre la integridad del documento en una auditoría.

LOPDGDD (Ley Orgánica de Protección de Datos y Garantía de Derechos Digitales) es el marco jurídico de protección de datos en España, supervisado por la AEPD. Los documentos con datos personales archivados bajo LOPDGDD deben conservar su presentación tipográfica original; si el sistema de guionización intenta separar el acrónimo (LO-PDGDD), el documento archivado difiere visualmente del emitido, lo que puede ser cuestionado en una auditoría de conformidad.

VERI*FACTU es la leyenda obligatoria que la AEAT exige en facturas del sistema VeriFactu (RDL 15/2025). La forma exacta —con asterisco central, sin separación— está fijada por la norma. La alternativa también fijada textualmente es "Factura verificable en la sede electrónica de la AEAT". Ambas formas deben representarse íntegras y sin modificación tipográfica.

VeriFactu como nombre del régimen fiscal, TicketBAI como nombre del sistema foral vasco y Facturae como nombre del formato de factura electrónica para la Administración son nombres propios del entorno normativo español. El motor de guionización TeX los trata como palabras comunes y puede intentar separarlos; deben protegerse con hyphens: none.

La técnica CSS es directa:

<style>
  .norma { hyphens: none; -webkit-hyphens: none; white-space: nowrap; }
</style>

<p>Factura conforme a <span class="norma">VeriFactu</span>
   (RDL 15/2025). Para verificar, acceda a la sede electrónica de la
   <span class="norma">AEAT</span> o escanee el QR.</p>

<style>
  .norma { hyphens: none; -webkit-hyphens: none; white-space: nowrap; }
</style>

<p>Factura conforme a <span class="norma">VeriFactu</span>
   (RDL 15/2025). Para verificar, acceda a la sede electrónica de la
   <span class="norma">AEAT</span> o escanee el QR.</p>

La clase CustomHyphenationDefinitions para castellano

La propiedad CustomHyphenation acepta una instancia de CustomHyphenationDefinitions con dos campos: PatternSource (obligatorio, ruta o URL al fichero de patrones en formato TeX) y ExceptionSource (opcional, ruta o URL al fichero de excepciones para palabras con separación irregular en castellano).

El proyecto tex-hyphen mantiene los ficheros hyph-es.pat.txt y hyph-es.hyp.txt con los patrones del español peninsular conformes a las normas de la RAE. Estos ficheros son distintos de los ficheros para el español latinoamericano y de los de otras lenguas peninsulares (catalán: hyph-ca.pat.txt, gallego: hyph-gl.pat.txt, euskera: hyph-eu.pat.txt).

El orden de prioridad en IronPDF es: primero CustomHyphenation si PatternSource es válido; después HyphenationLanguage si no hay patrones personalizados; y finalmente sin guionización si ninguno está configurado. El enum HyphenationLanguage no incluye español, así que para documentos en castellano CustomHyphenation es la única vía de guionización correcta.

Caso práctico: facturas bilingües castellano-euskera bajo TicketBAI/BATUZ

Los ISV que atienden a contribuyentes de Bizkaia bajo el sistema BATUZ de la Hacienda Foral enfrentan un escenario de guionización complejo: la misma empresa puede necesitar emitir la factura de visualización en castellano para clientes fuera del País Vasco y en euskera para interlocutores institucionales de la comunidad.

Bizkaia (bizkaia.eus) opera BATUZ desde 2022; los ISV registran el XML de facturación en la plataforma BATUZ antes de entregar el PDF al receptor. Gipuzkoa (gipuzkoa.eus) y Araba (araba.eus) tienen sus propios calendarios de implantación TicketBAI. En los tres territorios forales, el PDF de visualización que recibe el receptor puede emitirse en la lengua de la comunicación comercial.

Para gestionar el cambio de idioma de guionización por documento:

using IronPdf;

var renderer = new ChromePdfRenderer();
renderer.RenderingOptions.InputEncoding = System.Text.Encoding.UTF8;

// Para el PDF de visualización TicketBAI en castellano
renderer.RenderingOptions.CustomHyphenation = new CustomHyphenationDefinitions
{
    PatternSource = @"/app/patrones/hyph-es.pat.txt"
};

// Para el PDF de visualización TicketBAI en euskera (Bizkaia, Gipuzkoa, Araba)
renderer.RenderingOptions.CustomHyphenation = new CustomHyphenationDefinitions
{
    PatternSource = @"/app/patrones/hyph-eu.pat.txt"
};

using IronPdf;

var renderer = new ChromePdfRenderer();
renderer.RenderingOptions.InputEncoding = System.Text.Encoding.UTF8;

// Para el PDF de visualización TicketBAI en castellano
renderer.RenderingOptions.CustomHyphenation = new CustomHyphenationDefinitions
{
    PatternSource = @"/app/patrones/hyph-es.pat.txt"
};

// Para el PDF de visualización TicketBAI en euskera (Bizkaia, Gipuzkoa, Araba)
renderer.RenderingOptions.CustomHyphenation = new CustomHyphenationDefinitions
{
    PatternSource = @"/app/patrones/hyph-eu.pat.txt"
};

Imports IronPdf

Dim renderer As New ChromePdfRenderer()
renderer.RenderingOptions.InputEncoding = System.Text.Encoding.UTF8

' Para el PDF de visualización TicketBAI en castellano
renderer.RenderingOptions.CustomHyphenation = New CustomHyphenationDefinitions With {
    .PatternSource = "/app/patrones/hyph-es.pat.txt"
}

' Para el PDF de visualización TicketBAI en euskera (Bizkaia, Gipuzkoa, Araba)
renderer.RenderingOptions.CustomHyphenation = New CustomHyphenationDefinitions With {
    .PatternSource = "/app/patrones/hyph-eu.pat.txt"
}

En ambos casos, la leyenda VERI*FACTU o la frase alternativa de verificación AEAT debe estar protegida con hyphens: none, independientemente del idioma del cuerpo de la factura.

Comunidades autónomas con lengua cooficial: escenario multipatrones

España tiene cinco lenguas cooficiales con ámbitos territoriales concretos. Los ISV que generan documentación administrativa —contratos de trabajo, documentación sanitaria, licencias de actividad— para administraciones autonómicas necesitan soporte de guionización para varias lenguas:

El catalán se usa en Cataluña, Comunitat Valenciana (donde se denomina valenciano) e Islas Baleares. Para documentos de las administraciones autonómicas de estas comunidades, los patrones hyph-ca.pat.txt proporcionan guionización conforme a las normas del Institut d'Estudis Catalans.

El gallego se usa en Galicia. Los patrones hyph-gl.pat.txt cubren las normas del Instituto da Lingua Galega y la Real Academia Galega.

Para un ISV que genera contratos laborales para clientes en múltiples comunidades autónomas, la selección de patrones por comunidad o idioma de documento puede encapsularse en una función de configuración:

using IronPdf;

void ConfigurarGuionizacion(ChromePdfRenderer renderer, string idioma)
{
    string fichero = idioma switch
    {
        "es" => "/app/patrones/hyph-es.pat.txt",  // Castellano (RAE)
        "ca" => "/app/patrones/hyph-ca.pat.txt",  // Catalán/Valenciano/Balear
        "gl" => "/app/patrones/hyph-gl.pat.txt",  // Gallego
        "eu" => "/app/patrones/hyph-eu.pat.txt",  // Euskera (Euskaltzaindia)
        _    => "/app/patrones/hyph-es.pat.txt"   // Castellano por defecto
    };

    renderer.RenderingOptions.CustomHyphenation = new CustomHyphenationDefinitions
    {
        PatternSource = fichero
    };
}

using IronPdf;

void ConfigurarGuionizacion(ChromePdfRenderer renderer, string idioma)
{
    string fichero = idioma switch
    {
        "es" => "/app/patrones/hyph-es.pat.txt",  // Castellano (RAE)
        "ca" => "/app/patrones/hyph-ca.pat.txt",  // Catalán/Valenciano/Balear
        "gl" => "/app/patrones/hyph-gl.pat.txt",  // Gallego
        "eu" => "/app/patrones/hyph-eu.pat.txt",  // Euskera (Euskaltzaindia)
        _    => "/app/patrones/hyph-es.pat.txt"   // Castellano por defecto
    };

    renderer.RenderingOptions.CustomHyphenation = new CustomHyphenationDefinitions
    {
        PatternSource = fichero
    };
}

Imports IronPdf

Sub ConfigurarGuionizacion(renderer As ChromePdfRenderer, idioma As String)
    Dim fichero As String = If(idioma = "es", "/app/patrones/hyph-es.pat.txt", 
                               If(idioma = "ca", "/app/patrones/hyph-ca.pat.txt", 
                               If(idioma = "gl", "/app/patrones/hyph-gl.pat.txt", 
                               If(idioma = "eu", "/app/patrones/hyph-eu.pat.txt", 
                               "/app/patrones/hyph-es.pat.txt"))))

    renderer.RenderingOptions.CustomHyphenation = New CustomHyphenationDefinitions With {
        .PatternSource = fichero
    }
End Sub

Configuración Docker para despliegues en producción bajo LOPDGDD

Para entornos on-premise donde el acceso a internet está restringido —habitual en infraestructuras de ISV que procesan datos de facturación bajo LOPDGDD—, incluya los patrones en la imagen Docker:

FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base
WORKDIR /app

FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY ["MiServicioPdf.csproj", "."]
RUN dotnet restore
COPY . .
RUN dotnet build -c Release -o /app/build

FROM build AS publish
RUN dotnet publish -c Release -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .

# Fuentes para á, é, ñ, ¿, ¡ y Latin-1 Extended del castellano
RUN apt-get update && apt-get install -y \
    fonts-liberation fontconfig libgdiplus libc6-dev \
    && fc-cache -fv && rm -rf /var/lib/apt/lists/*

# Patrones de guionización para lenguas peninsulares
COPY hyph-es.pat.txt /app/patrones/
COPY hyph-es.hyp.txt /app/patrones/
COPY hyph-ca.pat.txt /app/patrones/
COPY hyph-gl.pat.txt /app/patrones/
COPY hyph-eu.pat.txt /app/patrones/

ENTRYPOINT ["dotnet", "MiServicioPdf.dll"]

Descargue los ficheros de patrones del repositorio tex-hyphen antes de construir la imagen.

Comportamiento ante errores y coherencia tipográfica en el archivo LOPDGDD

Los errores durante la carga del patrón —URL no accesible, fichero no encontrado, formato inválido— se registran en el log pero no lanzan excepciones. El renderizado continúa sin guionización en lugar de fallar.

Este fallo silencioso tiene implicaciones específicas para ISV bajo LOPDGDD: un documento archivado sin guionización difiere tipográficamente del documento original con guionización correcta. En auditorías donde se confrontan el documento emitido y el archivado —situación prevista por la LOPDGDD para datos de alto valor probatorio—, la discrepancia tipográfica puede generar preguntas sobre la integridad del archivo.

La práctica recomendada es validar los ficheros de patrones y confirmar su disponibilidad durante el arranque de la aplicación, antes de procesar ningún documento. Para entornos Docker bajo LOPDGDD, esto se traduce en un health-check que verifica la existencia de los ficheros en /app/patrones/ antes de que el servicio acepte solicitudes de renderizado.

IronPDF carga y compila los patrones en la primera llamada; las invocaciones posteriores reutilizan la caché. Para generación masiva de facturas VeriFactu bajo la Ley Crea y Crece (B2B desde 2027/2028), cargue los patrones en el arranque de la aplicación para evitar latencia en el primer renderizado de producción.

Para el soporte de caracteres del castellano en fuentes y tipografía, consulte la guía de gestión de fuentes para documentos en español. Para documentos PDF/A archivados bajo LOPDGDD, consulte la guía de PDF/A.