Saltar al contingut principal
Recepta número 41

Receptari · Capítol 10 · Sortida i integració

Anada i tornada d'un .postext en dues llengües

Un fulletó DL a doble cara desat en un fitxer .postext i compost de nou a partir dels seus bytes, amb les fonts, els dibuixos i les etiquetes que porta.

En aquesta pàgina
Nivell
Intermedi
Postext
Provada amb Postext 1.65.0
Requereix ≥ 1.25.0 · postext-pdf ≥ 1.25.0
Llicència
Actualitzada el 10 d’oct. del 2026
Codi MIT · Text CC BY 4.0
  • Mostra en castellà: encara no hi ha edició en català
  • Format 99 × 210 mm
  • 1 columna
  • DM Sans 9,4/13,4
  • DM Serif Display
  • Instrument Sans
  • 2 pàgines
  • Nivell
  • Postext 1.57.1
  • Compost en 64 ms
  • 178 línies de codi

En poques paraules

Un fulletó de dues cares d'un antic molí de marea, en anglès i en castellà. Ensenya a desar un document amb les seves fonts i imatges en un sol fitxer i a treure'n les mateixes pàgines.

Què compondràs

Les dues cares d'un fulletó DL de visita, de 99 × 210 mm, per a un molí de marea en una ria inventada. La portada és un sol dibuix: una roda de molí a la línia de l'aigua, amb la meitat superior sobre la sorra i la inferior pàl·lida sota el blau de l'aigua, el títol en DM Serif Display cursiva de 50 pt i una pestanya blava amb el codi de l'edició, ES o EN. El revers comença amb el molí en secció i continua amb el text en DM Sans justificada, l'horari en una taula amb la capçalera en blau, peus en Instrument Sans, un colofó i una franja blava amb la fundació que l'edita. Cada edició s'escriu en un fitxer .postext, i cada pàgina que veus es compon a partir dels bytes d'aquest fitxer, amb les fonts i els dibuixos que porta a dins.

Aquesta recepta respon a

  • Com obro un fitxer .postext i el pinto amb les seves pròpies fonts, imatges i configuració?
  • Com creo un paquet .postext des del codi per passar un document al Sandbox o a un altre programa?
  • Com publico el mateix llibre en dues llengües des d'un sol projecte?
  • Com aconsegueixo les etiquetes «Figura» i «Taula» en la llengua del meu document?

La resposta curta

script.js · línies 294–310al codi complet
// The writer: text, design, resources and every file they name, zipped. createBundle looks
// up each fileId (a drawing's svg.fileId, a face's variant fileId) in `files`.
const { bytes, warnings } = await createBundle({
  name: t({ en: 'The Tide Mill of Arenal', es: 'El molino de mareas de Arenal' }),
  locale: LANG, // one language per file; `localized` would add the other edition to it
  markdown, config: config(), resources,
  files: { ...drawings, ...faceFiles },
  thumbnail: { data: drawings['cover.svg'], mime: 'image/svg+xml' }, // the book's picture
});
if (warnings.length) console.warn(warnings); // what was left out, and why

// The reader has nothing but the bytes. Each fileId is now the file's path inside the zip:
// mill.svg is resources/mill.svg, and the faces sit under fonts/.
const bundle = await openBundle(bytes);
await loadBundleFonts(bundle); // one FontFace per face from the file, in place of loadFonts()
await registerBundleImages(bundle); // the drawings, for the canvas
const docs = buildBundle(bundle); // one VDTDocument per chapter: a leaflet has one

Ingredients

Tipografia
DM Sans, DM Serif Display, Instrument Sans (SIL OFL 1.1)
Recursos
Cap: totes les imatges es dibuixen en codi

Elaboració

#1 · Escriu l'edició i torna a llegir només els bytes

script.js · línies 294–310al codi complet
// The writer: text, design, resources and every file they name, zipped. createBundle looks
// up each fileId (a drawing's svg.fileId, a face's variant fileId) in `files`.
const { bytes, warnings } = await createBundle({
  name: t({ en: 'The Tide Mill of Arenal', es: 'El molino de mareas de Arenal' }),
  locale: LANG, // one language per file; `localized` would add the other edition to it
  markdown, config: config(), resources,
  files: { ...drawings, ...faceFiles },
  thumbnail: { data: drawings['cover.svg'], mime: 'image/svg+xml' }, // the book's picture
});
if (warnings.length) console.warn(warnings); // what was left out, and why

