WeasyPrint CLI converts carefully prepared HTML and CSS into PDFs, making it useful for multilingual manuals, translated reports, accessible information sheets and print-ready documentation. If you are searching for a WeasyPrint HTML-to-PDF tutorial for translated documents, the essential questions are how to preserve the correct language, keep page layout stable, choose fonts that support every script, and verify the resulting PDF rather than trusting a successful command alone.
A translated PDF may contain every correct sentence and still fail its readers. Page breaks can separate a warning from its explanation, a font can omit a character, a bidirectional paragraph can display numbers confusingly, and a table can extend past the printable page. This practical guide explains WeasyPrint command-line workflow, CSS paged media, Unicode, source safety, document metadata, visual proofing and accessibility review for publishers working across countries and languages.
The reliable starting procedure is to freeze an approved source revision, create one language-specific HTML document, make its language and reading direction explicit, test a short sample with representative scripts, render the PDF using a controlled stylesheet, and inspect the actual pages and extracted text. The checks below distinguish what WeasyPrint can render from what a translator, editor, accessibility specialist or distribution owner must still decide.
At a glance: the production route
- Confirm the authorized translation, exact target locale and review owner.
- Use tested fonts and an explicitly versioned print stylesheet.
- Render a short specimen before the complete document.
- Inspect the visible PDF, navigation, text extraction and independent conformance checks.
- Release the inspected artifact, then archive its source and build details.
Start with a reproducible command
weasyprint --version
weasyprint --help
weasyprint translated.html translated-review.pdf
weasyprint translated.html translated-review.pdf -s print.cssA minimum print stylesheet might contain @page { size: A4; margin: 18mm; } and a body font stack chosen for the writing systems in the translation. Treat these as examples, not universal specifications. Some newer commands and output-profile switches are version-dependent: read the help on the installed release before using them.
1. Scope the conversion job
Rendering is a final publishing step rather than a substitute for translation or copyediting. Decide which approved target-language edition belongs in the output before making a PDF. In a multilingual publishing project this is not a cosmetic detail: a reader must be able to act on the actual translated meaning, while the publisher must be able to explain how the finished file came to exist.
Example. A health notice translated into French may have a matching Spanish appendix that is not yet approved; automatically including the appendix would publish an unfinished language version. This is worth testing with a real sample rather than extrapolating from the English source, because language-specific length, fonts and structure can change the presentation even when the translation itself is accurate.
What to do. Record source revision, target language, approval owner, expected page format and delivery audience before running the command. Keep the decision visible to an editor and distinguish a layout correction from an unauthorized alteration to the translation. If the underlying text needs rewriting, return that decision to the language owner rather than disguising it with styling.
What passes. The manifest and finished PDF agree on language, edition and actual contents. Check the representative page and a second edge case, not only the most attractive page. A useful release note records the observed outcome, the file version and any deliberate exception.
Failure to avoid. A technically valid PDF can still be an unauthorized edition. The practical test is whether another reader could independently identify the same problem and confirm its resolution. A successful render alone cannot answer that question.
2. Inspect command availability
Different installed WeasyPrint versions can support different flags and PDF variants; copying a command from an unrelated operating system is not a guarantee of identical results. In a multilingual publishing project this is not a cosmetic detail: a reader must be able to act on the actual translated meaning, while the publisher must be able to explain how the finished file came to exist.
Example. A release machine reports a different set of PDF/A options from a developer laptop after a package update. This is worth testing with a real sample rather than extrapolating from the English source, because language-specific length, fonts and structure can change the presentation even when the translation itself is accurate.
What to do. Run weasyprint –version, weasyprint –help and, where necessary, check the package release notes before choosing options. Keep the decision visible to an editor and distinguish a layout correction from an unauthorized alteration to the translation. If the underlying text needs rewriting, return that decision to the language owner rather than disguising it with styling.
What passes. The build log records the renderer version and the parameters actually accepted. Check the representative page and a second edge case, not only the most attractive page. A useful release note records the observed outcome, the file version and any deliberate exception.
Failure to avoid. Silently changing a requested output standard to make a command succeed conceals a release problem. The practical test is whether another reader could independently identify the same problem and confirm its resolution. A successful render alone cannot answer that question.
3. Use an isolated working directory
A dedicated working copy prevents accidental overwriting of source translations, review proofs or other clients’ deliverables. File names should identify edition and language. In a multilingual publishing project this is not a cosmetic detail: a reader must be able to act on the actual translated meaning, while the publisher must be able to explain how the finished file came to exist.
Example. Two operators both save report.pdf in a shared folder, and the second export replaces the first even though the languages differ. This is worth testing with a real sample rather than extrapolating from the English source, because language-specific length, fonts and structure can change the presentation even when the translation itself is accurate.
What to do. Keep source, translated HTML, styles, images, proofs and final releases in separate named folders and use unique output paths. Keep the decision visible to an editor and distinguish a layout correction from an unauthorized alteration to the translation. If the underlying text needs rewriting, return that decision to the language owner rather than disguising it with styling.
What passes. A reviewer can identify the source and rendered artifact without guessing from modification times. Check the representative page and a second edge case, not only the most attractive page. A useful release note records the observed outcome, the file version and any deliberate exception.
Failure to avoid. Never render over the sole authoritative input file. The practical test is whether another reader could independently identify the same problem and confirm its resolution. A successful render alone cannot answer that question.
4. Run a minimal local render
Start with a reproducible short command, then add styling and PDF conformance options only when the basic text output is right. In a multilingual publishing project this is not a cosmetic detail: a reader must be able to act on the actual translated meaning, while the publisher must be able to explain how the finished file came to exist.
Example. A two-page localized leaflet fails because a referenced stylesheet is missing, not because its Arabic text is incorrect. This is worth testing with a real sample rather than extrapolating from the English source, because language-specific length, fonts and structure can change the presentation even when the translation itself is accurate.
What to do. Use weasyprint translated.html translated-review.pdf, then inspect any warnings and the rendered pages. Keep the decision visible to an editor and distinguish a layout correction from an unauthorized alteration to the translation. If the underlying text needs rewriting, return that decision to the language owner rather than disguising it with styling.
What passes. An output PDF opens and its visible text agrees with the approved HTML. Check the representative page and a second edge case, not only the most attractive page. A useful release note records the observed outcome, the file version and any deliberate exception.
Failure to avoid. A zero exit code proves only that this rendering attempt completed. The practical test is whether another reader could independently identify the same problem and confirm its resolution. A successful render alone cannot answer that question.
5. Apply a controlled stylesheet
The -s option allows an additional stylesheet. A print stylesheet should be reviewed as part of the publication source, because CSS changes readers’ perception of hierarchy. In a multilingual publishing project this is not a cosmetic detail: a reader must be able to act on the actual translated meaning, while the publisher must be able to explain how the finished file came to exist.
Example. A translator expands a heading; the screen layout looks fine, while the PDF inherits a screen-only narrow column with severe wrapping. This is worth testing with a real sample rather than extrapolating from the English source, because language-specific length, fonts and structure can change the presentation even when the translation itself is accurate.
What to do. Run weasyprint translated.html translated-review.pdf -s print.css; document the stylesheet revision and review the cascade. Keep the decision visible to an editor and distinguish a layout correction from an unauthorized alteration to the translation. If the underlying text needs rewriting, return that decision to the language owner rather than disguising it with styling.
What passes. Headings, paragraphs, figures and tables retain an intentional print hierarchy. Check the representative page and a second edge case, not only the most attractive page. A useful release note records the observed outcome, the file version and any deliberate exception.
Failure to avoid. Do not use emergency global font-size reductions to make an entire translation fit. The practical test is whether another reader could independently identify the same problem and confirm its resolution. A successful render alone cannot answer that question.
6. Set page size and margins
CSS @page governs the paper geometry, but the correct size depends on local print systems, reader needs and contractual requirements. In a multilingual publishing project this is not a cosmetic detail: a reader must be able to act on the actual translated meaning, while the publisher must be able to explain how the finished file came to exist.
Example. An A4 government information sheet gets exported in Letter format, so printers scale it and move important footer text. This is worth testing with a real sample rather than extrapolating from the English source, because language-specific length, fonts and structure can change the presentation even when the translation itself is accurate.
What to do. Set @page size and margin intentionally, for example @page { size: A4; margin: 18mm; }, and test printed or measured output. Keep the decision visible to an editor and distinguish a layout correction from an unauthorized alteration to the translation. If the underlying text needs rewriting, return that decision to the language owner rather than disguising it with styling.
What passes. Page dimensions, margins and bleed assumptions match the specification. Check the representative page and a second edge case, not only the most attractive page. A useful release note records the observed outcome, the file version and any deliberate exception.
Failure to avoid. A visually plausible page on a laptop may be wrong for the production printer. The practical test is whether another reader could independently identify the same problem and confirm its resolution. A successful render alone cannot answer that question.
7. Declare document language
HTML lang values give assistive technologies and processors crucial language context and help teams distinguish translated versions. In a multilingual publishing project this is not a cosmetic detail: a reader must be able to act on the actual translated meaning, while the publisher must be able to explain how the finished file came to exist.
Example. A Japanese report is produced from an English template retaining lang=en on its root element. This is worth testing with a real sample rather than extrapolating from the English source, because language-specific length, fonts and structure can change the presentation even when the translation itself is accurate.
What to do. Set html lang to a suitable BCP 47 tag for the actual document, and mark genuinely mixed-language spans separately. Keep the decision visible to an editor and distinguish a layout correction from an unauthorized alteration to the translation. If the underlying text needs rewriting, return that decision to the language owner rather than disguising it with styling.
What passes. Language metadata and on-page text describe the same edition. Check the representative page and a second edge case, not only the most attractive page. A useful release note records the observed outcome, the file version and any deliberate exception.
Failure to avoid. A locale tag is not a translation; it must never mask English placeholders. The practical test is whether another reader could independently identify the same problem and confirm its resolution. A successful render alone cannot answer that question.
8. Review writing direction
Right-to-left languages require more than aligning a paragraph to the right. Direction interacts with numbers, punctuation, URLs and embedded left-to-right phrases. In a multilingual publishing project this is not a cosmetic detail: a reader must be able to act on the actual translated meaning, while the publisher must be able to explain how the finished file came to exist.
Example. An Arabic invoice contains an English product identifier and a date; careless direction styling changes visual grouping. This is worth testing with a real sample rather than extrapolating from the English source, because language-specific length, fonts and structure can change the presentation even when the translation itself is accurate.
What to do. Mark direction semantically using dir where appropriate and review representative mixed-script passages with native-language readers. Keep the decision visible to an editor and distinguish a layout correction from an unauthorized alteration to the translation. If the underlying text needs rewriting, return that decision to the language owner rather than disguising it with styling.
What passes. Meaning and order remain clear in the rendered line, not merely in HTML source order. Check the representative page and a second edge case, not only the most attractive page. A useful release note records the observed outcome, the file version and any deliberate exception.
Failure to avoid. Manual insertion of directional controls throughout a file can create hard-to-debug inconsistencies. The practical test is whether another reader could independently identify the same problem and confirm its resolution. A successful render alone cannot answer that question.
9. Choose multilingual fonts
Unicode text needs fonts with actual glyph and shaping support. Font family names alone do not guarantee that every character will render correctly. In a multilingual publishing project this is not a cosmetic detail: a reader must be able to act on the actual translated meaning, while the publisher must be able to explain how the finished file came to exist.
Example. A PDF appears fine in Latin characters but displays tofu boxes in Thai captions or Devanagari labels. This is worth testing with a real sample rather than extrapolating from the English source, because language-specific length, fonts and structure can change the presentation even when the translation itself is accurate.
What to do. Identify the required writing systems and license-permitted fonts; define tested font families and fallback behavior in CSS. Keep the decision visible to an editor and distinguish a layout correction from an unauthorized alteration to the translation. If the underlying text needs rewriting, return that decision to the language owner rather than disguising it with styling.
What passes. Check every script in a rendered PDF and use a font inventory tool when font embedding matters. Check the representative page and a second edge case, not only the most attractive page. A useful release note records the observed outcome, the file version and any deliberate exception.
Failure to avoid. A font substitute with plausible shapes may still be typographically or linguistically unsuitable. The practical test is whether another reader could independently identify the same problem and confirm its resolution. A successful render alone cannot answer that question.
10. Test font-face asset paths
CSS @font-face is helpful for consistent release builds, but relative URLs and remote retrieval policies can make a render environment-dependent. In a multilingual publishing project this is not a cosmetic detail: a reader must be able to act on the actual translated meaning, while the publisher must be able to explain how the finished file came to exist.
Example. A CI runner has no access to a font server and falls back to an unrelated typeface with wider metrics. This is worth testing with a real sample rather than extrapolating from the English source, because language-specific length, fonts and structure can change the presentation even when the translation itself is accurate.
What to do. Bundle legally usable font assets with the release and verify CSS URLs relative to the input document and stylesheet. Keep the decision visible to an editor and distinguish a layout correction from an unauthorized alteration to the translation. If the underlying text needs rewriting, return that decision to the language owner rather than disguising it with styling.
What passes. The same source renders with the same intended family on a clean test machine. Check the representative page and a second edge case, not only the most attractive page. A useful release note records the observed outcome, the file version and any deliberate exception.
Failure to avoid. Avoid assuming an installed workstation font exists on a remote build server. The practical test is whether another reader could independently identify the same problem and confirm its resolution. A successful render alone cannot answer that question.
11. Preserve diacritics and combining marks
Many languages distinguish words using marks that can sit above, below or beside letters. Rendering can look almost correct while the marks are clipped. In a multilingual publishing project this is not a cosmetic detail: a reader must be able to act on the actual translated meaning, while the publisher must be able to explain how the finished file came to exist.
Example. Vietnamese tone marks extend beyond a compressed line box in a narrow sidebar. This is worth testing with a real sample rather than extrapolating from the English source, because language-specific length, fonts and structure can change the presentation even when the translation itself is accurate.
What to do. Use generous line height and inspect accented samples at realistic print scale; check composed and decomposed Unicode sequences in source tests. Keep the decision visible to an editor and distinguish a layout correction from an unauthorized alteration to the translation. If the underlying text needs rewriting, return that decision to the language owner rather than disguising it with styling.
What passes. Reviewers see complete marks on both ordinary text and bold or italic headings. Check the representative page and a second edge case, not only the most attractive page. A useful release note records the observed outcome, the file version and any deliberate exception.
Failure to avoid. Do not normalize or strip characters as a cosmetic workaround. The practical test is whether another reader could independently identify the same problem and confirm its resolution. A successful render alone cannot answer that question.
12. Watch line-length expansion
A translated sentence can expand substantially relative to the source. Width, rather than dictionary accuracy, may become the limiting factor. In a multilingual publishing project this is not a cosmetic detail: a reader must be able to act on the actual translated meaning, while the publisher must be able to explain how the finished file came to exist.
Example. A German safety instruction is longer than its English source and the warning box increases to two lines. This is worth testing with a real sample rather than extrapolating from the English source, because language-specific length, fonts and structure can change the presentation even when the translation itself is accurate.
What to do. Let containers reflow, review warnings and captions and edit only with linguistic approval if text must be shortened. Keep the decision visible to an editor and distinguish a layout correction from an unauthorized alteration to the translation. If the underlying text needs rewriting, return that decision to the language owner rather than disguising it with styling.
What passes. The full approved meaning appears without clipping or reduced legibility. Check the representative page and a second edge case, not only the most attractive page. A useful release note records the observed outcome, the file version and any deliberate exception.
Failure to avoid. Never use CSS overflow hiding to meet a fixed height requirement. The practical test is whether another reader could independently identify the same problem and confirm its resolution. A successful render alone cannot answer that question.
13. Protect critical warning blocks
Some information must remain together for safety or comprehension. Breaking a warning title from its instructions can change how it is read. In a multilingual publishing project this is not a cosmetic detail: a reader must be able to act on the actual translated meaning, while the publisher must be able to explain how the finished file came to exist.
Example. A chemical-handling notice places the hazard header at the bottom of one page and the action on the next. This is worth testing with a real sample rather than extrapolating from the English source, because language-specific length, fonts and structure can change the presentation even when the translation itself is accurate.
What to do. Apply suitable break-inside or break-after rules and check that the content still fits in real page geometry. Keep the decision visible to an editor and distinguish a layout correction from an unauthorized alteration to the translation. If the underlying text needs rewriting, return that decision to the language owner rather than disguising it with styling.
What passes. The warning and its action can be understood without searching through page boundaries. Check the representative page and a second edge case, not only the most attractive page. A useful release note records the observed outcome, the file version and any deliberate exception.
Failure to avoid. Rules that prohibit all page breaks may generate blank pages or large unusable gaps. The practical test is whether another reader could independently identify the same problem and confirm its resolution. A successful render alone cannot answer that question.
14. Manage headings near page edges
A standalone heading at the bottom of a page makes navigation harder. Long chapters need balanced pagination without destroying natural document flow. In a multilingual publishing project this is not a cosmetic detail: a reader must be able to act on the actual translated meaning, while the publisher must be able to explain how the finished file came to exist.
Example. An Italian training handbook has a level-two heading followed by a full-page blank after a forced break. This is worth testing with a real sample rather than extrapolating from the English source, because language-specific length, fonts and structure can change the presentation even when the translation itself is accurate.
What to do. Test CSS break rules and keep-with-next behavior against short and long translated headings. Keep the decision visible to an editor and distinguish a layout correction from an unauthorized alteration to the translation. If the underlying text needs rewriting, return that decision to the language owner rather than disguising it with styling.
What passes. Readers see a heading with meaningful related text on the same page whenever practical. Check the representative page and a second edge case, not only the most attractive page. A useful release note records the observed outcome, the file version and any deliberate exception.
Failure to avoid. Do not force every subsection to a new page unless the publication design requires it. The practical test is whether another reader could independently identify the same problem and confirm its resolution. A successful render alone cannot answer that question.
15. Evaluate widow and orphan control
A one-line fragment at a page boundary can disrupt reading and interfere with editorial comparison across versions. In a multilingual publishing project this is not a cosmetic detail: a reader must be able to act on the actual translated meaning, while the publisher must be able to explain how the finished file came to exist.
Example. A Portuguese paragraph’s final line lands alone at the start of the next page after translation expansion. This is worth testing with a real sample rather than extrapolating from the English source, because language-specific length, fonts and structure can change the presentation even when the translation itself is accurate.
What to do. Use widows and orphans settings where supported and inspect the result visually; accept that some languages need editorial judgment. Keep the decision visible to an editor and distinguish a layout correction from an unauthorized alteration to the translation. If the underlying text needs rewriting, return that decision to the language owner rather than disguising it with styling.
What passes. Paragraph fragments at page boundaries do not impair comprehension or look accidental. Check the representative page and a second edge case, not only the most attractive page. A useful release note records the observed outcome, the file version and any deliberate exception.
Failure to avoid. Machine-generated pagination must not be evaluated only by total page count. The practical test is whether another reader could independently identify the same problem and confirm its resolution. A successful render alone cannot answer that question.
16. Keep tables within width
Tables combine translated headings, variable-length values, numbers, notes and often different scripts. They deserve separate responsive and print tests. In a multilingual publishing project this is not a cosmetic detail: a reader must be able to act on the actual translated meaning, while the publisher must be able to explain how the finished file came to exist.
Example. A localized fee schedule gains a longer header, squeezing the amount column so decimals seem attached to descriptions. This is worth testing with a real sample rather than extrapolating from the English source, because language-specific length, fonts and structure can change the presentation even when the translation itself is accurate.
What to do. Give tables suitable column widths, allow deliberate text wrapping, repeat essential headings if supported, and consider reorganizing genuinely wide data. Keep the decision visible to an editor and distinguish a layout correction from an unauthorized alteration to the translation. If the underlying text needs rewriting, return that decision to the language owner rather than disguising it with styling.
What passes. Every cell stays legible, aligned to the correct row and within page margins. Check the representative page and a second edge case, not only the most attractive page. A useful release note records the observed outcome, the file version and any deliberate exception.
Failure to avoid. Shrinking text below the reading requirement is not a valid resolution. The practical test is whether another reader could independently identify the same problem and confirm its resolution. A successful render alone cannot answer that question.
17. Label figures and captions correctly
Text may reside inside images, in HTML captions or in separate labels. These parts can be maintained by different teams and become inconsistent. In a multilingual publishing project this is not a cosmetic detail: a reader must be able to act on the actual translated meaning, while the publisher must be able to explain how the finished file came to exist.
Example. A French PDF has a translated figure caption but the screenshot still contains English interface labels. This is worth testing with a real sample rather than extrapolating from the English source, because language-specific length, fonts and structure can change the presentation even when the translation itself is accurate.
What to do. Inventory translatable text in diagrams and images, then confirm image choice and caption match the approved edition. Keep the decision visible to an editor and distinguish a layout correction from an unauthorized alteration to the translation. If the underlying text needs rewriting, return that decision to the language owner rather than disguising it with styling.
What passes. A reader does not encounter contradictory terminology between figure and accompanying text. Check the representative page and a second edge case, not only the most attractive page. A useful release note records the observed outcome, the file version and any deliberate exception.
Failure to avoid. Do not assume embedded words inside an image are included in HTML extraction checks. The practical test is whether another reader could independently identify the same problem and confirm its resolution. A successful render alone cannot answer that question.
18. Check footnotes and citations
Footnotes and references connect a claim to evidence. Conversion can move or reflow them even when the source reference target is intact. In a multilingual publishing project this is not a cosmetic detail: a reader must be able to act on the actual translated meaning, while the publisher must be able to explain how the finished file came to exist.
Example. A translated research summary refers to note 8, but its link points to a deleted English-only footnote. This is worth testing with a real sample rather than extrapolating from the English source, because language-specific length, fonts and structure can change the presentation even when the translation itself is accurate.
What to do. Preserve link targets and note identifiers; test whether the chosen CSS and renderer version support the desired placement. Keep the decision visible to an editor and distinguish a layout correction from an unauthorized alteration to the translation. If the underlying text needs rewriting, return that decision to the language owner rather than disguising it with styling.
What passes. Citation numbering, destinations and reference text agree throughout the final PDF. Check the representative page and a second edge case, not only the most attractive page. A useful release note records the observed outcome, the file version and any deliberate exception.
Failure to avoid. A blue hyperlink is not proof that its destination still exists. The practical test is whether another reader could independently identify the same problem and confirm its resolution. A successful render alone cannot answer that question.
19. Build reliable internal links
A multilingual PDF needs navigable headings and tables of contents, especially when documents are long or delivered digitally. In a multilingual publishing project this is not a cosmetic detail: a reader must be able to act on the actual translated meaning, while the publisher must be able to explain how the finished file came to exist.
Example. A Spanish compliance manual links section 4.2 in the text, but its anchor was renamed during an export step. This is worth testing with a real sample rather than extrapolating from the English source, because language-specific length, fonts and structure can change the presentation even when the translation itself is accurate.
What to do. Keep stable IDs in the translated HTML and click representative internal links after rendering. Keep the decision visible to an editor and distinguish a layout correction from an unauthorized alteration to the translation. If the underlying text needs rewriting, return that decision to the language owner rather than disguising it with styling.
What passes. Bookmarks or links that are intended to exist lead to the correct translated sections. Check the representative page and a second edge case, not only the most attractive page. A useful release note records the observed outcome, the file version and any deliberate exception.
Failure to avoid. Avoid changing IDs simply because a heading was translated. The practical test is whether another reader could independently identify the same problem and confirm its resolution. A successful render alone cannot answer that question.
20. Review external link policy
External websites may change languages, require authentication or be unsuitable for an offline document. Link text must explain its destination. In a multilingual publishing project this is not a cosmetic detail: a reader must be able to act on the actual translated meaning, while the publisher must be able to explain how the finished file came to exist.
Example. An education leaflet displays ‘Read more’ in a translated paragraph but links to a source-language-only page without warning. This is worth testing with a real sample rather than extrapolating from the English source, because language-specific length, fonts and structure can change the presentation even when the translation itself is accurate.
What to do. Provide descriptive translated link text and decide whether translated external resources are available or whether a language note is necessary. Keep the decision visible to an editor and distinguish a layout correction from an unauthorized alteration to the translation. If the underlying text needs rewriting, return that decision to the language owner rather than disguising it with styling.
What passes. A reviewer can open key links and understand the expected language and context. Check the representative page and a second edge case, not only the most attractive page. A useful release note records the observed outcome, the file version and any deliberate exception.
Failure to avoid. Never imply that an external resource is available in the target language unless checked. The practical test is whether another reader could independently identify the same problem and confirm its resolution. A successful render alone cannot answer that question.
21. Handle missing images and network resources
A renderer may retrieve linked assets from disk or the network. Unavailable resources can produce incomplete pages or a security exposure. In a multilingual publishing project this is not a cosmetic detail: a reader must be able to act on the actual translated meaning, while the publisher must be able to explain how the finished file came to exist.
Example. A batch renders successfully while an icon CDN is temporarily blocked, leaving blank spaces in all translated PDFs. This is worth testing with a real sample rather than extrapolating from the English source, because language-specific length, fonts and structure can change the presentation even when the translation itself is accurate.
What to do. Use controlled local assets when possible, inspect warning logs, and define an appropriate retrieval or isolation policy. Keep the decision visible to an editor and distinguish a layout correction from an unauthorized alteration to the translation. If the underlying text needs rewriting, return that decision to the language owner rather than disguising it with styling.
What passes. Images, logos and functional graphics appear in proofs with the expected licensed versions. Check the representative page and a second edge case, not only the most attractive page. A useful release note records the observed outcome, the file version and any deliberate exception.
Failure to avoid. Untrusted HTML or CSS should not be given unrestricted access to local files or networks. The practical test is whether another reader could independently identify the same problem and confirm its resolution. A successful render alone cannot answer that question.
22. Keep source files trustworthy
Rendering arbitrary documents can expose the server to unwanted resource fetching and other input-based risks. Translation does not make a source safe. In a multilingual publishing project this is not a cosmetic detail: a reader must be able to act on the actual translated meaning, while the publisher must be able to explain how the finished file came to exist.
Example. A vendor sends HTML containing remote references that were not part of the authorized translation package. This is worth testing with a real sample rather than extrapolating from the English source, because language-specific length, fonts and structure can change the presentation even when the translation itself is accurate.
What to do. Treat untrusted HTML and CSS as potentially unsafe, use sandboxing and restricted resource access, and assess the documented security guidance. Keep the decision visible to an editor and distinguish a layout correction from an unauthorized alteration to the translation. If the underlying text needs rewriting, return that decision to the language owner rather than disguising it with styling.
What passes. A build review records where every external dependency came from and which permissions were allowed. Check the representative page and a second edge case, not only the most attractive page. A useful release note records the observed outcome, the file version and any deliberate exception.
Failure to avoid. Do not run third-party HTML with broad network or filesystem permissions merely to meet a deadline. The practical test is whether another reader could independently identify the same problem and confirm its resolution. A successful render alone cannot answer that question.
23. Plan metadata intentionally
Title, author and language-related properties influence discovery, archiving and accessibility. Some properties depend on renderer version and source markup. In a multilingual publishing project this is not a cosmetic detail: a reader must be able to act on the actual translated meaning, while the publisher must be able to explain how the finished file came to exist.
Example. A Polish report opens with a generic filename and an English document title in PDF properties. This is worth testing with a real sample rather than extrapolating from the English source, because language-specific length, fonts and structure can change the presentation even when the translation itself is accurate.
What to do. Set accurate HTML title and approved metadata fields, render, and inspect properties with a PDF inspection tool. Keep the decision visible to an editor and distinguish a layout correction from an unauthorized alteration to the translation. If the underlying text needs rewriting, return that decision to the language owner rather than disguising it with styling.
What passes. The metadata matches edition, publisher, title and intended language. Check the representative page and a second edge case, not only the most attractive page. A useful release note records the observed outcome, the file version and any deliberate exception.
Failure to avoid. Metadata correctness cannot rescue a PDF whose actual text is wrong. The practical test is whether another reader could independently identify the same problem and confirm its resolution. A successful render alone cannot answer that question.
24. Choose PDF variants carefully
PDF/A and PDF/UA claims depend on supported renderer options, valid input and independent conformance checks. They are not magic quality switches. In a multilingual publishing project this is not a cosmetic detail: a reader must be able to act on the actual translated meaning, while the publisher must be able to explain how the finished file came to exist.
Example. A contractor adds a PDF/UA flag and assumes accessibility is solved although tables are unlabeled and images lack text alternatives. This is worth testing with a real sample rather than extrapolating from the English source, because language-specific length, fonts and structure can change the presentation even when the translation itself is accurate.
What to do. Consult the exact WeasyPrint version help for –pdf-variant or tagging options, generate a proof and run an appropriate independent validator. Keep the decision visible to an editor and distinguish a layout correction from an unauthorized alteration to the translation. If the underlying text needs rewriting, return that decision to the language owner rather than disguising it with styling.
What passes. The requested profile is supported and the output passes relevant validation and human checks. Check the representative page and a second edge case, not only the most attractive page. A useful release note records the observed outcome, the file version and any deliberate exception.
Failure to avoid. Never label a publication standards-compliant solely because the export flag was accepted. The practical test is whether another reader could independently identify the same problem and confirm its resolution. A successful render alone cannot answer that question.
25. Examine text extraction
Text extraction can reveal lost or substituted characters that visual viewing misses, especially in complex layouts. In a multilingual publishing project this is not a cosmetic detail: a reader must be able to act on the actual translated meaning, while the publisher must be able to explain how the finished file came to exist.
Example. A multilingual legal table looks intact, but copying a sentence produces a broken combination of punctuation and numbers. This is worth testing with a real sample rather than extrapolating from the English source, because language-specific length, fonts and structure can change the presentation even when the translation itself is accurate.
What to do. Extract representative text with a PDF tool and compare it to an approved text transcript, accounting for layout-specific reading order. Keep the decision visible to an editor and distinguish a layout correction from an unauthorized alteration to the translation. If the underlying text needs rewriting, return that decision to the language owner rather than disguising it with styling.
What passes. Script characters, dates, quantities and meaningful text sequences survive extraction. Check the representative page and a second edge case, not only the most attractive page. A useful release note records the observed outcome, the file version and any deliberate exception.
Failure to avoid. Matching byte order is not always identical to visual reading order, so investigate differences contextually. The practical test is whether another reader could independently identify the same problem and confirm its resolution. A successful render alone cannot answer that question.
26. Run page-image comparison
Images of pages make it easier to catch spacing, cropping and typography regressions across builds. Automatic visual diffs still need interpretation. In a multilingual publishing project this is not a cosmetic detail: a reader must be able to act on the actual translated meaning, while the publisher must be able to explain how the finished file came to exist.
Example. A new font package changes line wrapping in only the Japanese edition, pushing a chart legend off the page. This is worth testing with a real sample rather than extrapolating from the English source, because language-specific length, fonts and structure can change the presentation even when the translation itself is accurate.
What to do. Render each PDF page to an image, compare against the last approved proof and inspect differences at the page level. Keep the decision visible to an editor and distinguish a layout correction from an unauthorized alteration to the translation. If the underlying text needs rewriting, return that decision to the language owner rather than disguising it with styling.
What passes. A reviewer can explain every meaningful change and find no missing content. Check the representative page and a second edge case, not only the most attractive page. A useful release note records the observed outcome, the file version and any deliberate exception.
Failure to avoid. Do not reject a legitimate translation merely because its page count differs from English. The practical test is whether another reader could independently identify the same problem and confirm its resolution. A successful render alone cannot answer that question.
27. Inspect accessibility as a reader
Semantic HTML, meaningful alt text and useful document navigation are necessary inputs, but real accessibility depends on what survives conversion. In a multilingual publishing project this is not a cosmetic detail: a reader must be able to act on the actual translated meaning, while the publisher must be able to explain how the finished file came to exist.
Example. A report has attractive colored headings, yet a screen-reader user cannot identify the hierarchy or understand a diagram. This is worth testing with a real sample rather than extrapolating from the English source, because language-specific length, fonts and structure can change the presentation even when the translation itself is accurate.
What to do. Check headings, actual alternative text, link names, language and reading order in suitable assistive and inspection tools. Keep the decision visible to an editor and distinguish a layout correction from an unauthorized alteration to the translation. If the underlying text needs rewriting, return that decision to the language owner rather than disguising it with styling.
What passes. The intended readers can navigate and understand essential content without relying only on visual layout. Check the representative page and a second edge case, not only the most attractive page. A useful release note records the observed outcome, the file version and any deliberate exception.
Failure to avoid. A machine validator can support accessibility testing but does not replace a user-centered review. The practical test is whether another reader could independently identify the same problem and confirm its resolution. A successful render alone cannot answer that question.
28. Document numbers and locale conventions
Decimal separators, dates, time zones, units and currency symbols can be ambiguous across countries. A PDF freezes those choices for distribution. In a multilingual publishing project this is not a cosmetic detail: a reader must be able to act on the actual translated meaning, while the publisher must be able to explain how the finished file came to exist.
Example. In one market 1,500 denotes one-and-a-half; in another it denotes one thousand five hundred, changing a payment instruction. This is worth testing with a real sample rather than extrapolating from the English source, because language-specific length, fonts and structure can change the presentation even when the translation itself is accurate.
What to do. Use an approved market style guide and verify high-risk numeric expressions independently from surrounding translated prose. Keep the decision visible to an editor and distinguish a layout correction from an unauthorized alteration to the translation. If the underlying text needs rewriting, return that decision to the language owner rather than disguising it with styling.
What passes. Numbers and contextual units keep the intended real-world quantity. Check the representative page and a second edge case, not only the most attractive page. A useful release note records the observed outcome, the file version and any deliberate exception.
Failure to avoid. Do not globally replace punctuation in formatted numbers without understanding their semantics. The practical test is whether another reader could independently identify the same problem and confirm its resolution. A successful render alone cannot answer that question.
29. Manage release sign-off
A PDF is not complete just because it renders. Translation owner, technical publisher and subject expert may have different responsibilities. In a multilingual publishing project this is not a cosmetic detail: a reader must be able to act on the actual translated meaning, while the publisher must be able to explain how the finished file came to exist.
Example. A manual is rebuilt after approval to correct a broken font; the new copy is distributed without the language reviewer seeing changed line breaks. This is worth testing with a real sample rather than extrapolating from the English source, because language-specific length, fonts and structure can change the presentation even when the translation itself is accurate.
What to do. Maintain a release checklist with approved source, target revision, renderer version, fonts, proof file and sign-off decision. Keep the decision visible to an editor and distinguish a layout correction from an unauthorized alteration to the translation. If the underlying text needs rewriting, return that decision to the language owner rather than disguising it with styling.
What passes. The released PDF can be traced back to the actual reviewed artifact. Check the representative page and a second edge case, not only the most attractive page. A useful release note records the observed outcome, the file version and any deliberate exception.
Failure to avoid. Do not treat an earlier approval as automatic approval for a materially altered artifact. The practical test is whether another reader could independently identify the same problem and confirm its resolution. A successful render alone cannot answer that question.
30. Archive a reproducible package
Future corrections and legal questions require a reproducible history, not just the final PDF. Store reasonable source artifacts without exposing secrets. In a multilingual publishing project this is not a cosmetic detail: a reader must be able to act on the actual translated meaning, while the publisher must be able to explain how the finished file came to exist.
Example. Six months after publication a customer reports missing Arabic diacritics; no one can reproduce the font environment. This is worth testing with a real sample rather than extrapolating from the English source, because language-specific length, fonts and structure can change the presentation even when the translation itself is accurate.
What to do. Archive approved HTML, CSS, permitted assets, font manifest, renderer version, output hash and release notes in controlled storage. Keep the decision visible to an editor and distinguish a layout correction from an unauthorized alteration to the translation. If the underlying text needs rewriting, return that decision to the language owner rather than disguising it with styling.
What passes. A competent colleague can regenerate the output and compare it with the archived final file. Check the representative page and a second edge case, not only the most attractive page. A useful release note records the observed outcome, the file version and any deliberate exception.
Failure to avoid. Do not publish internal credentials, private drafts or licensed font files as downloadable source. The practical test is whether another reader could independently identify the same problem and confirm its resolution. A successful render alone cannot answer that question.
Worked mini-project: a three-language public information pack
Imagine a public agency issuing equivalent English, French and Arabic guidance about renewing a service appointment. The source team supplies an approved English original, and language specialists approve separate French and Arabic HTML files. The PDF publisher creates distinct output paths for each language rather than building a single mixed-language file by accident. Each page has the same substantive obligations, but not necessarily the same line breaks or total number of pages.
First, render only the heading, one explanatory paragraph, a numbered instruction, a short table, an embedded web address and a final warning. In French, test long headings, accents, apostrophes, dates and amounts. In Arabic, test right-to-left body copy with left-to-right appointment codes and web addresses. In English, confirm the source reference numbers and contact details before comparing the language editions. These cases are diagnostic rather than a promise that every language will share one fixed visual template.
Second, review the CSS page rule, language declarations and font fallbacks. If the Arabic table overflows, repair the column design or allow appropriate wrapping, then have the language owner inspect the changed presentation. If a French warning breaks across pages, use a targeted page-break treatment, not an arbitrary cut in the sentence. If an icon is missing, verify the source asset path and permission to reproduce it.
Finally, extract key PDF text, click the appointment links, compare page images, and record the precise PDF returned from review. Only that reviewed hash should be distributed. The lasting lesson is that a good multilingual PDF preserves actionable meaning, reader navigation, visual legibility and a documented path back to the approved edition.
Frequently asked questions
Can WeasyPrint translate an English report automatically?
No. Its core job is rendering documents, not translating or verifying language. Supply a professionally reviewed target-language HTML version and judge the generated PDF against it. When the document contains legal, medical or safety-sensitive material, involve an appropriate domain reviewer before release.
Do I need a separate CSS file for every language?
Not necessarily. A shared baseline can be effective, with language-aware overrides for typography, direction, page breaks and particular writing systems. Test each language rather than assuming the same spacing will work. When the document contains legal, medical or safety-sensitive material, involve an appropriate domain reviewer before release.
Why does a PDF display boxes instead of letters?
The required font or glyph coverage may be missing, blocked or substituted. Check the renderer environment, font files, licensing and actual script coverage before modifying the words. When the document contains legal, medical or safety-sensitive material, involve an appropriate domain reviewer before release.
Will a PDF/UA flag guarantee an accessible document?
No. The tool option and actual accessibility are different claims. Confirm semantic headings, text alternatives, logical reading order, language information and independent conformance where required. When the document contains legal, medical or safety-sensitive material, involve an appropriate domain reviewer before release.
Why is the translation two pages longer than English?
Length, fonts, word boundaries and sentence structure change across languages. A different page count is not automatically a defect. Inspect whether content remains complete, readable and correctly ordered. When the document contains legal, medical or safety-sensitive material, involve an appropriate domain reviewer before release.
How should I handle an Arabic paragraph with English code fragments?
Use meaningful HTML language and direction markup; inspect real mixed-script examples with an Arabic reviewer. Avoid inserting arbitrary bidirectional control characters as a blanket fix. When the document contains legal, medical or safety-sensitive material, involve an appropriate domain reviewer before release.
What should be compared after a font update?
Inspect line wrapping, punctuation, page breaks, tables, captions, and text extraction. The most important differences are those that alter meaning or hide content. When the document contains legal, medical or safety-sensitive material, involve an appropriate domain reviewer before release.
Can I render HTML received from an unknown vendor?
Treat untrusted HTML, CSS and remotely referenced assets cautiously. WeasyPrint documents security considerations; use a restricted, appropriately isolated environment rather than exposing sensitive files. When the document contains legal, medical or safety-sensitive material, involve an appropriate domain reviewer before release.
Should the final PDF be the only archived artifact?
No. Keep the approved translation, stylesheet, necessary licensed asset references, renderer version and sign-off record so a correction can be reproduced. When the document contains legal, medical or safety-sensitive material, involve an appropriate domain reviewer before release.
What is the difference from a PDF validator?
WeasyPrint produces the document. Validation tools such as veraPDF examine conformance to relevant standards, while visual, linguistic and accessibility review check the information people actually receive. When the document contains legal, medical or safety-sensitive material, involve an appropriate domain reviewer before release.
Sources and further reading
For current syntax and release-dependent flags see WeasyPrint official first steps and the upstream project documentation. For complementary checks, read eduKate’s veraPDF multilingual archive QA guide and LibreOffice document-to-PDF guide. These cover different processes: rendering from HTML, validation of conformance, and office-format conversion.
Final principle
The finished deliverable is the reader’s document, not the command transcript. The publisher’s responsibility is to make the approved translation readable and traceable in the environment where it will actually be used. Plan from the reader backwards: what they must understand, which language they will use, what could be misread, and which evidence will show that the released PDF is the one that was reviewed.