How do you translate a Typst report, book, research paper or teaching handout without breaking fonts, references, equations and document layout? This Typst CLI localization guide explains typst compile, typst watch, text language settings, font fallback, right-to-left scripts, Unicode, heading outlines, bibliography keys, reproducible PDF output and quality assurance. It helps translators, designers, educators, publishing teams and developers build multilingual documents whose meaning and visual structure both survive.
Typst is a markup-based typesetting system with a compiler and a document language of its own. It is not a machine translator, terminology database or guarantee that the rendered PDF is accessible and scientifically accurate. Changing text can change page breaks, headings, table widths, citations and font shaping. A translation may compile successfully even when its safety instructions, formulas, dates or captions no longer mean what the source author intended.
A professional workflow begins by identifying the authoritative Typst source, installed compiler version, fonts, source revision and intended output format. Separate prose from syntax and executable expressions, apply language and font settings intentionally, render representative pages, then inspect the complete artifact with native-language and technical reviewers. The finished document should let people find, understand and use information without guessing about missing glyphs or altered logic.
Quick reference: essential checks
- Confirm the maintained Typst compiler and its installed CLI help.
- Use
typst compile document.typfor a basic reproducible compile when appropriate. - Use
typst watch document.typfor iteration, not as a substitute for final release QA. - Review
textsettings such as language, region, direction and font where relevant. - Run
typst fontsto inspect discovered fonts in the actual build environment. - Preserve functions, labels, references, citation keys, source paths and mathematical notation.
- Test every writing system used in the final document, including accented, CJK and RTL text.
- Recheck headings, bookmarks, page numbers, tables and cross-references after translation.
- Validate source meaning and domain-sensitive quantities independently of compilation.
- Inspect the exported PDF on multiple viewers and with accessibility checks where necessary.
Understand what Typst changes when a document is translated
Typst combines source markup, functions, styling rules and rendering. The visible sentence is only one part of the file. A heading may have a structural role and generated number, a figure may carry a label referenced elsewhere, and a font setting may determine which glyph appears. Translating the sentence without reviewing those relationships can create a document that renders but misleads the reader.
Imagine a research handout translated from English into Arabic. The paragraph meanings may be accurate, but a Latin-only font could omit Arabic glyphs, a left-to-right layout may confuse mixed numeric expressions, and a referenced figure might move to a different page. None of these defects is solved by proofreading the words alone. They must be tested in the produced artifact.
Establish roles at the outset. The language editor decides natural wording and terminology; the subject specialist verifies evidence, formulas and instructions; the Typeset or build owner verifies syntax, font behavior and output consistency. A single person may cover several responsibilities, but a successful compiler exit code should never be mistaken for all three approvals.
Start from the authoritative source
A PDF supplied for translation may not be the best editable source. If the publisher maintains a .typ document and related templates, begin there where possible. Record the source revision, included files, stylesheet or shared functions, citation assets and image resources. The source-to-output relationship matters when a warning or value is corrected after translation begins.
If the document contains multiple chapters, determine whether they share heading numbering, bibliography data or imported functions. Translating an isolated page can produce a visually plausible sample while omitting a dependency that the full document needs. Build a project map before changing file names or include paths. Mark files that are generated or owned by other software.
Keep a release record identifying the exact material translated and any editorial adaptations. The aim is a traceable edition, not simply a new PDF that happens to look similar. When readers ask whether a translated page reflects the current report, the publisher should be able to answer from evidence rather than memory.
Verify the compiler and command syntax
The Typst repository provides a CLI for compiling documents locally. A basic invocation is typst compile document.typ; typst watch can support iterative work. The exact option set and supported output formats depend on the installed release, so review typst --help and command-specific help before relying on flags from an old tutorial.
Do not translate command names, option tokens or file extensions. The instructional sentence around a command can be localized, but the terminal command must remain executable for the intended operating system. When a guide uses examples, distinguish literal filenames that are part of the project from placeholders a reader may replace.
Compile a small representative document in a clean environment before translating a large book. Record the compiler version and font inventory. If two machines produce substantially different typography, investigate environmental differences before blaming the translation. Reproducible document production is a prerequisite for meaningful layout review.
Know the difference between compile and watch
A watch command is useful during development because it can respond to file changes and repeatedly produce output. It is not a release-signoff mechanism. The reviewer still needs to know which final source revision, configuration and tool environment generated the artifact being distributed. A live preview can make an intermediate state appear more final than it is.
When translating long documents, use an iterative loop: change one logical section, inspect the output, and compare with the source. That makes layout regressions easier to attribute. However, the entire final document should receive a clean compile and full inspection before distribution, because pagination, references and outlines may depend on content beyond the edited section.
Clearly explain this difference to contributors. “Watch the page update” helps them work efficiently; “compile the approved revision and verify the produced PDF” describes the acceptance task. Keeping these verbs precise prevents reviewers from confusing interactive convenience with documented evidence of a reliable release.
Language settings shape typesetting behavior
Typst’s text element supports properties including lang, region, script and dir, along with font and hyphenation controls. Their purpose is to help the typesetting system handle language-sensitive behavior. The values should reflect the intended content and writing system rather than remain accidentally inherited from an English template.
A French document may need French language settings for appropriate text treatment, while an Arabic document may need directionality and font verification. An English paragraph embedded inside a non-English document can be a separate language run. The translator should not assume that one global setting is correct for every quotation, citation or code sample.
Language settings do not translate prose. They are technical information used by the layout system. The editor must still choose correct terms, natural syntax, culturally appropriate examples and readable punctuation. After applying settings, inspect the actual output rather than trusting that a configuration value automatically yields typographically correct pages.
Fonts are content infrastructure
A font is not only a visual brand choice in a multilingual document. It determines whether a reader can see characters, mathematical symbols and combinations of scripts. A typeface excellent for Latin text may lack full Arabic, Devanagari or CJK coverage. Typst supports font selection and fallback behavior, but a publisher must verify what is installed in the rendering environment.
The command typst fonts can show discovered fonts, and Typst documents font path options for local compilation. Project machines may not have the same system font collections. A PDF that looks correct on a designer’s laptop can fail in a container build when a fallback font is missing. Test the production environment explicitly.
Choose fonts for coverage, readability, embedding and license compatibility. Do not treat visual similarity to the source as the only criterion. A translated school handout should display diacritics, punctuation and symbols clearly even if the final typography differs from the English edition. Consistency matters, but legibility and meaning matter more.
Understand font fallback
Font fallback occurs when a selected font lacks certain glyphs or when the system chooses a compatible alternative. This can be helpful for mixed-language documents, but uncontrolled fallback can change proportions, baseline alignment and line spacing. A reader may notice a sudden change in weight or style mid-sentence that the source author never intended.
Typst’s text documentation discusses font arrays, fallback and per-script examples. A publisher can plan a sensible font stack for the required languages. Before settling on one, test real words, numbers, quotations, symbols and punctuation rather than a sample containing only a language’s most common characters. Rare glyphs often reveal coverage gaps.
Inspect the exported PDF on more than one viewer and verify that text remains selectable and copyable. Font coverage is not adequately established by looking at a static screenshot. If the document is a long report, sample pages from every major section and check the bibliography, tables, footnotes and mathematical notation as well.
Accents and combining characters
Many languages use accented characters, and Unicode may encode visually similar text using different code-point sequences. A combination of font behavior and normalization can change how accents appear or how text is copied and searched. Translators should preserve legitimate orthography and avoid replacing specialized characters with rough ASCII substitutes simply because a font or tool is inconvenient.
A Spanish scientific handout may need accented technical terms, Greek mathematical symbols and English filenames. Each type of text has a different role. Ordinary prose should use proper Spanish spelling, equations should preserve authorized symbols, and file paths should remain exact. A visually confusable character in an identifier can create a technical failure even if it looks plausible on the page.
When diagnosing odd output, isolate a small string and inspect the actual Unicode characters before changing it. Test both glyph appearance and the copied text. A missing diacritic should be repaired through correct source text and font support, not by replacing the intended word with an inaccurate substitute.
CJK typography and mixed Latin text
Chinese, Japanese and Korean technical writing often mixes local scripts with English program names, numbers, mathematical notation and URLs. Line breaking and punctuation conventions differ from those of English. A translation that merely fits the original English page dimensions can produce poor spacing or unintended line breaks when the new script has different typographic needs.
Typst has text settings for font selection, script and language-sensitive behavior. Test representative paragraphs with local punctuation, inline Latin expressions, parentheses and emphasized text. Check whether the selected font stack supports every character and whether headings remain distinguishable. A small demonstration with only two words is not enough for a long technical manual.
Inspect paragraph density and page breaks. Avoid shrinking text aggressively just to preserve the source’s page count; that can undermine readability and accessibility. If translated text needs more space, let the layout adapt within the publication’s constraints. Communicate substantive layout changes to the editor rather than silently deleting explanations.
Arabic and Hebrew directionality
Right-to-left documents can contain left-to-right code, paths, measurements, identifiers and citations. The visible order of these runs may differ from their underlying character order. Typst exposes text direction controls, but using them correctly requires testing actual content. A configuration that appears adequate for plain Arabic may fail when mixed with parentheses, version strings or equations.
For a technical installation guide, protect commands and filenames as literal strings. Translate the surrounding instruction into natural Arabic or Hebrew, then inspect the exported PDF. Copy the command out and verify its character order. A reader should not have to guess which punctuation belongs to the command and which belongs to the sentence.
Avoid injecting invisible directional controls without understanding their purpose and their effect on search, selection and assistive technology. Test mixed-script pages with knowledgeable reviewers. The goal is a usable and copyable document, not merely a page that looks visually acceptable in one viewer.
Text language and region are not the same thing
A language can have regional orthographic, numerical and stylistic conventions. Typst’s lang and region settings help the text-processing pipeline make informed choices, but they should not be confused with an editorial style guide or national legal requirement. Use the appropriate settings when they materially affect typesetting, and handle cultural or legal adaptations through explicit authorial review.
Consider a Portuguese-language financial report destined for Brazil rather than Portugal. The editor may choose regional vocabulary, number presentation and terminology suitable for Brazilian readers. Merely setting a region value cannot translate the content or verify the currency and financial context. Those decisions require a qualified editor who understands what the amounts mean.
Record regional variants in the publication inventory so updates reach the intended edition. If a document serves a global audience, consider unambiguous dates and explicit units. Do not treat one region’s conventions as universally correct just because the source file happens to use them.
Hyphenation, justification and line breaking
Hyphenation can improve or damage a multilingual page depending on the language and the typesetting settings. Typst exposes hyphenation controls and text-layout options. The appropriate choice depends on font, line width, script and reading audience. A setting that helps English academic prose can create strange breaks in other languages if applied without testing.
A technical term should not be split in a way that makes it look like two different identifiers. Likewise, a code path or URL must remain understandable even if the line breaks. Review long words, headings, lists and narrow table cells under the actual page dimensions. A successful render only means the engine produced output, not that every break is pedagogically clear.
Avoid solving overflow solely by reducing font size. Consider approved adjustments to margins, table layout, explanatory wording or placement of examples. Maintain comfortable reading conditions for students and general readers. When the document is a printed guide, test a physical page or realistic print view rather than assessing only a zoomed desktop PDF.
Translate content without changing Typst syntax
Typst source contains markup markers, expressions, functions and content blocks. A translator who treats every source token as prose can break the file. Create a source map distinguishing text to translate from syntax to protect. This is particularly important for imported modules, counters, labels, variable names and custom templates.
In a heading such as = Introduction, the human-facing heading text can be localized while the structural heading marker should remain valid. In a reference like @methods, the label is a technical identifier; altering it without updating the target breaks the reference. The source language’s grammar does not dictate which technical tokens are editable.
A good translation interface allows editors to work on text with enough context to understand meaning while minimizing accidental syntax changes. After exporting the localized file, compile it and inspect the warnings. The compiler may catch broken syntax, but it cannot tell you whether the translated sentence accurately describes the referenced procedure.
Headings and document hierarchy
Typst uses headings to express logical sections and can generate an outline from them. Translators should maintain the hierarchy even if titles need to be rewritten for clarity. A heading is more than a visual line of large text: it helps readers navigate the document and can affect PDF bookmarks and generated contents.
The Typst documentation discusses heading levels and accessibility. Avoid skipping levels merely to obtain a preferred font size. If a long translated heading wraps across several lines, adjust its layout without demoting its semantic importance. Inspect how it appears in the outline, page header and bookmark panel.
A heading translation may legitimately be longer than the source. Test whether the full title remains intelligible, whether the chapter order still makes sense, and whether any cross-references relying on labels remain valid. The review should focus on navigation and information architecture, not on matching the English heading’s character count.
Outline and table of contents localization
Typst’s outline element can generate contents and other lists, with the title influenced by the text language or explicitly customized. This helps readers navigate translated documents, but the output requires inspection. A generated list may contain longer entries, different punctuation and updated page numbers that change after final layout.
For a bilingual textbook, do not paste an English table of contents as fixed text into the translated edition. Use the project’s generated mechanism where appropriate and review the result. If chapter names change language, ensure the outline uses their translated names and points to the intended pages. Check leading whitespace, leader dots and alignment under the target script.
Page numbers should be derived from the final layout, not copied from the original. A translation can legitimately increase the number of pages. The acceptance criterion is that readers find the correct chapter, not that every entry retains the English source’s pagination.
Cross-references and labels
Typst supports labels and references to headings, figures and other elements. These are structural connections that should remain stable during translation. A sentence can be localized while the target label stays unchanged, preserving a dependable reference. If a label must be renamed, update every reference deliberately and test the build.
Suppose a technical report uses a label <risk-table> for a table discussed throughout the text. Translating the table’s caption is appropriate; translating the label merely because it contains an English word may not be. The identifier is internal infrastructure. Preserve it unless the maintainers have a clear migration and verification plan.
Inspect the generated reference text, numbering and supplementary labels in the target language. The exact words before a number may depend on document settings. A mechanically valid reference can still be linguistically awkward, so the native-language editor should read it in full sentence context after compilation.
Figures, captions and evidence
Scientific and educational documents often rely on charts, photographs and diagrams as evidence. Translating only surrounding prose can leave crucial labels inside images in the source language. Identify which text belongs to the source image, which can be regenerated from data, and which must be added as an accessible explanation. Do not edit numbers or axes to match a rewritten claim.
A figure caption should faithfully state what the visual shows, including units, sample scope and limitations. If the source figure uses a color legend, ensure the translated caption does not reverse categories. Review images with the actual output size, because small fonts and long labels can become illegible in translated layouts.
For accessibility, supply meaningful descriptions according to the publishing format and its supported features. A decorative caption is not automatically an equivalent alternative for a complex statistical plot. Where necessary, provide a nearby text summary of trends and values so readers can understand the evidence without relying solely on visual cues.
Tables with long translated labels
Tables often reveal layout problems earlier than paragraphs because cell widths are constrained. A term that fits in English may be much longer in German or require different line breaking in Japanese. Typst’s table layout options can help, but the translation and numerical content must remain intact. Do not shorten a regulatory or technical label into ambiguity merely to fit the old column.
Review headers, row associations, units, signs, decimal punctuation and note markers. If a table presents a risk threshold or dose, a single lost symbol can change the interpretation. Compare the translated artifact against the source table cell by cell. Changes to layout are acceptable when they make the same information easier to read.
Test whether text overflows, gets clipped or becomes inaccessible at normal zoom and when printed. Page breaks through large tables need careful review. A well-designed translated table tells the same factual story, using the target language’s natural presentation, without sacrificing numeric precision or traceability.
Mathematical notation stays logically consistent
Equations may contain Latin and Greek letters, operators, subscripts, superscripts and references. These symbols should not be modified by ordinary prose translation. The editor may change the explanatory language around them, but the mathematical relationship remains the authority. A well-formed equation can still be accompanied by a wrong explanation, so mathematical review is essential.
Consider a statement about a confidence interval. Translating “95 percent confidence” as if it meant a 95 percent probability of a fixed parameter lying in a particular computed interval may misrepresent frequentist interpretation. Typst can render the symbols beautifully, but it cannot fix the conceptual error. The domain reviewer must validate what the text claims.
For textbooks, test whether symbols are defined consistently across chapters and diagrams. Maintain equation labels and check references after layout. A translation should help readers understand the mathematics without secretly changing the calculation to make the new prose sound smoother.
Bibliography keys and citation integrity
Typst documents support bibliography sources such as BibLaTeX and Hayagriva, with citations linked by keys. These keys identify records and are not sentences to translate. Human-facing titles may have authorized translations or transliterations, but bibliography metadata should remain traceable to the actual source. Do not invent a translated title that looks official when it is only an explanatory gloss.
A citation to an academic paper should still resolve after a document is translated. Verify the reference keys, entries and style choices in the compiled result. If the publisher uses different citation conventions for particular regions or disciplines, document the choice rather than silently changing source attribution.
Review bibliography links, author names, dates and editions. Preserve original titles where needed for retrieval, and label editorial translations clearly. A scholarly document is useful when readers can follow its evidence, not merely when all visible text has been translated into one language.
Footnotes, callouts and supplementary labels
A translated report may contain footnotes, warnings, supplemental captions and custom templates. Some labels are automatically generated, while others are written directly in source text. Identify which mechanism produced each item before changing it. A global template adjustment can affect every page, so test it on a representative document.
Footnotes are particularly vulnerable to layout shifts. A short English footnote can become several lines in another language, pushing surrounding text or changing pagination. Do not delete substantive qualifications to preserve the original page count. Adjust layout according to the publication’s policy and verify the note’s association with the correct reference marker.
For warnings, preserve the strength of the statement, the conditions under which it applies and the action the reader must take. A translated warning that looks prominent but omits a negation is unsafe. Proofreading and subject review remain necessary regardless of how well the template renders.
Metadata and source attribution
Professional publications need accurate titles, authorship, issue dates, version numbers, document purpose and rights information. Typst can place metadata into an output, but the publisher must verify the values. Translation should not change ownership, confidentiality status or effective date unless an authorized edition policy requires it.
A translated manual may carry both the original publication date and the date of its localized edition. These are different facts. Avoid presenting a translated revision as though it were the latest technical specification if its source is outdated. Explain the relationship in concise, reader-facing language, especially for policy and safety documents.
Check PDF properties and the visible cover, header and footer. A document can contain a correct localized title on the first page while metadata still displays an old internal filename. Readers and search systems can encounter either version. Make them consistent and accurate.
Numbers, currencies and units across regions
Amounts and measurements frequently require localized presentation but not altered meaning. Decimal separators, thousands grouping, date order and currency notation vary. Translators must distinguish a formatting convention from a numerical conversion. Do not change 1.5 into 1,500 by confusing decimal punctuation with grouping.
A worldwide instruction may mention a price or legal threshold that applies only to one jurisdiction. Translate the statement faithfully and identify its scope; do not silently replace it with a local amount. If currency conversion is requested, specify the date and rate source separately so the original and derived amounts remain distinguishable.
Check every value in tables, formulas, captions and prose. Use a second reviewer for high-consequence calculations. The Typst compiler can position digits and units correctly without verifying the financial, scientific or regulatory meaning of those digits.
Document length and pagination
Languages expand and contract differently. A translated paragraph may occupy more lines, causing a figure or note to move to the next page. Some editions legitimately become longer than the source. A typesetting workflow should accept controlled reflow rather than deleting meaning to force identical page numbering.
When a document refers to “page 12,” that reference may need revision because the translated edition’s pagination differs. Prefer structural cross-references where available. Check the final table of contents, page headers and internal references after all layout changes. A reference that points to an old page is a practical defect even if the translated sentence is accurate.
For print distribution, inspect margins, bleed requirements where relevant, and paper size assumptions. A handbook designed for one region’s standard page size may require adjustment for another market. These are explicit design decisions, not consequences that should be left to whatever default the compiler happens to use.
Reproducibility across machines
Different operating systems and CI images may have different fonts, file paths, installed packages and rendering capabilities. Reproducibility requires a pinned toolchain and a documented environment. A source file is not sufficient evidence of layout equivalence if a second machine substitutes different glyphs or calculates different line breaks.
Keep the Typst version, font set, external image assets and package dependencies in a project manifest or documented setup. Rebuild a representative output on the same environment used for publication. If generated PDFs differ, investigate before assuming that the change is harmless. A difference may be due to fonts, compiler version or metadata rather than the text itself.
For teams using CI, publish artifacts only after a controlled build and review. Avoid allowing a developer’s local preview to become the release unnoticed. A named build command and source revision make multilingual publishing easier to audit and maintain.
Security and untrusted source material
A publishing pipeline may receive Typst source from outside contributors. Treat it as source code with access to whatever the build environment permits, not as an inert text document. Review imports, dependencies and resource paths before running unfamiliar projects, and use an appropriately restricted build environment when content provenance is uncertain.
Translation should not require broad access to confidential data or developer credentials. If a sample contains sensitive information, replace it with authorized demonstration data before sharing it with external translators. Do not paste secrets into a PDF to make a screenshot look realistic; a released document can be distributed far beyond the original team.
A clean compile does not establish that the input is trustworthy or that publication rights have been granted. Maintain licensing, confidentiality and attribution checks separately from text quality. This is particularly important for research reports, patient-facing material and corporate technical manuals.
Case study: a bilingual school mathematics handout
A teacher has a Typst handout explaining algebra in English and wants a Chinese edition. The source contains mathematical variables, worked examples, a table and an automatically generated outline. The translator identifies what must stay literal, sets appropriate text-language and font behavior, then translates the explanations without changing the algebraic relationships.
The teacher verifies that variable definitions match the equations and that students receive the same task in both editions. The typesetter checks Chinese punctuation, CJK font coverage and paragraph breaks. If a step becomes longer, the solution layout may change, but the reasoning should not be compressed into an ambiguous shortcut.
The final PDF is printed and tested by reading the instructions, completing a sample question and finding a referenced section. This measures the learner’s practical experience rather than the aesthetic similarity of two pages.
Case study: an Arabic laboratory procedure
A laboratory team translates a Typst procedure with Arabic explanations and English instrument commands. The commands must remain copyable and exact. The editor checks the order of steps, safety warnings, chemical concentrations and device labels. A Typst build owner reviews directionality and font fallback on mixed-script lines.
One command contains a path and a number in parentheses. It looks correct in the editor but appears visually reversed in a PDF viewer. The team isolates the smallest problematic example, reviews text direction and source character order, and recompiles. It then verifies that copied commands remain correct and that assistive technology presents the instruction meaningfully.
The release is approved only after language, technical and layout checks agree. Preserving a command’s exact bytes matters more than matching the original page’s appearance.
Case study: a Spanish scientific report
A research institute translates a Typst report into Spanish. Its plots and bibliography are generated from approved source assets, while the narrative describes statistical results. The translator uses a terminology glossary and keeps labels and citation keys stable. The analyst verifies every percentage, unit and uncertainty expression.
A longer translated chart caption pushes the bibliography to another page. This is a layout issue, not a reason to delete the sample-size qualification. The typesetter adjusts the layout within approved constraints, then regenerates the outline and checks all internal references. The source-to-translation revision is recorded.
The final artifact is inspected for selectable text, font coverage, bookmarks, citation links and table readability. The institute can then state which source revision the Spanish edition represents and which parts were independently reviewed.
Case study: a multilingual regulatory appendix
A manufacturer publishes a regulatory appendix with product classifications and defined terms. Legal scope depends on exact wording and version date. Translators should not replace jurisdiction-specific terminology with a local-sounding phrase unless the publisher has authorized that interpretation. Machine identifiers and product codes remain exact.
The Typst document includes tables and footnotes referencing statutory definitions. A misplaced note can change how a reader understands a category. Review the note’s position, table association, units and cross-reference destinations in the final PDF. A compiler pass cannot judge whether a legal exception has been faithfully conveyed.
Use qualified legal and technical reviewers for consequential wording. Separate the translation’s publication date from the source law’s commencement date and make limitations visible. Typesetting is the delivery mechanism for the content, not a substitute for authority over the content.
Case study: a Japanese software manual
A software provider translates a Typst manual for Japanese users. It includes command-line examples, headings, illustrations and a bibliography of technical standards. The language editor translates explanatory prose but protects commands, flags and citation IDs. The build owner checks font coverage, Japanese punctuation and line breaks around Latin identifiers.
During review, a translated heading grows longer and wraps, altering the outline spacing. Rather than shortening the phrase until it becomes vague, the team adjusts heading presentation and verifies the bookmark hierarchy. Several URLs are also checked to ensure punctuation is not accidentally included when copied.
The final user test asks a Japanese reader to locate a procedure, understand its warning and copy an example command. That practical exercise verifies information access, not just visual presentation.
Case study: a distributed translation team
Contributors on Windows, macOS and Linux create editions in different languages. The project chooses a supported Typst version and documents font dependencies. All contributors can compile a representative test file, but final release artifacts are built in a controlled environment to avoid inconsistent font substitution and page breaks.
Each translation pull request identifies changed prose, machine-facing content, figures and references. Reviewers evaluate semantic fidelity separately from layout. When the compiler version changes, the project runs a baseline comparison before mixing the upgrade with major translation revisions. This makes unexpected output differences easier to investigate.
The publishing team records the approved source revision and output checks, then distributes each edition through clearly named links. Readers receive a dependable document, while maintainers retain a clear explanation of how it was produced.
Troubleshooting: missing characters in the PDF
When a PDF shows boxes, blank spaces or unexpected glyphs, inspect the actual source characters and the font inventory. Run typst fonts in the rendering environment and compare the selected font stack with the scripts the page uses. Determine whether the issue concerns coverage, fallback, incorrect source encoding or an unsuitable font feature.
Do not replace every missing non-Latin character with transliteration as a quick fix. The target audience may require the original script for names, technical concepts or faithful quotations. Choose fonts with appropriate coverage and licensing, then recompile and test the affected pages. Verify copied text as well as visual appearance.
Add the problematic string to a regression sample so later changes do not reintroduce the fault. Check uncommon characters, symbols and punctuation alongside ordinary words. A single successful heading is not sufficient evidence for a whole multilingual book.
Troubleshooting: reference or outline mismatch
If a reference points to the wrong section, check whether the target label changed, a heading was deleted, or the document structure was altered. If the outline displays unexpected entries, inspect heading levels and the outlined settings. Do not solve these problems by hard-coding page numbers that will break again when the text reflows.
Reduce the document to the smallest reproducible example containing the relevant heading, label and reference. Then reintroduce the surrounding structure once the cause is understood. The Typst heading and outline documentation provides the supported model for these relationships; use it rather than relying on arbitrary visual hacks.
After repairing the source, compile the complete document and test the PDF bookmarks, contents list and cited sections. Ask a reader to navigate the document as intended. Structural consistency is an important part of translation because it helps people locate the information they are looking for.
Troubleshooting: local and production PDF differ
An author may see one layout locally and another from CI. Compare the compiler version, font inventory, input paths, image assets, package dependencies and configuration. Translation length may expose a difference that was invisible in the shorter English edition. A layout discrepancy is not necessarily an error in the translated words.
Generate a small test document with the affected language, font and page settings, then compile it in both environments. Record the difference and adjust the supported build setup. Resist the urge to manually rearrange every affected page before identifying the environmental cause; that can create fragile layout rules.
Rebuild the full artifact in the release environment and review substantive changes, especially clipped text, altered pagination and missing glyphs. The delivered file should be the exact artifact that passed quality assurance, not a different local copy.
Frequently asked questions
Is Typst a translation engine?
No. Typst is a typesetting and document-compilation system. It can render multilingual text when source, fonts and configuration are suitable, but it does not determine the correct translation of complex prose, scientific findings or legal terms. Human linguistic and subject review remain essential.
What is the basic Typst compile command?
A common starting command is typst compile document.typ, assuming an appropriately installed compiler and valid input. Check the current command help for output formats and other options. The safe publication workflow includes source revision control, font consistency and inspection of the resulting artifact.
Do I need different fonts for every language?
Not necessarily, but every character and symbol used must have suitable glyph coverage. A planned font stack can combine families when appropriate. Test the actual build environment and inspect the PDF, particularly for CJK, Arabic, Indic scripts, mathematical notation and less common punctuation.
Can changing the text language translate a document?
No. Language settings guide text processing and potentially language-sensitive labels. They do not replace human-authored paragraphs. Use the correct settings in addition to translating and reviewing the prose, not instead of translation.
Why does the PDF page count change after translation?
Different languages have different text lengths and line-breaking patterns. Font metrics and table labels also affect layout. A changed page count can be normal. Recheck the outline, references and pagination rather than forcing identical page lengths at the expense of readability.
What happens if I translate a citation key?
References may stop resolving or point to unintended records. Preserve bibliography identifiers unless the entire citation system is deliberately migrated and tested. Translate surrounding discussion and apply a documented policy to visible titles, without inventing bibliographic details.
How do I protect RTL commands?
Keep the command’s underlying character sequence and syntax exact, apply appropriate direction handling and test the rendered output. Copy representative commands from the final PDF to verify the bytes. Ask a reviewer familiar with the language to inspect mixed punctuation, paths, numbers and labels.
Does a successful compile prove a PDF is accessible?
No. Compilation establishes that an artifact was produced under the chosen conditions. Font legibility, reading order, bookmarks, descriptive alternatives, keyboard usability and copyable text require separate inspection. Use appropriate accessibility tools and human testing for the intended audience.
Can Typst be used for localized scientific reports?
Yes, provided the project manages source revisions, data, equations, citations, fonts and rendering quality. Translators should preserve scientific meaning while allowing necessary typographic adaptations. A subject specialist must verify numerical claims and conclusions separately from layout.
Should teams match the source PDF page by page?
Usually the more important target is equivalent meaning, navigability and readable design. Exact page matching may be required by a particular publication contract, but should not be assumed. If pagination changes, review references and navigation; do not remove necessary content to conceal reflow.
Final quality-assurance checklist
- The correct source revision, Typst version and release environment are recorded.
- Language, region, direction and font settings suit the actual text.
- Commands, markup functions, paths, labels and bibliography keys remain valid.
- CJK, RTL, accents, mathematical glyphs and uncommon Unicode characters display correctly.
- Headings, outlines, bookmarks, captions and internal references match the new layout.
- Tables, measurements, equations, figures and legal qualifications retain their meaning.
- The document is readable at realistic print and screen sizes.
- Text selection, copy-paste, navigation and accessibility have been tested as applicable.
- Native-language and subject specialists approved consequential content.
- The exact final PDF or other output was built and verified from the approved revision.
Primary references and further reading
Review the official Typst repository and compiler overview, Typst text and language settings, Typst heading reference, Typst outline documentation, and Typst bibliography guide. Confirm CLI flags in your installed release. For a related but distinct publishing workflow involving Quarto projects, generated labels and computational execution, see eduKateSG’s Quarto CLI localization guide. This article focuses specifically on Typst source, language-aware typesetting and output fidelity.