// The reader has nothing but the bytes. Each fileId is now the file's path inside the zip:
// mill.svg is resources/mill.svg, and the faces sit under fonts/.
const bundle = await openBundle(bytes);
await loadBundleFonts(bundle); // one FontFace per face from the file, in place of loadFonts()
await registerBundleImages(bundle); // the drawings, for the canvas
const docs = buildBundle(bundle); // one VDTDocument per chapter: a leaflet has one

createBundle comprimeix en un zip el capítol, la configuració, els recursos i tots els fitxers als quals fan referència, i openBundle no rep res més que aquests bytes. Les fonts surten de loadBundleFonts, els dibuixos de registerBundleImages i el disseny de bundle.config. Una font que no sigui a files surt amb la font de reserva del navegador, i un dibuix que falti es descarta amb un avís i la seva remissió s'imprimeix com a (?). Dins el zip, cada fileId passa a ser una ruta (mill.svg ara és resources/mill.svg), i els recursos i el customFonts que retorna openBundle ja fan servir els noms nous (obrir un paquet).

#2 · Posa les fonts dins el fitxer

script.js · línies 277–289al codi complet
const customFonts = Object.entries(FONTS).map(([name, specs]) => ({ name,
  variants: specs.map((spec) => ({ weight: parseInt(spec, 10), format: 'woff2',
    style: spec.endsWith('i') ? 'italic' : 'normal', fileId: `${fontsourceId(name)}-${spec}` })),
}));
// The bytes: Fontsource's static woff2 files, latin subset, which covers the Spanish text too.
const faceFiles = Object.fromEntries(await Promise.all(customFonts.flatMap(({ name, variants }) =>
  variants.map(async ({ weight, style, fileId }) => {
    const id = fontsourceId(name);
    const res = await fetch(`https://cdn.jsdelivr.net/npm/@fontsource/${id}@5/files/`
      + `${id}-latin-${weight}-${style}.woff2`);
    if (!res.ok) throw new Error(`Fontsource has no ${name} ${weight} ${style}`);
    return [fileId, new Uint8Array(await res.arrayBuffer())];
  }))));

Un paquet porta una font quan customFonts la declara i files en desa els bytes amb el fileId de la variant; createBundle desa la DM Sans 400 com a fonts/dm-sans-400-normal.woff2. El pen baixa de Fontsource els set woff2, però no en registra cap: loadBundleFonts afegeix a document.fonts les còpies del paquet abans que buildBundle mesuri una sola línia, i el PDF treu les seves fonts d'aquests mateixos set fitxers.

#3 · Anomena cada fitxer pel seu fileId

script.js · línies 234–267al codi complet
const svg = (id, w, h, altText, extra) => ({ id, typeId: 'figure', kind: 'svg', createdAt: 0,
  updatedAt: 0, altText, svg: { fileId: `${id}.svg`, width: w * 10, height: h * 10 }, ...extra });
