How do you translate Quarto documents, reports and websites while preserving code results, figure references, navigation and publication behavior? This Quarto CLI localization guide covers lang, language, _language.yml, document metadata, quarto render, cross-reference captions, computational output, project configuration, Unicode typesetting, and practical quality assurance. It is for researchers, educators, technical writers, publishers and multilingual teams creating usable editions of scientific or instructional material.
Quarto combines authoring formats and document-processing systems, and may execute code to produce tables, plots and results. Translating a Quarto page is therefore not only replacing prose. Editors must separate human-facing sentences and interface labels from program logic, data, bibliography identifiers, equations and build configuration. A translated report can look polished while silently citing the wrong figure, publishing stale results, or describing a computation that its code does not perform.
Start with the actual audience and output format. Confirm whether the document becomes HTML, PDF, slides, a book or a website; identify its source revision and runtime; set an appropriate language tag; and render a representative sample before scaling the work. Verify captions, navigation, citations and accessibility in the delivered artifact. The aim is a reader who can understand both the explanation and the evidence, whatever language is used.
Quick reference: a safe Quarto translation workflow
- Identify the maintained Quarto CLI version and review
quarto --help. - Keep document text, executable code, data and machine keys in separate review scopes.
- Set the source language with the
langoption using an appropriate BCP 47 language tag. - Use
languageand supported translation YAML to adjust generated labels where needed. - Distinguish
_quarto.ymlproject settings from a document’s YAML front matter. - Run
quarto renderagainst a controlled project or document revision. - Understand
execute: freezebefore trusting previously rendered computation. - Check figure, table, equation and listing references in every target output.
- Test search, sidebars, menus and cross-language destinations on actual websites.
- Review localized PDF fonts, hyphenation and reading order separately from HTML.
Quarto is a publishing system, not a translation engine
Quarto helps authors turn Markdown-oriented source, code and metadata into published documents. Its CLI can render and preview projects, but it does not independently decide whether a translated scientific claim matches the original study. A perfectly successful render does not prove the page’s conclusions are accurate. Technical and language reviews still need to compare statements with data and authorized source material.
The distinction becomes especially important when prose describes numerical results generated by code. A translator might adapt a sentence about a 12 percent increase, while a revised dataset now produces a different value. The build may succeed, yet the narrative becomes outdated. Keep track of which claims are static explanations, which cite computed outputs, and which require deliberate synchronization when inputs change.
For education, teach readers this separation clearly. Quarto owns document building and some localized labels; authors own meaning; analysts own calculations; project maintainers own reproducible environments. A publication workflow should collect evidence from each layer instead of treating one green build as a universal certificate of correctness.
Identify the project, revision and output
Before translating, locate the authoritative .qmd or other supported source file and identify whether it belongs to a larger project. Check the project’s configuration, input data, filters and extensions. Record the Quarto version and the intended output formats. A single page may be rendered inside a website, book or standalone report, and those contexts can change navigation and shared metadata.
Suppose a lecturer shares a PDF and asks for a Spanish edition. If the source is actually a Quarto book chapter, translating only text extracted from the PDF risks losing working references and updateability. Start from the maintained source where possible, then map the intended Spanish artifact to the original chapter revision. Preserve the publication date and clearly identify any adapted examples.
Do not assume that every local rendering represents the release. A preview may use a different project profile or environment from the production site. Confirm which configuration is authoritative, what assets are included, and whether external resources are available. A traceable source-to-output relationship makes translation corrections far less expensive.
Use the correct document language tag
Quarto’s lang document option identifies the main language, following language tags such as en, en-GB, fr or pt-BR. It influences language-sensitive document processing and generated text. Set it deliberately rather than relying on the default English language. Distinguish region-specific variants where they affect terminology, spelling, dates or publication conventions.
A Portuguese report for Brazil may require different editorial wording from an edition for Portugal. Both can be understandable, but the intended audience should be explicit. A tag is not a substitute for localization; setting pt-BR does not magically translate every paragraph. The source text, metadata and generated labels must still be reviewed by someone who knows the language and subject.
After rendering, inspect the emitted document’s language metadata and the behavior of generated elements. Screen readers may depend on accurate language declarations. Hyphenation and typographic conventions can differ across PDF engines. A correct lang value is a useful foundation, but the rendered file must demonstrate the expected behavior.
Distinguish lang from language configuration
Quarto documents have both lang and language facilities with related but different purposes. The official document-language guide explains language tags and the option for overriding generated labels. Treat these keys as configuration syntax, not translated words. The human-facing values may be localized, but altering the key names themselves can make the configuration invalid.
For example, a report might use a French main-language tag and a custom label for the author line or a particular caption. The project may place overrides at the document or project level. Review which setting takes precedence for the chosen format rather than copying a small example into a complex repository and assuming every caption changes.
Test the result in each output format that matters. A label override useful for HTML may not fully determine LaTeX or another PDF engine’s behavior. If a label remains untranslated, investigate the output pipeline and supported translation entry rather than replacing the word directly inside generated HTML or PDF.
Work safely with _language.yml
Quarto documents a translation YAML mechanism and the possibility of a project-root _language.yml file for custom generated labels. This is useful when default translations do not match a publication’s style or a language lacks full coverage. The key names represent Quarto’s interface contract; the values represent human-facing labels. Do not swap these roles.
A translation file may contain labels for author, publication date, callouts, figures or other interface elements. Each label should be meaningful in context, grammatical when combined with numbers or names, and consistent with the broader style guide. A literal word-for-word translation can fail if the label normally needs a different order or punctuation in the target language.
Use a maintained default-language template as reference, record the actual Quarto version, and review the generated result. Avoid inventing YAML keys that appear sensible but are not recognized. When the system does not expose a needed translation, use a documented project-supported customization and explain the limitation to the editorial team.
YAML front matter is both text and configuration
YAML front matter often contains a translatable title, subtitle, abstract and author details alongside machine-facing keys and numeric options. It may also specify lang, formatting, citations or execution controls. Translators should be given an explicit map of values they may change. A successful translation of a title is not a reason to edit the configuration key that stores it.
For example, title remains title in the source while its value becomes a natural target-language phrase. A path to a bibliography file or CSS resource usually remains unchanged unless the project deliberately defines a language-specific file. A locale’s visible title can be adapted, but the underlying document identity and edition linkage should remain traceable.
Validate the YAML after any structural edit and then render the output. Errors caused by tabs, quoting, colon characters or incorrect nesting can prevent publication. Even without syntax errors, an incorrect tag or inherited option can produce misleading metadata. Review the configuration semantically as well as syntactically.
Render a single document before a full project
The Quarto CLI supports commands such as quarto render document.qmd for an individual document and quarto render for project-level output. Start with a representative target-language document. Confirm that dependencies resolve and that captions, links and images appear correctly. A single-file render offers a manageable debugging surface before a multilingual build becomes complicated.
A local render is not necessarily equivalent to a global project render. Quarto’s project processing and execution handling may differ depending on the target and configuration. The official execution documentation notes important distinctions in how freeze behavior interacts with global and incremental renders. Treat those as production concerns rather than implementation trivia.
After a successful sample, render the full intended deliverable and compare it against a source-language control. Inspect differences in navigation, search index, resource paths, number references and page ordering. The complete project needs testing because a single chapter can pass while shared elements are still wrong.
Preview is for inspection, not final acceptance
Previewing a Quarto website or document is useful for fast feedback, especially while rewriting headings and prose. But a development preview may use local paths, cached assets or permissions unavailable to public readers. Make preview one part of a sequence that includes the final production build and an actual published-page check.
Imagine a multilingual classroom website whose Spanish page looks correct in a local preview. After deployment, its stylesheet path breaks because the locale directory has a different base URL. The issue may not appear while running from the project root. Check the deployed path, navigation links and browser console as well as the rendered page.
When reviewers use screenshots, include the edition and revision so a later change is not judged against obsolete evidence. Screenshots are helpful for visual layout, but cannot prove copyable code, keyboard operation, link destinations or accessible semantics. Combine them with task-based interaction checks.
Understand frozen computations
Quarto provides an execution freeze mechanism for managing when computational documents are rerun during project rendering. The official documentation distinguishes global project builds from incremental single-document renders. The purpose is to avoid unnecessary expensive execution, but it also creates a responsibility to know whether visible results reflect current data and code.
A translation team may alter only narrative prose while reusing frozen output. That can be reasonable when the numerical results and source revision are unchanged. If the input data or code has changed, previously frozen output may be stale. Do not assume that changing a description will automatically regenerate the evidence it refers to, or that freeze: true is a reproducibility guarantee by itself.
Record which outputs were computed, from which inputs, under which environment. If the translation changes interpretive statements, compare them against the actual output displayed. Rerun the necessary calculations using an authorized, safe environment before publication whenever the supporting evidence may have changed.
Distinguish freeze from computational cache
Freeze and cache solve related but different execution problems. A cache may store computation results based on source or dependency conditions, while freeze controls reuse in the project-render workflow. Authors should understand which mechanism is active, how results are invalidated, and what must be done when data changes. Translators should not attempt to repair mismatched results by editing generated HTML.
Consider a statistical notebook where a chart is generated from a monthly dataset. The English edition reflects October data, but a localized narrative is rewritten to refer to November. If the calculation still shows October, the page is internally inconsistent. The right repair is to reconcile data, computation, and language, not merely to refresh formatting.
For a project with many contributors, include a data provenance note and a build manifest. Report the Quarto version, key packages, source commit and execution policy. The reader may never see those technical details, but the publisher needs them to maintain trustworthy multilingual scientific explanations.
Protect code while translating code comments
Quarto can contain executable cells in languages such as Python and R. Those cells may depend on exact names, indentation and syntax. A translator may have authority to edit Markdown descriptions but not computation. Establish a clear boundary between executable instructions, human-readable comments and outputs. Do not assume that text surrounded by a code fence is free prose.
A plot-generating command may use a data column whose English-sounding name looks translatable. Changing it within code can make the computation fail. The surrounding paragraph can refer to the column using a localized descriptive phrase while the actual key remains exact. If the project chooses to localize sample data labels, treat that as a deliberate analytical change with tests.
Check both code that should run and code shown as illustrative source. Copyable examples require technical accuracy even when they are not executed in the document. Error messages and displayed outputs may be translated in a caption, but should not be falsified to imply that the underlying software produces different results.
Numbers, dates and units in research writing
Scientific and educational reports combine precise quantities with language-sensitive number presentation. Decimal punctuation, thousands separators, unit spacing, date formats and time zones may vary by locale. Translate the presentation without changing the underlying measurement. Always preserve the distinction between percentages and percentage points, estimates and observed values, and units with different magnitudes.
If a figure shows a change from 10 percent to 12 percent, an explanation describing a 2 percentage-point increase differs from claiming a 2 percent relative increase. A translation can have correct spelling and a successful render while still communicating the wrong quantity. Compare narrative claims against the figure or table, not merely against isolated source words.
Use a consistent style appropriate to the audience, and keep units explicit. For worldwide content, give dates in unambiguous form where misunderstanding would matter. A published report should let readers understand when the data were collected and whether an amount is local currency, converted currency or a unitless ratio.
Figure captions and cross-references
Quarto offers generated figure and table references. The document-language settings influence localized labels, while cross-reference syntax and identifiers connect the text to targets. Preserve reference identifiers unless a planned migration updates every dependent link. Translate caption prose, but ensure the figure cited in the sentence is still the one the reader sees.
A common failure occurs when a translated paragraph says “see Figure 3,” while the rendered build numbers the image differently. Prefer the project’s supported cross-reference mechanism rather than hard-coded numbers where appropriate. Verify captions, references and list-of-figures entries after rendering. A reference that appears grammatically correct can still point to the wrong evidence.
Make sure alt text and surrounding description carry the important information for users who cannot see the image. A translated caption alone may not make a chart accessible. Review visual legends, axis labels, color-dependent distinctions and data sources as separate content elements.
Tables and computed output
Tables in Quarto can be authored directly or generated from code. Translators should distinguish structural table syntax, computed data and human-facing column labels. A table may look tidy in a Markdown editor but become hard to use when translated labels are longer. The output format matters: a PDF table may overflow, while HTML may wrap or scroll.
Suppose a table lists confidence intervals and units. A translator must preserve the values and the meaning of the interval, including whether endpoints are inclusive or estimates are rounded. If the data are generated, edits to labels may belong in code or configuration rather than in the generated table. Trace the source before changing the artifact.
Review table headers, data-cell associations, footnotes and screen-reader behavior. Test the narrowest supported screen width. If labels become unreadable, consider an approved layout adaptation rather than deleting essential terms to fit the original English column width.
Mathematics, symbols and equations
Mathematical expressions are not ordinary sentences. Symbols, variable definitions, equation numbers and references must remain internally consistent during translation. A prose explanation may change grammatical order, but replacing a variable name or altering a mathematical operator can invalidate the argument. Protect equations and review explanations with a subject specialist.
An English sentence might say “where n is the sample size.” In a target language, the explanation may move to a different position or need a clearer noun phrase. The symbol n remains the same unless the whole document deliberately adopts a different notation scheme. Captions and nearby text should use the same interpretation of all symbols.
A Quarto build can render an equation successfully even when its accompanying explanation is logically false. Compare the mathematics with the prose, verify numbering and references, and test legibility in PDF and HTML. Accessible math descriptions may need additional review beyond visual correctness.
Citations and bibliographies
Quarto supports citation workflows through its publishing stack. A translator should preserve stable citation identifiers and source attribution while adapting surrounding prose. Do not translate a DOI, citation key, URL or publication identifier into a phrase that can no longer be resolved. Bibliographic styles and localization conventions can affect the displayed result.
A paper title may have an official translated title or no recognized equivalent. Choose an editorial policy for titles, transliterations and explanatory translations. Do not invent bibliographic metadata or convert uncertain authorship into a confident claim. Where a source has multiple editions, identify which one supports the statement.
After rendering, inspect in-text citations, bibliography entries, note numbering and hyperlinks. Confirm that a reader can trace the evidence behind important scientific and historical statements. A successful bibliography build is not a substitute for checking whether the cited work actually supports the translated claim.
Translate website navigation as its own layer
A Quarto website can contain a navbar, sidebar, search, page navigation and links to source repositories. These are shared interface elements, not merely paragraphs within individual documents. Translating content without translating navigation leaves readers in a mixed-language environment and may send them unexpectedly to a different language edition.
Create a clear information architecture for the target audience. Check page titles, sidebar labels, section ordering and navigation destinations. Do not automatically duplicate an English link when a localized destination exists. If a page has not yet been translated, label the fallback honestly so the reader understands the language change before opening it.
Quarto website navigation configuration is documented separately from document-language labels. Review _quarto.yml and relevant page metadata while preserving machine-facing keys. Test the deployed website rather than assuming a rendered source file guarantees a coherent multilingual navigation experience.
Search and discoverability
Search is valuable only if it helps a reader find the appropriate page and section in the intended language. A documentation site may have English and target-language material in separate paths or deployments. Indexing arrangements can vary; do not claim that Quarto automatically manages every multilingual search scenario. Verify the actual search implementation and its treatment of Unicode.
A Japanese reader searching a technical term may expect the Japanese title, but the page might contain only the English term in a code example. Review page titles, descriptions, glossary terms and useful synonyms. Keep SEO language natural and precise; keyword repetition is not a substitute for explaining the concept correctly.
Confirm canonical and alternate-language link behavior through the publishing environment if the project uses them. Search snippets, social previews and internal results should not misrepresent the language or freshness of a page. Ask a reviewer to follow a realistic query all the way to the correct section.
PDF output requires its own language review
PDF is not simply a screenshot of HTML. Fonts, hyphenation, line breaking, page numbering, headers, tables and links behave differently. Quarto’s document-language documentation notes the involvement of downstream engines for some PDF language rules. Teams must test the exact PDF pipeline rather than transferring assumptions from the web preview.
For a report in Arabic, Hebrew, Hindi or Japanese, font availability and script shaping can determine whether the result is legible. Inspect the generated PDF using a suitable viewer, and check copied text, bookmarks, mathematical characters, table widths and reading order. A visually attractive first page does not guarantee that every page survives a long document.
If PDF accessibility matters, evaluate tagging and reading sequence with appropriate tools and human review. A PDF can render cleanly while making headings or figures difficult to navigate with assistive technology. Include these checks in the acceptance criteria instead of considering them optional polish after the deadline.
HTML accessibility and screen readers
Accessible HTML relies on semantic headings, meaningful links, proper table structure, image alternatives and accurate language metadata. Quarto provides document machinery but cannot make poorly written alt text or confusing navigation meaningful. Review the translated page as a reader would use it, including keyboard-only interaction and a screen reader where practical.
A link labeled “click here” becomes even less useful when separated from surrounding context in a screen-reader link list. Translate destination-based labels. Avoid using color alone to differentiate chart categories, and verify that code blocks can be navigated and copied. Where a complex chart cannot be expressed adequately in a short alt attribute, provide a substantive text explanation nearby.
Test representative pages, not only the homepage. Long scientific reports often hide accessibility problems deep inside captions, lists, equations or callouts. A successful Quarto render gives the team a working artifact to inspect; it does not eliminate the need for inclusive editorial design.
External dependencies and offline reproducibility
Quarto projects can depend on programming packages, fonts, extensions, remote data, images and bibliographies. A local translation render may fail when a collaborator has different dependencies or restricted network access. Identify external requirements before publication, and avoid assuming that everyone can reproduce an environment configured only on the original author’s computer.
For a translated training manual, separate values that must be recomputed from static instructional prose. If the publication is intended for offline distribution, test it without a network connection. Embedded links may remain, but critical instructions should not require an inaccessible third-party service merely to understand what to do.
Keep a dependency manifest, version control and simple build instructions. Where licensed or restricted assets are involved, verify that translation and redistribution permissions cover the intended format and region. A technically successful build does not itself grant intellectual-property rights or permission to publish sensitive datasets.
Scenario: translating a classroom textbook chapter
A university instructor has a Quarto chapter containing explanations, mathematical notation and short R calculations. The target edition is French. The editor begins with a stable source revision, marks computations as protected and translates instructional prose with a disciplinary glossary. The chapter’s lang is set appropriately, and generated labels are checked.
The reviewer compares equations and numeric outputs against the source, renders the chapter, and verifies that every exercise instruction makes sense in French. A reference to a figure must still point to the same visual evidence. If the translated explanation needs more space, the layout may adapt without changing the calculation itself.
The department then tests both HTML and PDF, including figure captions, bibliography and accessibility. The approved edition records the underlying source revision so a future numerical change triggers a proper review. The result is not merely a readable translation but a dependable teaching resource.
Scenario: an international research report
A research institute releases a Quarto report in English and Spanish. The report contains computed charts using confidential intermediate data. Translators need the explanatory text, captions and approved aggregated outputs but should not gain unnecessary access to the raw dataset. The workflow separates permitted data from language tasks and uses a controlled build environment.
The team checks date formats, statistical terms and whether claims accurately represent chart values. If calculations are frozen, the project records exactly which source and data revision produced them. Translators do not edit images to make numbers appear consistent with rewritten prose. Any inconsistency is escalated to the research owner.
The final publication is reviewed for accessible charts, working references, consistent citations and correct metadata. Each edition explains its reporting period and limitations. Scientific transparency depends on preserving the logic behind conclusions, not on making every sentence follow the same grammatical pattern.
Scenario: a multilingual documentation website
A software team maintains a Quarto site with an English reference and several translated tutorials. It wants users to navigate to the same topic in the correct language. The team must map content equivalents, not simply prepend a locale path to every URL. Some pages have no translation; others have changed titles and anchors.
Editors verify translated menus, section headings, search behavior and fallback labels. A command example remains consistent across languages, while surrounding instructions are localized for the audience. Build tests confirm that links and assets work after deployment to the intended host. Search results should identify the actual language and destination.
A final reader test asks someone unfamiliar with the project to find an installation procedure, run a safe example and return to the reference section. That journey reveals navigation defects that a source-file spell check or standalone render would miss.
Scenario: a report revised after translation began
A report’s English source changes during a translation cycle: one figure receives new data and its interpretation is revised. The Spanish edition still references the old result. The Quarto build passes because the prose and figure are syntactically valid. The problem is a revision mismatch, not a rendering failure.
The publisher should maintain source-to-translation revision mapping and identify which claims depend on changed data. A translator receives the revised source passage, the verified figure and a note explaining the consequence. Where calculations are frozen or cached, the team checks whether the output is genuinely current before making claims in the new edition.
Do not quietly change only a number in the target-language sentence without examining context. The direction, uncertainty, scope or conclusion may also have changed. The publication gate should verify equivalence of evidence and meaning, followed by a fresh render and link inspection.
Scenario: adapting a callout and reference label
A technical manual uses a Quarto warning callout with a localized caption. The default generated label is linguistically acceptable but too mild for a dangerous procedure, so the team investigates documented language overrides. It must preserve the callout’s severity and position while changing only appropriate human-facing text.
The source may contain a machine token for the callout type and separate prose inside it. Editing the token as though it were a sentence can break rendering. A legitimate label override belongs in the supported configuration layer. Test both the localized label and the warning body in HTML and PDF, because output engines can display them differently.
Ask a reviewer whether a reader can identify the prohibited action before encountering the command. The success criterion is safe comprehension. A label that is perfectly localized but appears after the dangerous step is not good technical documentation.
Scenario: a worldwide public-health dashboard
A public-health report created with Quarto contains dates, rates, maps and narrative guidance. Its audience spans regions with different local date conventions and emergency procedures. Editors must distinguish general research interpretation from jurisdiction-specific instructions. Do not rewrite a global report into local legal advice without authority.
Each target edition should explain measurement units, denominator populations, uncertainty and data refresh date. If maps or dashboards embed text, the team identifies whether those labels are generated from code or stored separately. A translation should not alter the underlying case counts or suggest greater certainty than the evidence supports.
Review the final output on mobile and assistive technologies, and test whether links to local public-health resources are clearly labeled. The document’s numerical accuracy, language clarity and audience relevance need separate checks. No single render command can certify all three.
Troubleshooting: the wrong language still appears
If a translated document displays English captions, inspect the lang setting, any language overrides and the Quarto version. Determine whether the string originates from Quarto itself, a downstream formatter, an extension, custom content or an image. Only then choose the correct correction mechanism. A blind text replacement in generated output will likely disappear on the next render.
Build a minimal test document with one figure, one table and one callout. Set the intended language and render it using the production format. Compare results with the official language documentation. If a particular label cannot be customized through the intended layer, record the limitation and choose an approved publication workaround.
Test the correction in each target output. A change that fixes HTML may leave PDF unchanged because the formatting engines are different. Keep the configuration fix within source control and document it so future contributors do not need to rediscover the problem.
Troubleshooting: results differ between renders
Unexpected changes in computational output call for investigating data, code, package versions, execution environment, freeze settings and cache state. Do not assume a translation changed the mathematics. Compare an unchanged source-language control document with the target edition under the same environment, then isolate which inputs differ.
If a single-document render triggers execution while a global build reuses frozen output, the observed discrepancy can be explained by execution policy. Confirm the behavior against the official project-execution guidance for the installed version. Log which command created the release and whether computation actually ran. An unexplained chart value should block publication.
Once the cause is known, rerender from a controlled environment and compare values. Then review the explanatory sentences, captions, conclusions and abstracts that depend on those outputs. Statistical meaning must remain stable across language editions.
Troubleshooting: a localized page disappears from search
A page can render successfully but remain difficult to discover because of navigation, metadata, paths or search configuration. Check whether it was included in the deployed site, linked from the expected menu, and indexed by the site’s search setup. Inspect its language declaration, title and description. Avoid assuming that a successful local build implies public discoverability.
For a multilingual website, verify the edition’s route and whether cross-language links point to the right topic. Broken or misdirected links can result when a page’s translated heading changes anchor fragments. Rebuild and test the actual destination rather than changing only the visible label.
If a search index is external, allow for its real update process without inventing timelines or claiming automatic coverage. The quality target is a user who can find and understand the intended document, not merely a folder full of successfully generated HTML files.
Frequently asked questions
Does Quarto translate prose automatically?
No. Quarto provides publishing and generated-label localization features, but human-authored paragraphs still need translation and review. A document’s language tag cannot determine whether a scientific conclusion, safety warning or legal qualification is equivalent to the source.
What is the difference between lang and language?
lang identifies the principal document language, while language can participate in generated-label overrides and translation configuration. Their exact use is documented in Quarto’s official document-language guide. Preserve the key names and verify output behavior rather than treating them as interchangeable free-text fields.
Is _language.yml required for every translation?
No. Quarto supplies built-in translations for supported languages, while custom translation YAML is useful for additional or overridden labels. Use it when the publication requires a supported customization. Do not create arbitrary keys and assume the renderer will recognize them.
Does a successful quarto render prove the translation is correct?
No. It proves that the selected rendering process completed, subject to the actual command’s behavior. A report can still misstate numbers, omit a warning, point to the wrong figure or display a broken link. Technical, linguistic, accessibility and publication checks remain separate.
Why might figures show old values?
Frozen or cached computations, unchanged inputs, or differences in execution environment can explain stale or differing output. Investigate which calculation actually ran and which source revision produced the numbers. Do not alter the narrative to disguise unexplained computation.
Can I translate code identifiers to make examples easier?
Only when the code and data are deliberately designed to support that change and are retested. In ordinary technical documentation, preserve literal identifiers and translate the explanatory prose. Copyable examples must remain executable and accurately described.
How should Quarto websites handle missing language editions?
Make the fallback explicit. Do not present an English page as though it were a completed translation. Maintain a content-equivalence map, honest link labels and a predictable navigation path. Test deployed routes and search behavior for the actual site.
Does changing a heading affect cross-references?
It may affect generated anchors or navigation. Use stable project-supported reference identifiers when appropriate, and inspect in-body references, table of contents and incoming links after editing headings. A new translated title should not silently disconnect readers from the section they need.
Are PDFs and HTML equivalent localization outputs?
No. They use different rendering and typography paths, and PDF adds concerns such as fonts, hyphenation, bookmarks, page breaks and reading order. Test both forms if both are intended for distribution. A clean HTML preview is not evidence that a long PDF is accessible.
How should teams handle citations in translation?
Preserve traceable bibliographic identifiers and source attribution. Translate surrounding discussion faithfully and use a clear editorial policy for translated titles. Check final bibliography entries and links; a working citation key does not establish that the reference supports the claim.
Publication checklist
- The authoritative Quarto project, input files and source revision are identified.
- The main language tag and any generated-label overrides are deliberate.
- Project and document YAML remain valid and machine-facing keys unchanged.
- Computations, data inputs and frozen results have traceable provenance.
- Figures, tables, mathematics, citations and reference identifiers remain correct.
- Navigation, search, metadata and language paths lead readers to accurate destinations.
- HTML and PDF have been tested separately where both are published.
- Unicode fonts, CJK, RTL text, keyboard access and screen-reader needs are reviewed.
- Source-language, technical and editorial approvals cover the consequential claims.
- The release artifact matches the tested build and its recorded dependencies.
Primary sources and further reading
Consult the official Quarto document-language guide, Quarto project basics, Quarto managing execution documentation, and Quarto website navigation reference. Check the installed CLI help for your release. For a separate document-conversion focus, see eduKateSG’s Pandoc CLI localization article; this Quarto guide addresses project-level publishing, generated labels and the relationship between prose and computations.