Formatos de módulos de SWORD, MySword y e-Sword: en qué se equivoca la documentación

Respuesta corta: si estás creando un módulo bíblico, tres afirmaciones ampliamente repetidas son erróneas. e-Sword no tiene formato .bbl. Un módulo del Nuevo Testamento debe conservar la numeración de libros de la Biblia completa. Y un índice zText de SWORD cuenta ranuras, no versículos. Cada error genera un módulo que se instala limpiamente pero se lee mal, lo cual es la peor manera de equivocarse.

Escribimos generadores de módulos para SWORD, MySword y e-Sword en Go puro, sin herramientas externas, para publicar los módulos bíblicos gratuitos detrás de Tringine. Cada esquema y disposición de bytes a continuación se extrajo de módulos reales publicados usando un editor hexadecimal y sqlite3, no de un artículo técnico. Esto es todo lo que aprendimos, incluida la comprobación única que ahora ejecutamos en cada compilación porque leer el código no bastaba.

¿Por qué no existe ningún archivo .bbl para e-Sword?

Porque no existe. Al buscar el formato de módulos bíblicos de e-Sword aparece constantemente .bbl, pero .bbl es una extensión de bibliografía de LaTeX —por eso buscar una especificación siempre resulta infructuoso y confuso.

Los formatos reales son .bblx para e-Sword 9 y 10, donde el texto del versículo es RTF, y .bbli para la versión 11 y posteriores, donde el texto del versículo es HTML. Las versiones 11 a 13 leen ambos, por lo que distribuir solo .bblx cubre e-Sword de la 9 a la 13. Si vas a crear un solo formato, crea ese.

¿Por qué un módulo del Nuevo Testamento sigue numerando los libros del 40 al 66?

Porque los tres formatos direccionan los versículos respecto a una versificación fija —la lista canónica de libros, capítulos y número de versículos que un lector utiliza para encontrar un versículo, por defecto KJV— y la numeración es absoluta en lugar de relativa a lo que contiene tu edición. Renumerar un Nuevo Testamento del 1 al 27 sitúa a Mateo exactamente donde corresponde Génesis, y todo lo posterior se desplaza.

Confirmamos esto con dos módulos reales exclusivos del NT en lugar de fiarnos del razonamiento: ambos comienzan en el libro 40 y ambos establecen OT=0. El mismo principio se aplica dentro de un testamento: un libro que tu edición no incluya sigue ocupando sus ranuras, vacías. Si lo omites para ahorrar espacio, el lector mostrará el texto de Marcos bajo las referencias de Mateo, silenciosamente, para cada libro posterior al hueco.

¿Cuántos registros corresponden a un índice zText?

Este es el que corrompe silenciosamente un módulo, porque un índice con una longitud incorrecta sigue parseándose sin error.

Un testamento de SWORD consta de tres archivos. Todos en formato little-endian, medidos a partir de los módulos ASV y Byzantine de CrossWire:

La enumeración es donde se produce el error. Las ranuras se organizan así: la ranura 0 es el encabezado del módulo, la ranura 1 el encabezado del testamento, luego por libro un encabezado de libro, luego por capítulo un encabezado de capítulo, y luego una ranura por versículo. Por tanto, el número de registros es 2 + books + chapters + verses —no el número de versículos.

Para el Nuevo Testamento bajo la versificación KJV eso es 2 + 27 + 260 + 7,957 = 8.246 registros, de modo que nt.bzv mide exactamente 82.460 bytes. Para el Antiguo Testamento, 2 + 39 + 929 + 23,145 = 24.115 registros, o 241.150 bytes.

Esto se puede comprobar con un solo comando, que es la razón de dejarlo por escrito: los módulos ASV y Byzantine distribuidos tienen ambos un nt.bzv de exactamente 82.460 bytes. Si el tuyo difiere, tu enumeración es incorrecta, y lo descubrirás por un lector desconcertado en lugar de por un fallo de ejecución.

Otro detalle de diseño que conviene imitar: un módulo solo del NT sigue incluyendo un ot.bzv —a tamaño completo, todo ceros— con ot.bzs y ot.bzz de longitud cero. Eso es exactamente lo que hace, byte a byte, el módulo Byzantine distribuido.

¿Qué requieren realmente los formatos SQLite?

MySword (.bbl.mybible): page_size=32768, UTF-8, y el índice de la Biblia es UNIQUE. El texto del versículo utiliza pares de etiquetas estilo theWord, no HTML —las notas al pie son <RF>…<Rf>. Details.Language toma un código de tres letras, y qué tres letras usar no es obvio: ISO 639-2 tiene un código bibliográfico y uno terminológico para unas veinte lenguas, y los módulos publicados no siguen ninguno de forma consistente (los módulos en alemán y checo usan deu y ces; los de francés, albanés y griego usan fre, alb y gre; aproximadamente un tercio omite la columna). Resolvimos los nuestros abriendo módulos reales en lugar de leer el estándar: ambos módulos noruegos publicados llevan nor, así que el nuestro también. Donde no pudimos asignar un idioma con total certeza, seguimos escribiendo NULL en lugar de adivinar, porque una etiqueta de idioma incorrecta es peor que una ausente.

e-Sword (.bblx): page_size=1024, identificadores entre comillas simples, y el índice no es único. Hay dos trampas aquí. Details.Version es un INT que indica la generación del formato —2 para .bblx, 4 para .bbli— y no la versión de tu edición, que corresponde a Comments. Y tres módulos reales que examinamos discrepan sobre la propia codificación de la base de datos: uno UTF-16LE, dos UTF-8. Por lo tanto, no se puede confiar en que la codificación de la columna preserve un punto de código tamil o telugu.

