Quick answer: To localize a VuePress 2 documentation site, create parallel language routes and pages, configure site and theme locales separately, then test the content, navigation, links, metadata and actual user tasks in every published language.
VuePress 2 multilingual documentation needs more than translated Markdown. If you are looking for how to translate a VuePress documentation website, configure VuePress locales, create a multilingual navigation menu, or test localized documentation before publication, the real job is to keep language, route, content, links and reader actions aligned. A page can read fluently in Chinese or French and still send its reader to an English procedure that describes a different software version.
This guide explains VuePress 2 internationalization as a complete publishing workflow. It distinguishes the site’s locale configuration from the default theme’s language settings, then works through content directories, translated navigation, internal links, fallback behavior, search, metadata, accessibility and release testing. It is intended for maintainers of open-source projects, software vendors, documentation teams and translators anywhere in the world.
The objective is a working language edition, not a decorative language selector. You will learn how to map a source page to its actual target-language counterpart, recognise when a translation is missing, preserve commands and technical constraints, and produce evidence that readers can complete the same task in every published language. The examples are illustrative; check your installed VuePress and theme versions against their matching documentation before copying configuration.
A minimal configuration to inspect
For a default-theme project, the following example shows how site locale paths and theme labels play different roles. Adapt paths and values to the theme and VuePress version actually in use.
import { defineUserConfig } from 'vuepress'
import { defaultTheme } from '@vuepress/theme-default'
export default defineUserConfig({
locales: {
'/': { lang: 'en-US', title: 'Guide', description: 'Project documentation' },
'/zh/': { lang: 'zh-CN', title: '使用指南', description: '项目文档' }
},
theme: defaultTheme({
locales: {
'/': { selectLanguageName: 'English' },
'/zh/': { selectLanguageName: '简体中文' }
}
})
})Understand the two configuration layers
VuePress 2 has a site-level locale setting and, when the default theme is used, a separate theme-level locale setting. The site layer describes language-specific site identity: language tag, title, description and root path. The theme layer governs parts of the reader-facing interface such as the language selector and localized theme labels. Confusing these layers produces a familiar failure: translated pages exist and the document’s language is declared, but the navigation still says English or the language control is poorly labeled.
Begin by recording which theme is installed and whether it is the default theme. Locate the VuePress configuration file used in that project, and inspect both the top-level locales map and the theme options. A custom theme may have completely different localization hooks, or none at all. The safest troubleshooting order is not to copy properties from a random blog post: first verify the site’s installed major version, next identify the theme implementation, and finally compare the actual options with that version’s reference.
A clean acceptance test is simple. Open a translated page directly, not through a home-page redirect, and confirm the HTML language, page title, visible theme controls and sidebar all describe the same locale. If the browser shows a localized body under an English-only navigation shell, the translation has not yet reached the full interface.
Design paths before translating paragraphs
VuePress’s site locale keys are URL paths. The root slash can represent the default locale, while a path such as /zh/ can host another language. This means directory structure is not merely a convenient way to organise Markdown: it determines which page addresses will be built and how the reader moves through them. A missing translated file is therefore a routing and editorial decision, not just an empty translation cell.
Start with a route inventory. Write down the expected English and Chinese path for the home page, quick-start guide, installation guide, migration note and troubleshooting reference. Add the actual source file that generates each path. Preserve stable conceptual page identities even where target-language titles differ. For example, an installation guide can have a natural Chinese headline without being sent to an unrelated translated page with a similar-looking slug.
Check the deployed addresses, not only their filenames. The relevant question is whether a user can bookmark, share and return to the translated procedure. A root URL that changes unpredictably between deployments is a release defect even when the translation itself is accurate.
Make the smallest working bilingual build
A good proof of concept uses only two languages and three matched pages. Put the default-language home page and a second guide in the normal docs directory, then place translations under the corresponding locale directory. Configure the site locale map with the root path and the target-language path. Set the default theme’s locale entries independently so the language label is understandable to the reader.
Build the site and navigate it from the generated output. Do not measure success only by whether the build command exits with code zero. The three useful checks are that each expected route exists, the corresponding page is the correct document, and the language selector provides an intelligible way back. The direct URL test is particularly important: a site can seem functional when one begins at the English home page but fail when a search engine sends someone to a translated deep link.
Once this small build passes, add translated pages in controlled groups. A dozen paragraphs can be repaired easily; a hundred pages with inconsistent locale paths can become expensive. Use the proof of concept to settle naming, versioning and switcher behavior before investing in translation volume.
Translate navigation as instructions, not decoration
The navbar and sidebar describe how a documentation site is organised. A word like “Guide” may be just a category heading, but “Upgrade now” is an action. A translated label must therefore preserve navigation purpose as well as vocabulary. The default theme can have locale-specific navigation and sidebar configuration; a different theme must be checked for its own capabilities.
Map every navigation item to a target-language destination. Then ask whether the destination actually exists and fulfills the label’s promise. A localized “Troubleshooting” menu that links into a stale English version is not equivalent to a translated troubleshooting path. If content is unavailable, communicate that limitation instead of presenting the English destination as a silent translation. Where links intentionally cross languages, make that choice visible to readers.
Review navigation by completing tasks: find installation, find the current API, locate a breaking change, and return to the guide home page. A translated menu should reduce uncertainty, not make readers hunt for the same page under unfamiliar category names.
Respect the source version and release
Documentation translations are linked to product behavior. A command that worked in an earlier software release may now be deprecated. When the English source is updated, a perfectly grammatical translation can become dangerously misleading if it preserves an old option or removes a newly added warning. This is why page pairing must also include a version or revision reference.
Create a small status table with page identifier, source revision, target revision, last verified date and reviewer. If the source changes, distinguish purely editorial edits from changes to command flags, default values, prerequisites and safety warnings. Reopen high-risk sections for technical review, not merely linguistic proofreading. Translators should have a way to flag unsupported assumptions instead of guessing the product’s current behavior.
The most useful acceptance task is to follow the target-language procedure against the product version that the page claims to document. If the user cannot complete the operation, publication should not be approved just because the prose has been polished.
Preserve code tokens and translate the explanation
A translated setup page often contains command lines, URLs, package names, filenames, environment variables and visible UI labels. They are not all translated by the same rule. Preserve executable syntax unless the software explicitly documents an alternative. Translate surrounding explanations so readers understand what the command will do, what it will change and how to interpret the result.
Consider a page asking a maintainer to run a package-manager command. Changing the command’s letters to resemble the target language can make it unusable. Leaving a user-facing warning completely untranslated can make it incomprehensible. The solution is to classify segments: executable token, example data, literal path, translatable label, explanation, quotation, placeholder or output. Recheck every example after formatting or locale-specific typography has been applied.
In review, copy a command from the rendered translated page and compare it with a verified source example. Verify that punctuation, escape characters and code fences survive. A translator who only reads prose may miss a broken symbol; a technical reviewer who only executes code may miss that the translated sentence tells readers to use the wrong environment.
Keep filenames distinct from reader-facing titles
A Markdown filename and the page’s visible title perform different jobs. The file participates in routing and maintenance; the title helps the reader understand the document. Translating a filename for aesthetic reasons can unintentionally break established inbound links, especially where a project relies on predictable paths. Refusing to translate page titles, by contrast, can leave users with an English information architecture around otherwise translated content.
Choose a URL policy deliberately. Some teams retain source-language slugs to make equivalence obvious; others use native-language slugs because the audience expects them. Both approaches need a one-to-one mapping table and a plan for redirects when URLs change. Do not automatically treat matching filenames as proof that two pages are editorially equivalent. The content could belong to different releases.
Test by starting from a saved target-language URL after a new deployment. It should reach the same type of guide and should not suddenly resolve to the English version because someone restructured the project. Route stability is a reader promise.
Handle missing translations as a product decision
It is tempting to treat a missing target-language page as an implementation detail. To the reader, however, the difference between a missing page, an English fallback and an obsolete translation is substantial. The first says the topic is not available; the second can be useful if labeled; the third can falsely claim to be current. VuePress site configuration can fall back to root-level site metadata for certain omitted properties, but that does not imply complete translated document content exists.
Decide how the product should respond when a translation is absent. Options include withholding that language’s link for the specific page, linking to a clearly labeled source-language page or providing a maintained summary with a status note. Do not invent a silent content fallback that could mislead a reader about what has been reviewed. Keep a translation-coverage manifest that records exactly which pages are approved.
Try a missing-page drill. Remove one noncritical translation in a local test branch and observe language switching, navigation and direct linking. A safe release should have an expected, readable result rather than an accidental 404 or an unlabeled language switch.
Write useful localized page introductions
Technical documentation often begins with a short summary. That summary is a search result candidate, an orientation device and a promise about the work the page teaches. A literal translation can be semantically correct yet lose the main search intent in the target language. The reader may search for a task using a phrase that does not match the English page title.
Use a target-language search phrase where it is natural, but do not insert a list of keywords or change the underlying scope. In the first paragraphs answer what the procedure enables, what the prerequisite is, and when it should not be used. Maintain the distinctions between a tutorial, a reference entry and a troubleshooting page. Users who need a quick command should not be trapped inside promotional material.
Read the translated introduction without the English source. Ask someone unfamiliar with the project to predict what they will be able to do after reading. If their expectation differs from the actual steps, the introduction needs revision even when every sentence translates accurately.
Make sidebar depth match task complexity
Sidebars are often built around the source language’s conceptual hierarchy. A translated edition may need different labels and sometimes more explicit contextual grouping. That does not justify moving material so far that the reader can no longer find an equivalent page. Preserve a stable task map: introduction, preparation, procedure, verification, troubleshooting and next steps.
For example, a single English label “Build” could refer to compiling documentation, compiling an application or publishing a release. If the target language must disambiguate these, choose a label that matches the content actually behind it. Keep links and headings in agreement. Where the default theme’s localized sidebar entries are configured, review both the text and the route values; they are separate failure surfaces.
Test the sidebar from a deep page rather than only the home page. Expand its sections, follow a sibling link and return. A reader should not lose orientation simply because the locale changes. Responsive mobile navigation deserves its own test because long translated labels can overflow narrow layouts.
Treat search as a localized retrieval problem
On multilingual documentation, search quality depends on what content is indexed, how it is tokenized and which language the reader expects. Providing a translated page does not guarantee that the site’s chosen search integration includes its text. Nor does a search component automatically understand every writing system. The implementation depends on the actual search service or plugin, so avoid assuming one behavior for all VuePress sites.
Record each language’s search configuration and run real queries: an exact translated heading, a synonym used by beginners, an error message, a product term and a multiword phrase. Check that results lead to the right locale and version. In languages where words are not separated by spaces, tokenization can change the outcome dramatically. Use evidence from the published index rather than extrapolating from English search performance.
A successful translation edition should allow a user to find a task directly, not merely read the page after someone hands them its address. When search is incomplete, state the limitation and route readers to a usable table of contents while the index is corrected.
Preserve headings and cross-reference meaning
Links inside documentation are part of the instruction. “See the configuration step above” may become wrong if editors rearrange headings or translate anchor text without updating link targets. VuePress-generated headings and routing conventions should be tested in the actual build because punctuation, non-Latin characters and customized slug behavior can affect fragment identifiers.
Maintain a cross-reference map for high-value pages. Where possible link by stable relative routes and verify the built fragment. If a heading changes to become natural in the target language, its incoming anchors may also change. A link checker can find broken destinations, but it cannot decide whether a functioning link points to the correct concept. This calls for a human content review.
On a translated installation page, click every “next step,” “previous step” and API reference. Do not stop after the first link works. A guide that branches to a different version halfway through is an especially damaging error because the reader may follow valid steps from incompatible releases.
Localize alerts without changing their force
Documentation uses callouts such as note, tip, caution and danger to control reader behavior. Translators should preserve that hierarchy. Turning “must not” into “should avoid” weakens a prohibition. Rewriting a caution as a friendly suggestion can hide a destructive operation. Conversely, making an optional convenience sound mandatory imposes work the source did not require.
Classify each alert by its action: prerequisite, limitation, irreversible effect, security warning, compatibility note or optional improvement. Compare the target sentence for negation, conditions, scope and time. In some languages, the strongest natural construction differs greatly from the English syntax; preserve the operational meaning rather than word order. Icons or theme callout colors should not be the only cues to severity.
Ask a reviewer to state, in their own words, what they would do after reading the translated alert. If the answer does not match the intended operation, revise the alert and test again. An alert is successful only when it changes behavior appropriately.
Make language switching context-aware
The best language switcher takes a reader from a specific guide to the equivalent guide in another language, if that guide actually exists. A weak switcher always sends people to the translated home page, discarding their place in a complicated procedure. Neither the presence of a dropdown nor a translated label guarantees context preservation.
Define a page identity independent of its path. For every translated pair, check that it represents the same task and release. If no counterpart exists, choose an explicit alternative, such as a labeled source-language edition or the translated guide index. Do not link to a different page because its filename happens to match. Also test the switcher’s keyboard access and its behavior at small screen widths.
Begin on the target-language “Configure deployment” page, switch to English, then switch back. Read the headings and prerequisites in both versions. A reader who returns to a different chapter or a different product version has discovered an information architecture defect, not a minor localization preference.
Keep metadata and HTML language honest
A translated URL needs metadata that actually describes the translated content. The visible title, description, page language and canonical decisions should not contradict one another. VuePress exposes site-level language and descriptive metadata, but a deployment may add custom head tags, plugins or theme features. Review the rendered HTML rather than assuming configuration values always reach the final output as intended.
The HTML language should represent the actual text, not merely the visitor’s browser preference. Search-facing titles should describe the page’s purpose in the target language. Where alternate-language annotations are implemented, point only to valid counterpart pages and use correct locale identifiers. Never generate an alternate link for a nonexistent translation. A canonical URL is a deliberate statement of page identity and should not automatically erase genuine language variants.
Inspect the deployed source for three matching pages. Look for title, description, language declarations, canonical logic and language alternatives, then verify that those URLs resolve. Metadata is not a substitute for useful text; it is a way to avoid misrepresenting what has actually been published.
Support right-to-left and mixed-direction examples
Arabic, Hebrew and other right-to-left contexts introduce layout decisions beyond translating words. Navigation alignment, breadcrumbs, code examples, filenames and punctuation may require special handling. A code sample or product identifier remains a technical token even when surrounding prose reads right to left. The page must let readers distinguish those two directions without corruption.
Confirm what the installed theme provides for directionality before changing CSS. Test lists, tables, code blocks, highlighted terms, inline links and mixed-script paragraphs. Avoid using visually reversed strings to imitate bidirectional layout; that can damage copy-and-paste and screen-reader interpretation. Instead preserve the original characters and use appropriate direction metadata or styling where supported.
Give the test to a real target-language reader when possible. They should be able to identify the beginning and end of a command, locate the next step and copy code intact. A screenshot that merely looks mirrored is insufficient evidence of usable RTL documentation.
Check images, screenshots and diagram labels
The page may be translated while an important screenshot still shows a source-language menu. That can mislead users when they try to locate a button, particularly if the application itself offers a localized interface. Images can also contain tiny technical labels, warnings or arrows that no longer correspond to the translated instructions.
Create an image inventory by page. Classify each asset as language-neutral, requiring a translated caption, needing localized replacement, or intentionally showing source-language software. When UI labels differ, say which interface language the screenshot depicts. Do not redraw diagrams in a way that changes causal relationships, data values or controls. Alternative text should state the information the image conveys, not simply repeat its filename.
Test one full task using only the translated page and the relevant software. If a reader has to guess which screen element matches the sentence, the screenshot or explanation needs work. Screenshots must be reviewed again after a major product interface change.
Translate forms, labels and accessible names
A docs site may include search boxes, feedback forms, interactive examples, tabs and embedded demos. Text that looks like interface chrome can be necessary for basic use. A visible localized label paired with an untranslated accessible name creates two different experiences: sighted readers hear one instruction and screen-reader users another.
Inventory interactive elements at every language route. Verify label, placeholder, button text, validation message and accessible name. Preserve what the action does: “Copy,” “Run,” “Expand,” “Show result” and “Send feedback” should not be treated as decorative words. Test both keyboard interaction and screen-reader output where feasible. Embedded third-party tools can require a separate localization plan.
A practical exercise is to use the target-language page with a keyboard only. Locate search, open a navigation menu, expand an example and submit a deliberately incomplete form. If the interface cannot explain the error in the same language as the surrounding document, the page is not fully localized.
Plan links to unreleased translations
Translation teams often work on pages asynchronously. A target-language navigation item can appear before its corresponding page is finished, or an unpublished translated page can be indexed by search. Either choice can mislead readers about coverage and reliability. Publication status should therefore be explicit rather than inferred from the existence of a file.
Use editorial states such as not started, in translation, technical review, approved and published. Connect the content manifest to the build or editorial checklist so that navigation is updated only for approved pages. For necessary cross-language references, identify the language gap in a short note. A translated link should not be labeled as complete when its destination is only a machine-generated draft.
Test a staged release by excluding a not-yet-approved translation and checking every entry point: sidebar, navbar, search, sitemap, language switcher and links from related guides. The aim is not to hide inconvenient gaps; it is to present them honestly and prevent accidental promises.
Avoid breaking older inbound URLs
Documentation earns links from issue trackers, forums, support tickets and search engines. Changing a route during localization can silently invalidate those links. A language-prefix migration is especially risky if the default-language URL changes without a redirect plan. Readers may encounter old screenshots or bookmarked fragments long after the site has moved.
Before altering any path, export the current route map and note high-traffic or externally linked pages. For each moved page, decide whether a redirect is appropriate and whether the target represents the same language and version. A redirect to a generic homepage is often less helpful than a direct route to the relevant guide. Retest fragment links because redirects do not always preserve the same heading structure.
Include external inbound-link checks in the deployment smoke test. A translated documentation launch succeeds partly by allowing existing users to keep finding what they already relied on.
Turn translation review into a testable workflow
One reviewer may spot unnatural phrases but miss a wrong command. Another may execute the command but overlook politeness, inconsistent terminology or an inaccessible menu. Divide quality review into distinct questions: does the source meaning survive, is the target language usable, are technical tokens safe, and does the published website function?
The source-to-target reviewer checks claims, conditions, references, headings and terminology. A target-language editor reads independently for clarity and naturalness. A technical reviewer follows the steps against a declared product release. Finally, a site tester checks routes, metadata, mobile layout and navigation. Record defects with the affected path, language, severity, evidence and correction so they can be retested.
Do not reduce acceptance to a percentage of translated strings. A small number of mistranslated danger notices can matter more than hundreds of polished menu labels. Quality is about whether the reader can make the correct decision and complete the task.
Set up a lean change-detection routine
After launch, source documentation continues to change. A new flag, revised prerequisite, renamed screen control or withdrawn feature can make the translation stale. The team needs a method for detecting the kind of source change that affects target-language meaning, not simply a periodic date stamp.
For each page maintain a source identifier, last reviewed source revision, target revision and risk level. Flag changes to commands, defaults, security notes, API names and deletion instructions for priority review. Keep small stylistic improvements separate from operational changes so urgent fixes are not buried. When the target version is behind, communicate its status to users rather than silently presenting old advice as current.
A practical release check compares the source-change log with the approved translation manifest. Any high-risk difference requires an explicit decision: update and approve, temporarily remove the link, or publish a clearly labeled language fallback. There is no need to republish every translation for a punctuation change, but critical behavioral changes must not be ignored.
Build a documentation-first release checklist
Before deploying, check that each published language has the expected home page, current installation guide, core troubleshooting route and useful search or navigation path. Confirm that all localized destinations exist, that the current version is clear, and that the theme chrome matches the page language. Test direct deep links, browser back behavior and small-screen navigation.
Then validate meaningful content: numbers, option names, default values, examples, links and callout force. Review rendered HTML metadata and confirm any language-alternative annotations do not point to missing pages. Try the language selector at least once from a deep page. Verify that published routes can be reached without authentication or a source-language cookie.
Keep the release evidence lightweight but concrete. Record a build result, sampled URLs, screenshots where needed, test cases performed, unresolved limitations and the reviewer responsible. That evidence helps a future maintainer tell the difference between a known gap and a regression.
Understand why a glossary is not enough
A glossary can stabilise words such as “deployment,” “build,” “bundle” and “release,” but it cannot decide the entire meaning of a sentence. “Build the docs” might instruct a maintainer to run a command, whereas “build confidence” in a tutorial introduction has a different meaning. Translating both with one term can be unnatural or wrong.
Store terminology with context, concept definition, approved translation and usage notes. Distinguish terms that appear in the application’s interface from terms used only in narrative explanation. For recurring UI commands, quote the actual target-language screen label when it exists; otherwise give a clear source-language label so the reader can find the control. If a term is ambiguous, the translator should ask which function it has in the procedure.
Review terminology through connected steps, not isolated word lists. A reader should be able to move from a menu label to a heading to a button without wondering whether each refers to a different feature.
Use a small worked release example
Imagine an open-source library releasing version 3.2 with a changed configuration option. The English quick-start page is updated on Monday, but a Japanese page still describes the previous option. The page remains grammatically excellent, and its locale path continues to work. The actual failure is a false operational promise: readers following the translated procedure will copy an option that no longer applies.
Mark the target page as requiring review. Compare the revised English command and surrounding explanation against the Japanese page. Ask a technical reviewer to confirm the installed version and expected output. Then update the relevant prose, code block, warning and any sidebar summary that mentions the option. Retest the direct Japanese route and language switcher, and record which revision was verified.
This example shows why localization in VuePress is not a one-time text conversion. The website is a collection of linked user decisions. A language edition should remain synchronized with the product behavior that gives those decisions their meaning.
Publish and maintain within clear ownership boundaries
This guide’s subject is the VuePress 2 documentation site: its locale paths, theme interface, Markdown routes and release evidence. It does not replace broader instruction on translation theory, terminology, machine translation, or general multilingual web accessibility. Those questions belong to dedicated specialist guides and to the Master Art of Translation system.
A practical long-term plan gives one maintainer responsibility for locale routes and build behavior, another for source document revision, and qualified reviewers for each target language. Small projects may combine roles, but they still need distinct decisions. Ask who can approve a technical warning, who resolves a broken localized link and who can withdraw a dangerously stale page.
For connected reading, return to the Translate Like a Pro series index. For VuePress-specific configuration syntax, consult VuePress 2’s official i18n guide and the documentation for the theme actually installed. The goal is documentation that helps real people finish real tasks in their chosen language.
Frequently asked questions
Does VuePress 2 translate my Markdown automatically?
No. Locale configuration establishes routes and site identity; translators still create and maintain the target-language page content. Verify every published translation rather than mistaking a configured language for completed coverage.
Why is the language selector translated but the sidebar is not?
The theme’s locale settings may be incomplete, or a custom theme may use different controls. Inspect the installed theme configuration and verify each sidebar destination separately.
Can I keep code examples in English?
Yes, executable syntax and product-defined tokens commonly stay unchanged. Translate the explanations and preserve exactly which software version and environment the example applies to.
Should a missing translation silently send users to English?
Only if the behavior is deliberate and clearly disclosed. A hidden fallback makes it difficult for users to know whether a page was translated and reviewed.
What matters most in technical translation QA?
Test the promised reader action: correct route, current product version, accurate conditions and commands, complete navigation, and the rendered experience in the target language.
How should I handle translated SEO metadata?
Use accurate locale-specific titles and descriptions, confirm language and alternate-language metadata against real published pages, and do not allow automation to invent unavailable translations.