const row = (...cells) => cells.map((content) => ({ content }));
const head = (...cells) => cells.map((content) => ({ content, isHeader: true }));
const resources = [
  svg('cover', PAGE.w, PAGE.h, t({ en: 'A mill wheel on the waterline, its lower half pale '
    + 'under the estuary', es: 'Una rueda de molino en la línea del agua, con la mitad '
    + 'inferior pálida bajo la ría' })),
  svg('mill', SECTION.w, SECTION.h, t({
    en: 'The mill in section: the pond at high level on the left, the mill house on the dam '
      + 'with its millstones, the horizontal wheel in the vaulted pit, and the estuary on the '
      + 'right below a dashed high-water line',
    es: 'El molino en sección: el estanque a nivel alto a la izquierda, la casa del molino sobre '
      + 'la presa con sus muelas, el rodezno en el cárcavo abovedado y la ría a la derecha, bajo '
      + 'una línea discontinua de pleamar' }), {
    placement: { position: 'here' },
    caption: t({ en: 'Two hours after high water: the pond turns the wheel, and the estuary '
      + 'has fallen below the dashed line.',
    es: 'Dos horas tras la pleamar: el estanque mueve el rodezno y la ría ha quedado por debajo '
      + 'de la línea discontinua.' }) }),
  { id: 'hours', typeId: 'table', kind: 'table', createdAt: 0, updatedAt: 0,
    placement: { position: 'here' },
    caption: t({ en: 'Opening hours. Last entry 45 minutes before closing.',
      es: 'Horario. Última entrada 45 minutos antes del cierre.' }),
    table: { model: { headerRowCount: 1, columnWidths: [1.55, 0.9, 1.55], rows: t({
      en: [head('Season', 'Days', 'Hours'),
        row('April–June', 'Tue–Sun', '10:00–14:00, 16:00–19:00'),
        row('July–August', 'Mon–Sun', '10:00–20:00'),
        row('September–March', 'Fri–Sun', '10:30–14:30')],
      es: [head('Temporada', 'Días', 'Horario'),
        row('Abril–junio', 'Mar.–dom.', '10:00–14:00 y 16:00–19:00'),
        row('Julio–agosto', 'Lun.–dom.', '10:00–20:00'),
        row('Septiembre–marzo', 'Vie.–dom.', '10:30–14:30')] }) } } },
];

Els dos dibuixos són SVG que genera el mateix pen i que es lliuren a files amb el svg.fileId del seu recurs; la taula són dades, així que viatja a preset.json amb el seu peu. La secció i la taula es col·loquen amb position: 'here': la secció al capdamunt del revers i l'horari sota el paràgraf que el cita. El fulletó fixa layout.inlineResourceGap: 'above', que deixa l'aire d'un recurs en línia només per sobre, i així el revers cap en una cara: el títol que segueix la secció porta el seu propi espai, i una línia :::space{lines=0.5} després de la taula deixa 3,7 mm sota el peu.

#4 · Mantén les etiquetes en la llengua del fitxer

script.js · línies 55–59al codi complet
  // Hyphenation patterns and the PDF's /Lang.
  locale: t({ en: 'en-us', es: 'es' }),
  // '{n}' numbers the figures 1, 2, 3: a leaflet has no chapters to number them by. Without
  // resourceTypes the reader builds Figure 1.1 or Figura 1.1, in the language of the file.
  resourceTypes: defaultResourceTypes(LANG).map((type) => ({ ...type, numberingTemplate: '{n}' })),

Qui obre un fitxer crea els tipus integrats en la llengua que aquest fitxer serveix: sense resourceTypes a la configuració, el fulletó en castellà imprimeix Figura 1.1 i Tabla 1.1 l'obri qui l'obri, també el Sandbox des de /en/sandbox. El fulletó escriu els tipus només pels números: '{n}' treu el número de capítol, que un fulletó de dues pàgines no necessita (tipus de recurs). La mateixa funció config() fixa locale, que tria els patrons de partició de mots del castellà (compuer-tas al revers) i la llengua que declara el PDF.

#5 · Lliura els mateixos bytes

script.js · línies 316–324al codi complet
const file = `tide-mill-${LANG}.postext`;
document.getElementById('pt-actions').append(Object.assign(document.createElement('a'), {
  href: URL.createObjectURL(new Blob([bytes], { type: 'application/zip' })), download: file,
  textContent: `Download ${file} · ${Math.round(bytes.length / 1024)} KB` }));
// The PDF embeds the faces the bundle carries, and draws the figures from its files.
offerPdf(() => renderToPdf(docs, {
  fontProvider: bundleFontProvider(bundle, { decodeWoff2: decompressWoff2 }),
  resourceBytes: bundleResourceBytes(bundle),
}), `${RECIPE}-${LANG}.pdf`);

L'enllaç ofereix els mateixos bytes des dels quals es van compondre les pàgines: 132 KB amb les fonts. En importar-lo al Sandbox (Llibres → Nou → Obrir un fitxer .postext…), el fitxer es converteix en un llibre en castellà o en anglès que porta com a imatge la roda de thumbnail. El PDF pren les seves fonts de bundleFontProvider, que retorna la del paquet més propera en gruix, amb el mateix estil si n'hi ha, i els seus dibuixos de bundleResourceBytes, així que no es baixa dues vegades cap font ni cap imatge (compondre i renderitzar un paquet).