La solución es escribir cada runa no ASCII como un escape RTF \uN?, con signo de 16 bits y pares sustitutos por encima del BMP. Es independiente de la codificación y es lo que hacen los módulos reales. Si vas a distribuir un sistema de escritura no latino para e-Sword, este es el detalle decisivo de que alguien pueda leerlo.

Los booleanos son 1/0 en ambos formatos SQLite. (.bbli utiliza el -1 de Delphi, lo cual es una buena razón para no emitir .bbli a la ligera).

Comprueba el .conf renderizado, no la estructura

Los metadatos son la parte de un módulo que lee un catálogo y que un tribunal podría leer, y es la parte a la que una suite de pruebas tiene menos probabilidades de prestar atención. La nuestra no lo hizo al principio: un campo de licencia que era correcto en la estructura de Go se renderizó como otra cosa en el .conf, y lo detectamos leyendo el archivo, no ejecutando las pruebas. Se corrigió y todos los módulos se recompilaron el mismo día; los archivos disponibles hoy en nuestros repositorios indican Copyright=Public Domain para los textos en tamil de 1868 y telugu de 1880, no nombran a ningún titular de derechos de autor y acreditan a Publifye solo como preparador de la edición en TextSource.

Hay que mantener separadas dos afirmaciones en ese archivo. La licencia del texto es un hecho propio de la traducción y no te corresponde a ti elegirla: una Biblia de dominio público sigue siendo de dominio público en tu módulo, y ninguna línea de DistributionNotes puede restringirla. Los términos de tu servicio de distribución —registro, registro de actividad— rigen tus servidores y nada más. Si fusionas ambos, o bien restringes lo que es libre o liberas lo que no lo es.

La prueba que lo supervisa ahora realiza aserciones sobre el archivo .conf renderizado. Falla en el instante en que a un texto de dominio público se le asigna un titular de derechos o una nota restrictiva, e igualmente en el momento en que nuestra propia traducción se degrada en silencio a dominio público. En ambas direcciones, porque un error permisivo sigue siendo un error. Cualquiera que distribuya módulos bíblicos debería leer el archivo que publica, no el código que lo generó.

Cómo lo verificamos

No limitándonos a releer la especificación:

• Se compiló un módulo completo del Nuevo Testamento —7.957 versículos— y se leyó de nuevo con la propia herramienta diatheke de libsword dentro de un contenedor Debian. Aparece en modulelist, resuelve Mat 1:1, Juan 3:16, 1 Cor 13:13 y Apoc 22:21 en sus direcciones correctas, no devuelve nada para Génesis 1:1 como corresponde a un módulo exclusivo del NT, y realiza búsquedas correctamente.
• La misma comprobación en un módulo de la Biblia completa, 31.102 versículos entre ambos testamentos: Génesis 1:1 y Salmo 119:176 leídos en tamil y Apocalipsis 22:21 en telugu, cada uno en su propia dirección, con un ot.bzv real de exactamente 241.150 bytes junto al nt.bzv de 82.460 bytes.
• xmllint valida que el OSIS está bien formado, con la declaración de derechos presente.
• Los archivos SQLite se abren con sqlite3 exactamente con el recuento de filas previsto en la planificación: 7.957 filas para los libros 40 a 66 en el módulo del Nuevo Testamento, 31.102 para los libros 1 a 66 en el de la Biblia completa.

Esa verificación directa permitió detectar dos errores propios que la suite de pruebas no había detectado. Esa proporción es habitual y es un argumento a favor de probar contra el lector real y no contra la propia comprensión que uno tiene de él.

Preguntas frecuentes

¿Qué formato debería compilar primero para e-Sword?

.bblx. Las versiones 11 a 13 lo leen junto con el más reciente .bbli, por lo que un solo archivo cubre e-Sword del 9 al 13.

¿Por qué mi módulo muestra el texto del libro equivocado?

Casi siempre se debe a la enumeración. O bien se renumeraron los libros del 1 al 27 para un Nuevo Testamento, o bien se omitió un libro no incluido en la edición en lugar de dejarlo como ranuras vacías. Comprueba primero la longitud en bytes de tu nt.bzv comparándola con 82.460.

¿Necesito un archivo ot en un módulo del Nuevo Testamento?

Sí. Un ot.bzv de tamaño completo y todo ceros, con ot.bzs y ot.bzz de longitud cero.

¿Cómo incluyo texto en tamil, telugu u otro alfabeto no latino en .bblx?

Escribe cada runa no ASCII como un escape RTF \uN? en lugar de depender de la codificación de la columna, que es inconsistente entre los módulos reales.

¿Puedo utilizar vuestros módulos?

Sí. Los de dominio público no tienen ninguna restricción por nuestra parte: la edición es obra nuestra, las palabras pertenecen a todos. Nuestra propia traducción, Bibelen Anno 2026, es gratuita para su distribución no comercial.

---

¿Buscas los módulos en vez del formato? En Cómo instalar módulos bíblicos gratuitos en AndBible, MySword y e-Sword se explica paso a paso para cada aplicación. Cada módulo en tringine.publifye.com/modules se distribuye con su código fuente OSIS para que puedas recompilarlo o comprobar nuestro trabajo. La descarga requiere una cuenta gratuita, lo cual es una condición de nuestro servicio y no una reivindicación sobre los textos —la página de licencia lo indica claramente.

Escrito por Jørn André Halseth, fundador de Publifye AS —diez años publicando Biblias y desarrollando la tecnología con la que se imprimen, y autor de Tringine, Darash, Junifye y Lexifye. Acerca de · Contacto