Telar v1.3.0

Telar v1.3.0

i18n hygiene release. Telar has shipped English and Spanish language packs for several versions, but a number of layouts and includes still carried hardcoded English literals. This release wires them up so sites with telar_language: es render in Spanish throughout. It also refreshes the default content of the welcome and "About" pages to reflect what Telar can do today (multimedia, the Telar Compositor, narrative exhibitions and small digital collections), and introduces a sister-file convention so site owners can localize their own user pages.

Versión en español abajo

Fixed

Homepage headings rendered in English for Spanish-language sites
_layouts/index.html now resolves the stories and objects headings with a fallback chain: page.X | default: lang.pages.X | default: "<English literal>". Previously the layout skipped the language pack entirely when no page.* override was present, and the template index.md shipped with English page-overrides — so any site with telar_language: es saw English headings for no apparent reason.

Empty-state messages and IIIF URL warning hardcoded in English
_layouts/index.html, _layouts/objects-index.html, _layouts/glossary-index.html and _includes/iiif-url-warning.html now reference the lang.empty_states.* and lang.errors.iiif_mismatch.* keys that already existed in both language packs but were never used. Spanish-language sites now show the "no content yet" guidance and the IIIF mismatch troubleshooting modal in Spanish.

Thumbnail load fallback strings hardcoded in English
_layouts/index.html and _layouts/objects-index.html now inject TelarI18n and TelarI18nIIIF constants from the language pack, so the strings shown when a thumbnail fails to load ("Failed to load", "No image") now appear in the active language.

Empty-state messages pointed at the wrong content directory
The guidance read "add files to _stories/" / _objects/ / _glossary/. Those directories are generated by the build; the actual user-content paths are under telar-content/spreadsheets/ and telar-content/texts/glossary/. The lang values had the correct paths — wiring them up fixed both the i18n bug and the misleading guidance.

Migration script language detection for Spanish sites
BaseMigration._detect_language() looked for telar_language nested under the telar: block in _config.yml, but the key has always been top-level. Every Spanish-language site silently fell through to the English default for migration manual steps. The base class now reads the correct top-level key, so Spanish sites get Spanish manual steps in UPGRADE_SUMMARY.md and (in v1.3.0 specifically) the conditional acerca.md creation guard now sees the correct language.

Added

Sister-file localization for user pages (telar-content/texts/pages/)
scripts/generate_collections.py now recognizes markdown files with frontmatter localized_for: <canonical>.md and language: <code>. When site.telar_language matches the sister's language, the build uses the sister's content but writes the output under the canonical filename — so /about/ resolves to the right language without duplicating URLs. The v1.3.0 template ships with acerca.md as the Spanish sister of about.md; you can add siblings for other languages following the same convention.

New key lang.index_page.welcome carrying the homepage welcome content as a multi-line markdown block, in EN and ES. The default index.md body now renders {{ lang.index_page.welcome | markdownify }} with a bilingual EN/ES override comment that explains how site owners replace it with their own content.

New key lang.pages.glossary_intro for the glossary page intro sentence, with EN and ES values.

Two added keys in lang.errors.iiif_mismatch.* (local_fix_check_config and local_fix_run_with_note) that were missing from the IIIF warning's local-development fallback section.

Migration script v121_to_v130.py and matching migration.json manifest
Conditional content cleanup: removes the three stale index.md frontmatter keys and replaces user-content bodies (welcome, glossary, objects, About) with the v1.3.0 lang-key templates only when a SHA-256 hash check confirms the file is byte-for-byte identical to the v1.2.1 default. Any user customization — even a whitespace-only edit — preserves the file untouched. For sites with telar_language: es whose about.md is unchanged from the v1.2.1 default, the migration also creates acerca.md (the new Spanish sister) so the site immediately renders Spanish content at /about/. Sites with a customised about.md skip this — otherwise the new sister file would shadow the customisation at build time.

Changed

Default content of the welcome and About pages refreshed
Both pages now describe Telar as it is today: they name both modes (scroll-driven narrative exhibitions and publishing small digital collections), name the content types they weave (IIIF images, video, audio, narrative text, contextual layers), present the three setup paths (Telar Compositor, GitHub template + Google Sheets, hands-on local) and link to the Telar Compositor. The previous content described Telar as it stood around v0.7 (single-mode, GitHub template only, no audio/video, no Compositor).

pages/glossary.md, pages/objects.md, index.md rewritten to render via lang keys rather than hardcoded English. Each file carries a bilingual EN/ES HTML override comment explaining how to replace the default with custom content. The pattern uses {% assign lang = site.data.languages[site.telar_language] | default: site.data.languages.en %} at the top of the page (the layout's own lang assignment isn't visible to the page body, which Jekyll renders before wrapping it in the layout).

telar-content/texts/pages/about.md rewritten with the refreshed copy and a sentence in the Customize alert documenting the sister-file convention for site owners adding additional languages.