#6 · Dibuixa la portada amb un sol títol

script.js · línies 28–50al codi complet
const at = (x, y, width, edge = 'top-left') => ({ anchor: { to: 'page', edge },
  offset: { x: mm(x), y: mm(y) }, size: { width: mm(width) } });
const text = (id, content, family, size, placement, look) => ({ kind: 'text', id, content,
  fontFamily: family, fontSize: pt(size), color: col('estuary'), placement, ...look });
const caps = { fontFamily: LABEL, fontWeight: 700, textTransform: 'uppercase',
  letterSpacing: pt(1.15) };
const [MEASURE, EDGE] = [PAGE.w - 2 * PAGE.side, 17]; // mm; EDGE: trim to kicker and facts
const cover = { id: 'cover', advancedDesign: { enabled: true, slot: { elements: [
  { kind: 'image', id: 'art', resourceId: 'cover', placement: { anchor: { to: 'page',
    edge: 'top-left' }, size: { width: mm(PAGE.w), height: mm(PAGE.h) } } },
  text('kicker', '{attr.kicker}', LABEL, 7.5, at(PAGE.side, EDGE, MEASURE), caps),
  // The language tab: the edition's code on a blue flap hanging from the top edge.
  text('edition', '{attr.edition}', LABEL, 8, { anchor: { to: 'page', edge: 'top-right' },
    offset: { x: mm(-PAGE.side) } }, { ...caps, color: col('foam'), box: {
    backgroundColor: col('estuary'), padding: { top: mm(8), right: mm(2.4), bottom: mm(2.2),
      left: mm(2.4) } } }),
  text('title', '{titleText}', DISPLAY, 50, at(PAGE.side - 0.8, 25, MEASURE + 2),
    { italic: true, lineHeight: 0.96 }), // 48 pt from line to line
  text('lead', '{attr.lead}', TEXT, 11, at(PAGE.side + 2, WATER + 50, MEASURE - 4),
    { color: col('foam'), italic: true, lineHeight: 1.4 }),
  text('facts', '{attr.facts}', LABEL, 7.5, at(PAGE.side, -EDGE, MEASURE, 'bottom-left'),
    { ...caps, color: col('sand') }),
] } } };

La portada és el disseny del títol de coberta: el dibuix ancorat a la pàgina a mida completa, el text del títol amb {titleText}, l'avanttítol, l'entradeta i la línia de dades, que surten dels seus atributs, i un text amb caixa per a la pestanya de la llengua. El nivell 1 dels títols porta span: 'page', així que el dibuix arriba a la vora inferior del paper. Si es queda a la columna, el disseny es talla al peu de la caixa de text: el dibuix acabaria 13 mm abans de la vora inferior.

La recepta completa

Sandbox
// ═══ Postext Cookbook · Nº 041 · .postext round trip in two languages ════════════
// https://postext.dev/en/cookbook/bundle-round-trip
// Code: MIT · Text: original (CC BY 4.0) · Drawings: generated in code (CC BY 4.0)
// Fonts: DM Sans, DM Serif Display, Instrument Sans (SIL OFL 1.1) · Needs postext ≥ 1.25.0
import { createBundle, openBundle, loadBundleFonts, registerBundleImages, buildBundle,
  bundleFontProvider, bundleResourceBytes, defaultResourceTypes, renderPageToCanvas }
  from 'https://esm.sh/postext';
import { renderToPdf, decompressWoff2 } from 'https://esm.sh/postext-pdf';

const LANG = 'es'; // @lang: the language of the sample document ('en' | 'es')
const RECIPE = 'bundle-round-trip';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
const palette = { ink: '#172130', muted: '#56606c', // text; the colophon
  estuary: '#25476a', mud: '#8a6f4d', // the one accent; the wheel's wood in the drawings
  sand: '#e9dcc4', foam: '#eef2f3', rule: '#c4ced6', paper: '#ffffff' };
// Each colour carries its hex and the palette entry it follows.
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
// The engine's defaults link to 'main-color': point it at the estuary blue.
const colorPalette = Object.entries({ ...palette, 'main-color': palette.estuary })
  .map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
