How do you publish multilingual DocFX documentation without breaking API links, mixing releases or promising an automatic localization system that is not actually configured? Readers searching for DocFX translation, DocFX multilingual documentation, translated .NET API docs, localized toc.yml navigation and language-specific DocFX builds usually need a dependable publishing architecture rather than a list of translated words. DocFX builds documentation sites from content, configuration and often generated API metadata. Language editions therefore have to preserve the identity of symbols and the accuracy of the code while presenting explanations and navigation in a language readers understand.
This educational guide explains a practical approach to DocFX localization: prepare separately maintained language content, share the correct version of API metadata where appropriate, build traceable editions, review table-of-contents paths, test cross-reference UIDs, and check HTML, search and available PDF outputs. The official DocFX documentation explains configuration, TOC behavior, file-path-based URLs, templates, metadata generation and build commands. It should not be read as a promise that one universal switch will translate arbitrary Markdown, XML comments or YAML files into another language.
The safest first project is one narrowly scoped set of documentation that includes a getting-started article, an API method, a warning, a code example and a TOC link. Build both language editions from one tagged product release, verify that their reader tasks are equivalent, then scale to larger libraries. This article works through concrete defects and repairs, a four-week rollout plan and the questions a team should answer before treating an international documentation site as production-ready.
Quick answer: a reliable multilingual DocFX project
Build separate language editions from the same technical release, translate editorial content and navigation, retain valid API identifiers and xrefs, and test deployed URLs rather than only source files. Never claim that a template or route change translates the underlying engineering explanation.
Contents
- Essential DocFX localization foundations
- Thirty-one real-world QA cases
- A four-week launch plan
- Frequently asked questions
- Official references
Essential foundations before translating
DocFX is a documentation build system
DocFX uses docfx.json to define the files it transforms and assets it copies. It can render conceptual Markdown and generated .NET API reference material, among other supported inputs. Translation therefore concerns several content types with different ownership rules. A localized navigation label does not establish that conceptual pages or XML comments have been translated.
A useful way to apply this principle is to select one real document, identify its source and generated route, and write an acceptance test that another developer can repeat. Keep the test tied to a version. The goal is not superficial consistency between pages; it is consistent and verifiable technical guidance.
Separate code identity from reader language
An API UID, namespace, member name and parameter spelling are used to identify a programmatic object. Their stability makes cross-reference links meaningful. Translate surrounding descriptions and task instructions without turning UIDs or code fragments into human-language substitutes that the framework cannot resolve.
A useful way to apply this principle is to select one real document, identify its source and generated route, and write an acceptance test that another developer can repeat. Keep the test tied to a version. The goal is not superficial consistency between pages; it is consistent and verifiable technical guidance.
Plan independent edition roots
A multilingual site needs a URL design and an output plan. The DocFX configuration documents URL generation using input paths and configurable src/dest mapping. If separate builds publish into the same folder without controls, one edition can overwrite another. Prefer explicit language roots that remain stable through deployment.
A useful way to apply this principle is to select one real document, identify its source and generated route, and write an acceptance test that another developer can repeat. Keep the test tied to a version. The goal is not superficial consistency between pages; it is consistent and verifiable technical guidance.
Use the TOC as a navigation contract
DocFX supports toc.yml structures with name, href, items and uid concepts. A translated navigation title has to lead to a real matching article or API symbol. Each edition should have a table of contents that matches what actually exists, including explicit decisions for untranslated material.
A useful way to apply this principle is to select one real document, identify its source and generated route, and write an acceptance test that another developer can repeat. Keep the test tied to a version. The goal is not superficial consistency between pages; it is consistent and verifiable technical guidance.
Keep generated API metadata versioned
DocFX can generate .NET API YAML metadata from project or assembly information. The shape of that material follows the program. A translation prepared for an older SDK release may tell the reader to use members removed from the current assembly. Record and review the metadata source revision.
A useful way to apply this principle is to select one real document, identify its source and generated route, and write an acceptance test that another developer can repeat. Keep the test tied to a version. The goal is not superficial consistency between pages; it is consistent and verifiable technical guidance.
Differentiate templates from editorial text
The output template controls site appearance and may contain visible interface text. DocFX’s built-in modern template, custom styles and template metadata must be checked separately from prose pages. If a site has custom breadcrumbs, action buttons or search placeholders, those texts might be owned by the theme rather than the Markdown translator.
A useful way to apply this principle is to select one real document, identify its source and generated route, and write an acceptance test that another developer can repeat. Keep the test tied to a version. The goal is not superficial consistency between pages; it is consistent and verifiable technical guidance.
Preserve task-level technical meaning
A useful translation says precisely which command to run, which flag to choose, which result to expect and what to do when it fails. Do not replace examples with attractive but untested localized equivalents. Maintain the exact contractual syntax while explaining platform-specific behavior naturally.
A useful way to apply this principle is to select one real document, identify its source and generated route, and write an acceptance test that another developer can repeat. Keep the test tied to a version. The goal is not superficial consistency between pages; it is consistent and verifiable technical guidance.
Treat search and redirects as release features
Readers discover documentation through search, bookmarks and links from applications. A language selector is incomplete if a Japanese error message sends users to an English deprecated article. Design edition-aware routing, link validation and clear fallback notices instead of relying on manually guessed URLs.
A useful way to apply this principle is to select one real document, identify its source and generated route, and write an acceptance test that another developer can repeat. Keep the test tied to a version. The goal is not superficial consistency between pages; it is consistent and verifiable technical guidance.
Audit all supported output channels
HTML may pass while downloadable PDF or archived files contain missing characters, stale pages or wrong metadata. Test each format the project actually builds. Official PDF support and its configuration depend on DocFX release and template; confirm the version before describing an export workflow as available.
A useful way to apply this principle is to select one real document, identify its source and generated route, and write an acceptance test that another developer can repeat. Keep the test tied to a version. The goal is not superficial consistency between pages; it is consistent and verifiable technical guidance.
Maintain a revision and correction process
Translated pages are living documentation. Changes to source code, examples, security guidance or support channels can invalidate translations. Tie each edition to a release and request bilingual review of changed substantive claims, not just a mechanical count of edited strings.
A useful way to apply this principle is to select one real document, identify its source and generated route, and write an acceptance test that another developer can repeat. Keep the test tied to a version. The goal is not superficial consistency between pages; it is consistent and verifiable technical guidance.
Thirty-one DocFX translation and release QA situations
1. Docfx.json content globs
A Spanish build inadvertently includes the English Markdown tree because a broad content glob matches both directories.
Why it matters: The finished site can display duplicate pages and wrong-language search results even when individual translations are correct. Check this in the generated output because DocFX performs transformations between source files and browser pages. A review of raw YAML or Markdown alone can miss route, template and asset defects. Keep the source revision and deployment path beside the report.
A professional repair: Review build content patterns and exclusions for each edition with a clean build that lists included files. Put the correction in the source system that actually owns the content or route, then rebuild and compare the translated result with the reference release. Do not repair only the final HTML if regeneration will erase it.
Release evidence: Every published Spanish page comes from the intended source set, with no unexplained duplicates. Record the edition, DocFX version, technical revision and destination URL so the same issue can be retested when the next release ships.
2. Separate source folders
A team stores two translations under one path and manually copies files into place before every deployment.
Why it matters: Releases become dependent on memory and can silently overwrite the other language’s working files. Think in terms of the reader’s next action. After reading this passage, should they call an API, edit configuration, download a file or troubleshoot an error? Verify the translated page enables precisely that action in the targeted software release.
A professional repair: Design explicit edition source locations and version-controlled build inputs, then generate output reproducibly. Put the correction in the source system that actually owns the content or route, then rebuild and compare the translated result with the reference release. Do not repair only the final HTML if regeneration will erase it.
Release evidence: A clean checkout can build each language edition without any undocumented copying step. Record the edition, DocFX version, technical revision and destination URL so the same issue can be retested when the next release ships.
3. Language URL prefixes
Translated documentation is published at the same public paths as the English base edition.
Why it matters: Search engines, support links and browser caches cannot distinguish the two and users see unpredictable results. Do not treat a successful build exit code as a complete language approval. Build diagnostics, semantic accuracy, search relevance and links answer different questions. An issue can pass one category while remaining serious in another.
A professional repair: Give each edition stable language-specific paths and test direct navigation to nested pages. Put the correction in the source system that actually owns the content or route, then rebuild and compare the translated result with the reference release. Do not repair only the final HTML if regeneration will erase it.
Release evidence: Both language links survive a clean deployment and identify the correct edition. Record the edition, DocFX version, technical revision and destination URL so the same issue can be retested when the next release ships.
4. TOC display names
The French toc.yml shows translated labels but still links to articles that exist only in the English content tree.
Why it matters: Navigation looks localized but readers arrive at missing pages or the wrong language. Most dangerous regressions involve a boundary: editorial text beside generated API metadata, navigation beside file routing, code beside translated prose, or a PDF download beside current HTML. Include the boundary in testing instead of checking each piece in isolation.
A professional repair: Review each toc.yml name and href against the generated destination and the content-completeness map. Put the correction in the source system that actually owns the content or route, then rebuild and compare the translated result with the reference release. Do not repair only the final HTML if regeneration will erase it.
Release evidence: Every critical navigation entry opens an actual relevant page with a predictable fallback. Record the edition, DocFX version, technical revision and destination URL so the same issue can be retested when the next release ships.
5. TOC nested structure
The translated TOC drops a nested section containing critical setup prerequisites.
Why it matters: Readers may start advanced steps before completing an essential configuration. A careful reviewer compares claims with a known reference rather than inventing plausible details. The target text should preserve quantities, negation, conditions, permissions and lifecycle status exactly even when sentence structure changes substantially.
A professional repair: Compare information architecture by task rather than enforcing word-for-word matching of headings. Put the correction in the source system that actually owns the content or route, then rebuild and compare the translated result with the reference release. Do not repair only the final HTML if regeneration will erase it.
Release evidence: Readers can locate prerequisites and complete the intended workflow in both editions. Record the edition, DocFX version, technical revision and destination URL so the same issue can be retested when the next release ships.
6. TOC uid versus href
An editor replaces a DocFX uid with a translated phrase, believing the TOC’s key should match its visible label.
Why it matters: The identifier no longer resolves to the documented symbol even though its text is grammatically correct. If the corresponding topic has no finished translation, honesty is a feature. An explicit fallback and a stable authoritative page let the reader continue safely; a false impression of completeness encourages unverified decisions.
A professional repair: Keep uid values literal and translate only the human-facing name when appropriate. Put the correction in the source system that actually owns the content or route, then rebuild and compare the translated result with the reference release. Do not repair only the final HTML if regeneration will erase it.
Release evidence: The TOC resolves to the correct generated API page in a clean build. Record the edition, DocFX version, technical revision and destination URL so the same issue can be retested when the next release ships.
7. Cross-reference syntax
A Markdown author localizes the target of an xref link inside a paragraph about a .NET method.
Why it matters: The rendered link points to an unknown identifier or falls back unpredictably. Check this in the generated output because DocFX performs transformations between source files and browser pages. A review of raw YAML or Markdown alone can miss route, template and asset defects. Keep the source revision and deployment path beside the report.
A professional repair: Protect symbol UIDs and cross-reference syntax, translating the explanation surrounding them. Put the correction in the source system that actually owns the content or route, then rebuild and compare the translated result with the reference release. Do not repair only the final HTML if regeneration will erase it.
Release evidence: The hyperlink opens the same API concept in each edition’s supported navigation route. Record the edition, DocFX version, technical revision and destination URL so the same issue can be retested when the next release ships.
8. Metadata generation
A localized API page is manually written against an SDK that has since changed method parameters.
Why it matters: The documentation can promise signatures and defaults that the installed library no longer has. Think in terms of the reader’s next action. After reading this passage, should they call an API, edit configuration, download a file or troubleshoot an error? Verify the translated page enables precisely that action in the targeted software release.
A professional repair: Regenerate metadata from the intended release and compare translated commentary against the new shape. Put the correction in the source system that actually owns the content or route, then rebuild and compare the translated result with the reference release. Do not repair only the final HTML if regeneration will erase it.
Release evidence: Each stated signature and parameter name matches the released .NET assembly or project. Record the edition, DocFX version, technical revision and destination URL so the same issue can be retested when the next release ships.
9. XML documentation comments
The official method summary comes from English source comments while the target-language TOC implies complete translation.
Why it matters: Readers may overlook English warnings hidden on API pages and assume the edition is fully reviewed. Do not treat a successful build exit code as a complete language approval. Build diagnostics, semantic accuracy, search relevance and links answer different questions. An issue can pass one category while remaining serious in another.
A professional repair: Identify which API descriptions are generated from comments and define a separate reviewed translation path. Put the correction in the source system that actually owns the content or route, then rebuild and compare the translated result with the reference release. Do not repair only the final HTML if regeneration will erase it.
Release evidence: High-risk API summaries and warnings receive explicit bilingual technical review. Record the edition, DocFX version, technical revision and destination URL so the same issue can be retested when the next release ships.
10. Namespace stability
A translation changes a namespace spelling to read naturally in the target language.
Why it matters: Copying the documented using directive no longer works and cross-references become misleading. Most dangerous regressions involve a boundary: editorial text beside generated API metadata, navigation beside file routing, code beside translated prose, or a PDF download beside current HTML. Include the boundary in testing instead of checking each piece in isolation.
A professional repair: Keep assembly, namespace and type identifiers exact; translate the introductory concepts separately. Put the correction in the source system that actually owns the content or route, then rebuild and compare the translated result with the reference release. Do not repair only the final HTML if regeneration will erase it.
Release evidence: The documentation sample compiles using published library names. Record the edition, DocFX version, technical revision and destination URL so the same issue can be retested when the next release ships.
11. Overloaded methods
Two overloads are described with the same translated summary although one is asynchronous and the other synchronous.
Why it matters: Users choose the wrong call pattern, potentially missing error handling or awaiting incorrectly. A careful reviewer compares claims with a known reference rather than inventing plausible details. The target text should preserve quantities, negation, conditions, permissions and lifecycle status exactly even when sentence structure changes substantially.
A professional repair: Write distinct translated usage guidance grounded in the actual overload signatures and examples. Put the correction in the source system that actually owns the content or route, then rebuild and compare the translated result with the reference release. Do not repair only the final HTML if regeneration will erase it.
Release evidence: A developer can choose the correct overload from target-language explanation alone. Record the edition, DocFX version, technical revision and destination URL so the same issue can be retested when the next release ships.
12. Generic parameter constraints
A note about where T : class is translated as an instruction to pass a class name as text.
Why it matters: The translation changes a type constraint into a runtime argument requirement. If the corresponding topic has no finished translation, honesty is a feature. An explicit fallback and a stable authoritative page let the reader continue safely; a false impression of completeness encourages unverified decisions.
A professional repair: Compare the compiler constraint with a representative valid and invalid example. Put the correction in the source system that actually owns the content or route, then rebuild and compare the translated result with the reference release. Do not repair only the final HTML if regeneration will erase it.
Release evidence: A reviewer explains the type rule without inventing a new function parameter. Record the edition, DocFX version, technical revision and destination URL so the same issue can be retested when the next release ships.
13. Exception and status
A method throws an exception on invalid credentials, but a translated troubleshooting page says it returns false.
Why it matters: Callers might never catch the exception and misunderstand operational failure. Check this in the generated output because DocFX performs transformations between source files and browser pages. A review of raw YAML or Markdown alone can miss route, template and asset defects. Keep the source revision and deployment path beside the report.
A professional repair: Align translated error guidance with current API behavior and tested exception cases. Put the correction in the source system that actually owns the content or route, then rebuild and compare the translated result with the reference release. Do not repair only the final HTML if regeneration will erase it.
Release evidence: A target-language error-handling example succeeds on normal input and handles the documented failure. Record the edition, DocFX version, technical revision and destination URL so the same issue can be retested when the next release ships.
14. Version switcher
The German site displays the current release in navigation but sends API links to an older English package version.
Why it matters: A correct translation can still teach users to call unavailable methods. Think in terms of the reader’s next action. After reading this passage, should they call an API, edit configuration, download a file or troubleshoot an error? Verify the translated page enables precisely that action in the targeted software release.
A professional repair: Build a mapping of package version, language edition and symbol path, and crawl representative links. Put the correction in the source system that actually owns the content or route, then rebuild and compare the translated result with the reference release. Do not repair only the final HTML if regeneration will erase it.
Release evidence: Every critical link points to compatible code or clearly names an intentional older version. Record the edition, DocFX version, technical revision and destination URL so the same issue can be retested when the next release ships.
15. File-based URL calculation
A team renames translated Markdown files but assumes public paths remain the same as the source edition.
Why it matters: DocFX’s path-based URL behavior can turn those changes into broken bookmarks. Do not treat a successful build exit code as a complete language approval. Build diagnostics, semantic accuracy, search relevance and links answer different questions. An issue can pass one category while remaining serious in another.
A professional repair: Verify src/dest mapping, generated route paths and intended redirects before making translation slugs public. Put the correction in the source system that actually owns the content or route, then rebuild and compare the translated result with the reference release. Do not repair only the final HTML if regeneration will erase it.
Release evidence: Direct links to published chapters remain stable across routine content edits. Record the edition, DocFX version, technical revision and destination URL so the same issue can be retested when the next release ships.
16. Shared image resources
A diagram with English warning labels is reused in Japanese localized content without explanation.
Why it matters: The image conveys important unreviewed instructions and weakens the surrounding translation. Most dangerous regressions involve a boundary: editorial text beside generated API metadata, navigation beside file routing, code beside translated prose, or a PDF download beside current HTML. Include the boundary in testing instead of checking each piece in isolation.
A professional repair: Localize diagram source files when feasible, or provide accurate explanatory captions and alternatives. Put the correction in the source system that actually owns the content or route, then rebuild and compare the translated result with the reference release. Do not repair only the final HTML if regeneration will erase it.
Release evidence: The diagram’s actionable meaning is accessible without relying on English labels. Record the edition, DocFX version, technical revision and destination URL so the same issue can be retested when the next release ships.
17. Screenshot drift
A French tutorial contains screenshots of an old UI whose controls have been renamed in the current release.
Why it matters: Readers cannot reconcile instructions with the interface they actually see. A careful reviewer compares claims with a known reference rather than inventing plausible details. The target text should preserve quantities, negation, conditions, permissions and lifecycle status exactly even when sentence structure changes substantially.
A professional repair: Associate screenshots with product version and target locale, replacing or contextualizing stale assets. Put the correction in the source system that actually owns the content or route, then rebuild and compare the translated result with the reference release. Do not repair only the final HTML if regeneration will erase it.
Release evidence: A reviewer can follow the screenshot sequence in the tested product version. Record the edition, DocFX version, technical revision and destination URL so the same issue can be retested when the next release ships.
18. Search index mixing
A language-specific portal displays search results from all editions without indicating which one they belong to.
Why it matters: Readers may open an outdated or untranslated document after a natural-language query. If the corresponding topic has no finished translation, honesty is a feature. An explicit fallback and a stable authoritative page let the reader continue safely; a false impression of completeness encourages unverified decisions.
A professional repair: Inspect the deployed search configuration and filter or label results by language and version. Put the correction in the source system that actually owns the content or route, then rebuild and compare the translated result with the reference release. Do not repair only the final HTML if regeneration will erase it.
Release evidence: Search for a target-language task returns usable, correctly identified pages. Record the edition, DocFX version, technical revision and destination URL so the same issue can be retested when the next release ships.
19. Search synonyms
An API method retains an English identifier, but Spanish users search for the everyday task word instead.
Why it matters: Search relevance can fail even while the exact identifier is indexed correctly. Check this in the generated output because DocFX performs transformations between source files and browser pages. A review of raw YAML or Markdown alone can miss route, template and asset defects. Keep the source revision and deployment path beside the report.
A professional repair: Create natural translated entry headings and task pages linking to the stable API UID. Put the correction in the source system that actually owns the content or route, then rebuild and compare the translated result with the reference release. Do not repair only the final HTML if regeneration will erase it.
Release evidence: A native reader finds the operation without knowing the symbol name in advance. Record the edition, DocFX version, technical revision and destination URL so the same issue can be retested when the next release ships.
20. Template hard-coded strings
Custom DocFX template components include fixed English button labels and aria-label text.
Why it matters: The published shell mixes languages and assistive technology receives inconsistent instructions. Think in terms of the reader’s next action. After reading this passage, should they call an API, edit configuration, download a file or troubleshoot an error? Verify the translated page enables precisely that action in the targeted software release.
A professional repair: Audit the selected template, custom partials and JavaScript text separately from page content. Put the correction in the source system that actually owns the content or route, then rebuild and compare the translated result with the reference release. Do not repair only the final HTML if regeneration will erase it.
Release evidence: Visible and accessible controls use appropriate translated labels. Record the edition, DocFX version, technical revision and destination URL so the same issue can be retested when the next release ships.
21. UTF encoding
A Korean translation appears correct in the repository but corrupts during Markdown-to-HTML rendering.
Why it matters: Character corruption destroys search and makes commands or names difficult to interpret. Do not treat a successful build exit code as a complete language approval. Build diagnostics, semantic accuracy, search relevance and links answer different questions. An issue can pass one category while remaining serious in another.
A professional repair: Trace Unicode preservation through source, build output, web serving and exports. Put the correction in the source system that actually owns the content or route, then rebuild and compare the translated result with the reference release. Do not repair only the final HTML if regeneration will erase it.
Release evidence: Copying text from the deployed page yields the intended characters. Record the edition, DocFX version, technical revision and destination URL so the same issue can be retested when the next release ships.
22. Mixed RTL and code
Arabic text contains inline C# generics and dot-separated namespaces whose punctuation becomes visually reordered.
Why it matters: A reader can miscopy an identifier or misunderstand where an argument belongs. Most dangerous regressions involve a boundary: editorial text beside generated API metadata, navigation beside file routing, code beside translated prose, or a PDF download beside current HTML. Include the boundary in testing instead of checking each piece in isolation.
A professional repair: Inspect direction handling for code spans and mixed-script paragraphs in the actual site template. Put the correction in the source system that actually owns the content or route, then rebuild and compare the translated result with the reference release. Do not repair only the final HTML if regeneration will erase it.
Release evidence: Programmatic tokens preserve order and remain copyable while prose reads naturally. Record the edition, DocFX version, technical revision and destination URL so the same issue can be retested when the next release ships.
23. Global metadata title
The target-language site shows an English app title and footer even though every article heading was translated.
Why it matters: Visitors may misidentify the scope of the site and search snippets may not reflect its locale. A careful reviewer compares claims with a known reference rather than inventing plausible details. The target text should preserve quantities, negation, conditions, permissions and lifecycle status exactly even when sentence structure changes substantially.
A professional repair: Review supported template metadata and page-level metadata for each language edition. Put the correction in the source system that actually owns the content or route, then rebuild and compare the translated result with the reference release. Do not repair only the final HTML if regeneration will erase it.
Release evidence: The visible title, footer and search preview consistently describe the edition. Record the edition, DocFX version, technical revision and destination URL so the same issue can be retested when the next release ships.
24. Resource path collision
Two language builds copy images and scripts into a shared directory with overlapping names.
Why it matters: One edition may display the wrong diagram or stylesheet after the later deployment. If the corresponding topic has no finished translation, honesty is a feature. An explicit fallback and a stable authoritative page let the reader continue safely; a false impression of completeness encourages unverified decisions.
A professional repair: Use build destinations with controlled asset paths and verify published asset hashes and references. Put the correction in the source system that actually owns the content or route, then rebuild and compare the translated result with the reference release. Do not repair only the final HTML if regeneration will erase it.
Release evidence: Reloading both editions consistently renders their intended resources. Record the edition, DocFX version, technical revision and destination URL so the same issue can be retested when the next release ships.
25. PDF version support
A team promises a localized PDF without checking whether its DocFX version and template support the chosen PDF workflow.
Why it matters: Users receive a missing or stale download button and the release checklist wrongly marks the format complete. Check this in the generated output because DocFX performs transformations between source files and browser pages. A review of raw YAML or Markdown alone can miss route, template and asset defects. Keep the source revision and deployment path beside the report.
A professional repair: Confirm official version requirements, build the PDF explicitly, and test bookmarks, fonts and links. Put the correction in the source system that actually owns the content or route, then rebuild and compare the translated result with the reference release. Do not repair only the final HTML if regeneration will erase it.
Release evidence: A real downloadable PDF opens and matches the declared language and SDK release. Record the edition, DocFX version, technical revision and destination URL so the same issue can be retested when the next release ships.
26. Code fences and commands
A translator replaces command-line switches inside a code fence with natural words without noticing they are executable tokens.
Why it matters: Readers copy commands that fail or change option semantics. Think in terms of the reader’s next action. After reading this passage, should they call an API, edit configuration, download a file or troubleshoot an error? Verify the translated page enables precisely that action in the targeted software release.
A professional repair: Protect runnable syntax, translate explanatory comments clearly and test commands from a clean environment. Put the correction in the source system that actually owns the content or route, then rebuild and compare the translated result with the reference release. Do not repair only the final HTML if regeneration will erase it.
Release evidence: Commands run as documented with correct output in the target locale’s tutorial. Record the edition, DocFX version, technical revision and destination URL so the same issue can be retested when the next release ships.
27. Language selector fallback
A page has no reviewed Polish equivalent, but the selector silently sends the visitor to an unrelated Polish home page.
Why it matters: The user loses context and may assume the target method has disappeared. Do not treat a successful build exit code as a complete language approval. Build diagnostics, semantic accuracy, search relevance and links answer different questions. An issue can pass one category while remaining serious in another.
A professional repair: Use a clear fallback notice and an explicit base-language counterpart where no true equivalent exists. Put the correction in the source system that actually owns the content or route, then rebuild and compare the translated result with the reference release. Do not repair only the final HTML if regeneration will erase it.
Release evidence: Language switching preserves the topic or clearly explains the missing translation. Record the edition, DocFX version, technical revision and destination URL so the same issue can be retested when the next release ships.
28. Accessibility structure
The translated DocFX heading order is altered so screen-reader users jump from H2 to an unlabeled callout.
Why it matters: Visual review can pass while page navigation becomes confusing for assistive technology. Most dangerous regressions involve a boundary: editorial text beside generated API metadata, navigation beside file routing, code beside translated prose, or a PDF download beside current HTML. Include the boundary in testing instead of checking each piece in isolation.
A professional repair: Check semantic heading levels, link names, focus order and document language in representative pages. Put the correction in the source system that actually owns the content or route, then rebuild and compare the translated result with the reference release. Do not repair only the final HTML if regeneration will erase it.
Release evidence: A keyboard and screen-reader reviewer can complete the same documentation task. Record the edition, DocFX version, technical revision and destination URL so the same issue can be retested when the next release ships.
29. Redirect migration
After moving French content to new paths, a deployment drops redirects used by prior release notes.
Why it matters: Existing support tickets and saved URLs lead to errors, weakening long-term trust. A careful reviewer compares claims with a known reference rather than inventing plausible details. The target text should preserve quantities, negation, conditions, permissions and lifecycle status exactly even when sentence structure changes substantially.
A professional repair: Plan redirects as part of the edition migration and test external deep links from earlier versions. Put the correction in the source system that actually owns the content or route, then rebuild and compare the translated result with the reference release. Do not repair only the final HTML if regeneration will erase it.
Release evidence: Previously published important URLs reach their intended content or an explicit archive notice. Record the edition, DocFX version, technical revision and destination URL so the same issue can be retested when the next release ships.
30. Broken xref error
A build logs an unresolved cross-reference warning, but the team ignores it because the landing page looks fine.
Why it matters: A critical parameter explanation may link nowhere, and translation makes recovery harder. If the corresponding topic has no finished translation, honesty is a feature. An explicit fallback and a stable authoritative page let the reader continue safely; a false impression of completeness encourages unverified decisions.
A professional repair: Review build diagnostics and treat unresolved high-value symbols as release blockers. Put the correction in the source system that actually owns the content or route, then rebuild and compare the translated result with the reference release. Do not repair only the final HTML if regeneration will erase it.
Release evidence: An edition-specific link crawl finds no broken links to its essential symbols. Record the edition, DocFX version, technical revision and destination URL so the same issue can be retested when the next release ships.
31. Translation corrections
A bilingual developer finds a wrong statement about retry timing, but the editorial workflow tracks only typographical edits.
Why it matters: The source and translated versions can diverge without a traceable approval or retest. Check this in the generated output because DocFX performs transformations between source files and browser pages. A review of raw YAML or Markdown alone can miss route, template and asset defects. Keep the source revision and deployment path beside the report.
A professional repair: Record the affected behavior, evidence, SDK version, corrected language and reviewer decision. Put the correction in the source system that actually owns the content or route, then rebuild and compare the translated result with the reference release. Do not repair only the final HTML if regeneration will erase it.
Release evidence: Both editions lead to the same safe retry behavior after the fix. Record the edition, DocFX version, technical revision and destination URL so the same issue can be retested when the next release ships.
A four-week implementation plan
Week 1
Week one: choose a fixed SDK release and inventory the DocFX build. List content globs, generated API YAML, configuration files, TOCs, images, output paths, template customizations and any exports. Choose a target audience and a handful of tasks that genuinely require translated explanation. Establish what will remain as code identifiers and what needs human review.
Week 2
Week two: create separate, reproducible language builds. Use versioned inputs and explicit output destinations. Translate conceptual pages and navigation in context, protect API UIDs, and verify generated symbols against the release. Open the resulting HTML rather than relying on the source Markdown preview. Inspect template labels and a representative error page.
Week 3
Week three: ask bilingual technical reviewers to complete installation, a parameterized method call, exception handling and a version-specific migration. Test search, TOC links, nested routes, xrefs, screenshots and the correct rendering of Unicode text. If PDF is in scope, validate the exact format produced by the installed DocFX release.
Week 4
Week four: publish with language- and version-specific URLs, completeness notices and a correction contact. Preserve build manifests and link-check evidence. Set up change control so modified API signatures, XML comments, TOC structure and support guidance trigger proportionate translation review before the next multilingual release.
Frequently asked questions
Does DocFX automatically translate Markdown?
Do not assume so. DocFX processes source content into documentation output; actual text translation needs a separate, checked authoring workflow.
A particular project may add plugins, custom templates or CI logic. Test those actual integrations and distinguish them from standard DocFX behavior before generalizing advice to other teams.
What should happen to API UIDs?
Keep them consistent with the intended programmatic symbols, and test cross-reference resolution after every language build.
A particular project may add plugins, custom templates or CI logic. Test those actual integrations and distinguish them from standard DocFX behavior before generalizing advice to other teams.
Can toc.yml labels be localized?
Human-facing names can be translated, but their href and uid targets must still resolve correctly.
A particular project may add plugins, custom templates or CI logic. Test those actual integrations and distinguish them from standard DocFX behavior before generalizing advice to other teams.
Should editions share generated API metadata?
They can share versioned symbol identity where the technical artifact is the same; authored translated explanations still need ownership and review.
A particular project may add plugins, custom templates or CI logic. Test those actual integrations and distinguish them from standard DocFX behavior before generalizing advice to other teams.
Are language paths part of translation quality?
Yes. A translated article is not useful if its URL, link targets or search results send readers to unrelated or obsolete content.
A particular project may add plugins, custom templates or CI logic. Test those actual integrations and distinguish them from standard DocFX behavior before generalizing advice to other teams.
Can DocFX export PDF?
Official DocFX documentation describes PDF support with requirements that depend on release and template; test your actual installed version.
A particular project may add plugins, custom templates or CI logic. Test those actual integrations and distinguish them from standard DocFX behavior before generalizing advice to other teams.
How should missing translations behave?
Show an explicit incomplete-coverage notice and link to the authoritative topic instead of redirecting silently to a different subject.
A particular project may add plugins, custom templates or CI logic. Test those actual integrations and distinguish them from standard DocFX behavior before generalizing advice to other teams.
What should a QA record include?
DocFX version, SDK revision, source files, language edition, built artifact, review decision, link checks and reproducible reader tests.
A particular project may add plugins, custom templates or CI logic. Test those actual integrations and distinguish them from standard DocFX behavior before generalizing advice to other teams.
Documentation and related learning
Use DocFX’s official configuration documentation, TOC reference, .NET API documentation guide, PDF guide and build command reference. For broader translation meaning and independent language review, see Master Art of Translation and the Translate Like a Pro series index.