Removed

Stale lang.pages.home_title key removed from en.yml and es.yml. Defined since v1.0.0-beta but never referenced from any layout, include, or script.

Migration

Automated upgrade from v1.2.1:

1. Go to your repository's Actions tab
2. Select the Upgrade Telar workflow
3. Click Run workflow
4. Review the upgrade issue and merge the pull request

Or run locally: python3 scripts/upgrade.py

The script verifies a SHA-256 hash of each user-content file before touching it. If you customized your welcome page, About page, glossary intro or objects intro, those files are preserved unchanged. For Spanish-language sites with an unchanged About page, the migration also creates acerca.md automatically so /about/ immediately renders the new Spanish content. If you customised about.md, the migration leaves it alone and does NOT create acerca.md (which would otherwise shadow your customisation).

Migration script: scripts/migrations/v121_to_v130.py

Documentation

• Documentation: https://telar.org/docs
• Example Site: https://ampl.clair.ucsb.edu/telar
• Report Issues: https://github.com/UCSB-AMPLab/telar/issues

Acknowledgments

Telar is developed by Adelaida Ávila, Juan Cobo Betancourt, Natalie Cobo, Santiago Muñoz, and students and scholars at the UCSB Archives, Memory, and Preservation Lab, the UT Archives, Mapping, and Pedagogy Lab, and Neogranadina.

We gratefully acknowledge the support of the Caribbean Digital Scholarship Collective, the Center for Innovative Teaching, Research, and Learning (CITRAL) at the University of California, Santa Barbara, the UCSB Library, the Routes of Enslavement in the Americas University of California MRPI, and the Department of History of The University of Texas at Austin.

---

Español

Versión de limpieza i18n. Telar tenía paquetes de idioma para inglés y español desde hace varias versiones, pero algunos layouts e includes seguían con texto literal en inglés. Esta versión los cablea para que los sitios con telar_language: es muestren todo en español. Además: actualiza el contenido por defecto de las páginas de bienvenida y "Acerca de" para reflejar lo que Telar puede hacer hoy (multimedia, Compositor, exhibiciones narrativas y colecciones digitales), e introduce una convención de archivos hermanos para que cualquiera pueda localizar sus propias páginas.

Corregido

Encabezados de la página de inicio en inglés para sitios en español
El layout _layouts/index.html ahora resuelve los encabezados de historias y objetos con fallback: page.X | default: lang.pages.X | default: "<texto en inglés>". Antes se saltaba el paquete de idioma cuando no había un page.* override, y la plantilla index.md traía esos overrides en inglés de fábrica — así que cualquier sitio con telar_language: es veía los encabezados en inglés sin razón aparente.

Mensajes de "vacío" y alerta de IIIF en inglés
_layouts/index.html, _layouts/objects-index.html, _layouts/glossary-index.html y _includes/iiif-url-warning.html ahora referencian las claves lang.empty_states.* y lang.errors.iiif_mismatch.* que ya existían en ambos paquetes de idioma pero que nunca se usaban. Los sitios en español ahora muestran las guías de "no hay contenido todavía" y la alerta de IIIF en español.

Textos de carga de miniaturas en inglés
_layouts/index.html y _layouts/objects-index.html ahora inyectan constantes TelarI18n y TelarI18nIIIF desde el paquete de idioma, así que los textos que aparecen cuando una miniatura no carga ("Failed to load", "No image") ahora salen en el idioma activo.

Mensajes de "vacío" que apuntaban al directorio equivocado
La guía decía "agrega archivos en _stories/" / _objects/ / _glossary/. Esos directorios son generados por el build; las rutas reales para el contenido de los usuarios están bajo telar-content/spreadsheets/ y telar-content/texts/glossary/. Las claves del paquete de idioma tenían la ruta correcta — cablearlas arregló a la vez la i18n y la guía equivocada.

Detección de idioma en los scripts de migración
BaseMigration._detect_language() buscaba la clave telar_language anidada bajo el bloque telar: de _config.yml, pero esa clave siempre estuvo en el primer nivel. Cualquier sitio en español caía silenciosamente al valor por defecto en inglés para los pasos manuales de la migración. La clase base ahora lee la clave correcta del primer nivel, así que los sitios en español ven los pasos manuales en español en UPGRADE_SUMMARY.md y (en v1.3.0 específicamente) la verificación que decide si crear acerca.md ya ve el idioma correcto.

Agregado

Localización por archivos hermanos para páginas de usuario (telar-content/texts/pages/)
scripts/generate_collections.py ahora reconoce archivos markdown con frontmatter localized_for: <canónico>.md y language: <código>. Cuando site.telar_language coincide con el language del hermano, el build usa el contenido del hermano pero escribe la salida bajo el nombre del archivo canónico — así /about/ resuelve al idioma correcto sin duplicar URLs. La plantilla v1.3.0 incluye acerca.md como hermano en español de about.md; puedes agregar más hermanos para otros idiomas siguiendo la misma convención.