const [TEXT, DISPLAY, LABEL] = ['DM Sans', 'DM Serif Display', 'Instrument Sans'];
const PAGE = { w: 99, h: 210, top: 12, bottom: 13, side: 10 }; // mm: a DL leaflet, both sides
const [BODY, LEAD] = [9.4, 13.4]; // pt
const WATER = 98; // mm from the top of the cover: where the sand ends and the estuary begins

// #region cover: the front of the leaflet, a heading drawn over one picture
const at = (x, y, width, edge = 'top-left') => ({ anchor: { to: 'page', edge },
  offset: { x: mm(x), y: mm(y) }, size: { width: mm(width) } });
const text = (id, content, family, size, placement, look) => ({ kind: 'text', id, content,
  fontFamily: family, fontSize: pt(size), color: col('estuary'), placement, ...look });
const caps = { fontFamily: LABEL, fontWeight: 700, textTransform: 'uppercase',
  letterSpacing: pt(1.15) };
const [MEASURE, EDGE] = [PAGE.w - 2 * PAGE.side, 17]; // mm; EDGE: trim to kicker and facts
const cover = { id: 'cover', advancedDesign: { enabled: true, slot: { elements: [
  { kind: 'image', id: 'art', resourceId: 'cover', placement: { anchor: { to: 'page',
    edge: 'top-left' }, size: { width: mm(PAGE.w), height: mm(PAGE.h) } } },
  text('kicker', '{attr.kicker}', LABEL, 7.5, at(PAGE.side, EDGE, MEASURE), caps),
  // The language tab: the edition's code on a blue flap hanging from the top edge.
  text('edition', '{attr.edition}', LABEL, 8, { anchor: { to: 'page', edge: 'top-right' },
    offset: { x: mm(-PAGE.side) } }, { ...caps, color: col('foam'), box: {
    backgroundColor: col('estuary'), padding: { top: mm(8), right: mm(2.4), bottom: mm(2.2),
      left: mm(2.4) } } }),
  text('title', '{titleText}', DISPLAY, 50, at(PAGE.side - 0.8, 25, MEASURE + 2),
    { italic: true, lineHeight: 0.96 }), // 48 pt from line to line
  text('lead', '{attr.lead}', TEXT, 11, at(PAGE.side + 2, WATER + 50, MEASURE - 4),
    { color: col('foam'), italic: true, lineHeight: 1.4 }),
  text('facts', '{attr.facts}', LABEL, 7.5, at(PAGE.side, -EDGE, MEASURE, 'bottom-left'),

L'script.js compost funciona tal com és: enganxa'l com a script de mòdul en qualsevol pàgina o obre la recepta a CodePen. Carpeta de la recepta a GitHub ↗ (s'obre en una pestanya nova)

Variants

#Llegeix un paquet bilingüe

La guia de Postext porta en un sol fitxer els seus capítols, la seva configuració i els seus peus en anglès i en castellà; { locale } tria l'edició, que s'obre com a dotze capítols en 48 pàgines en qualsevol de les dues llengües, mentre l'enllaç continua oferint el fitxer del fulletó i el botó del PDF compon la guia.

-const bundle = await openBundle(bytes);
+const guide = await fetch('https://postext.dev/bundles/postext-guide.postext');
+const bundle = await openBundle(await guide.arrayBuffer(), { locale: LANG });

#Numera les figures per capítol

Sense els tipus, qui obre el fitxer els crea en la seva llengua amb la numeració per defecte, i les figures compten des del títol de coberta: Figura 1.1 i Tabla 1.1 en l'edició castellana, Figure 1.1 i Table 1.1 en l'anglesa.

-  resourceTypes: defaultResourceTypes(LANG).map((type) => ({ ...type, numberingTemplate: '{n}' })),

Errors freqüents

  • Aquí cada edició és un fitxer propi. Per portar les dues llengües en un de sol, passa a createBundle un mapa localized (Paquets bilingües); openBundle(bytes, { locale }) llegeix llavors qualsevol de les dues edicions.

Crèdits

Text
Text original, CC BY 4.0
Fonts
DM Sans (SIL OFL 1.1) · DM Serif Display (SIL OFL 1.1) · Instrument Sans (SIL OFL 1.1)
SandboxPDF