Nueva clave lang.index_page.welcome con el contenido de bienvenida de la home como bloque markdown multilínea, en EN y ES. El cuerpo por defecto de index.md ahora renderea {{ lang.index_page.welcome | markdownify }} con un comentario bilingüe EN/ES que le explica al dueño del sitio cómo reemplazarlo con contenido propio.

Nueva clave lang.pages.glossary_intro para la frase introductoria de la página de glosario, con valores en EN y ES.

Dos claves agregadas en lang.errors.iiif_mismatch.* (local_fix_check_config y local_fix_run_with_note) que faltaban para completar la sección de fallback de desarrollo local de la alerta de IIIF.

Script de migración v121_to_v130.py y manifiesto migration.json
Limpieza de contenido condicional: quita las tres claves obsoletas del frontmatter de index.md y reemplaza los cuerpos de los archivos de contenido (bienvenida, glosario, objetos, "Acerca de") con las plantillas de v1.3.0 basadas en lang keys, solo cuando un hash SHA-256 confirma que el archivo es byte-por-byte idéntico al default de v1.2.1. Cualquier personalización — incluso un cambio de espacios en blanco — preserva el archivo intacto. Para sitios con telar_language: es cuyo about.md no se haya modificado desde el default de v1.2.1, la migración también crea acerca.md (el nuevo archivo hermano en español) para que el sitio renderee contenido en español en /about/ de inmediato. Los sitios con un about.md personalizado se saltan este paso — si no, el nuevo archivo hermano taparía la personalización al construir el sitio.

Cambiado

Contenido por defecto de la bienvenida y la página "Acerca de"
Ambas páginas ahora describen Telar como es hoy: nombran sus dos modos (exhibiciones narrativas con desplazamiento y publicación de pequeñas colecciones digitales), nombran los tipos de contenido que combinan (imágenes IIIF, video, audio, texto narrativo, capas de contexto), presentan las tres rutas para crear un sitio (Telar Compositor, plantilla de GitHub + Google Sheets, manual local) y enlazan al Telar Compositor. El contenido anterior describía Telar de la época de v0.7 (un solo modo, solo plantilla de GitHub, sin audio/video, sin Compositor).

pages/glossary.md, pages/objects.md, index.md reescritos para renderear vía lang keys en lugar de inglés literal. Cada archivo lleva un comentario bilingüe EN/ES en HTML explicando cómo reemplazar el default por contenido propio. El patrón usa {% assign lang = site.data.languages[site.telar_language] | default: site.data.languages.en %} arriba de la página (la asignación de lang que hace el layout no es visible para el cuerpo de la página, que Jekyll renderea antes de envolverlo en el layout).

telar-content/texts/pages/about.md reescrito con el contenido actualizado y una frase nueva en la alerta de personalización que documenta la convención de archivos hermanos para quienes quieran agregar más idiomas.

Quitado

Clave lang.pages.home_title quitada de en.yml y es.yml. Estaba definida desde v1.0.0-beta pero nunca se referenciaba desde ningún layout, include o script.

Migración

Actualización automática desde v1.2.1:

1. Ve a la pestaña Actions de tu repositorio
2. Selecciona el flujo de trabajo Upgrade Telar
3. Haz clic en Run workflow
4. Revisa el issue de actualización y fusiona el pull request

O ejecútala localmente: python3 scripts/upgrade.py

El script verifica un hash SHA-256 de cada archivo antes de tocarlo. Si personalizaste tu página de bienvenida, "Acerca de", glosario o introducción de objetos, esos archivos se preservan sin cambios. Para sitios en español cuya página "Acerca de" no esté personalizada, la migración crea acerca.md automáticamente para que /about/ muestre el contenido nuevo en español de inmediato. Si personalizaste about.md, la migración no lo toca y tampoco crea acerca.md (que de otro modo taparía tu personalización).

Script de migración: scripts/migrations/v121_to_v130.py

Documentación

• Documentación: https://telar.org/docs
• Sitio de demostración: https://ampl.clair.ucsb.edu/telar
• Reportar problemas: https://github.com/UCSB-AMPLab/telar/issues

Agradecimientos

Telar es desarrollado por Adelaida Ávila, Juan Cobo Betancourt, Natalie Cobo, Santiago Muñoz, y estudiantes e investigadores del UCSB Archives, Memory, and Preservation Lab, el UT Archives, Mapping, and Pedagogy Lab, y Neogranadina.

Agradecemos el apoyo del Caribbean Digital Scholarship Collective, el Center for Innovative Teaching, Research, and Learning (CITRAL) de la University of California, Santa Barbara, la UCSB Library, el Routes of Enslavement in the Americas University of California MRPI, y el Departamento de Historia de la Universidad de Texas en Austin.