Rspress multilingual documentation needs more than a translated homepage. The practical work is to configure Rspress locales and a default language, organize language-specific Markdown and MDX files, translate custom interface text with i18nSource or i18n.json, and test navigation, language URLs, product versions and search. This guide provides a complete review method for teams publishing documentation across regions.
A versioned Rspress site has two important identities for each instruction: which product release it describes and which language a reader is using. Confusing either can turn a correct sentence into misleading technical advice. A Chinese troubleshooting guide for version two should not silently point to commands from version three, even if the language selector and build are working perfectly.
The goal is dependable reader action. We will distinguish current documented configuration from older examples, explain how language and release paths interact, and work through practical errors involving navigation, MDX components, code blocks, search, accessibility and maintenance. The reader should finish with a way to test what people actually see and do, not simply a checklist of translated strings.
The working checklist
- Configuration and locale routes
- Language folders, navigation and custom strings
- Version-aware links and search
- Exact commands, warnings and accessible UI
- Reproducible scenario tests and correction
1. The real scope of Rspress internationalization
Rspress documentation describes locale entries, corresponding language files and navigation, and optional translation data for custom UI. These are separate responsibilities. A label can be translated while its linked page remains English; a page can exist in Mandarin while its navigation item still points to an older version.
Audit the reader’s entire journey: how they arrive, which language and release are selected, what instructions they follow, and what happens at the end. Translate the human explanation without changing a command’s machine-readable identifiers. Check the page title and site description, which may be used in search results, as carefully as the visible body.
2. Choose one authoritative source before multiplying pages
Assign a technical owner to every important English source page and record the applicable product version, source commit and approval date. If source instructions are already incomplete, translating them multiplies the defect. Prioritize login, installation, permission, migration and irreversible actions because failures affect real people.
A translator is responsible for target-language meaning, not for guessing whether an obsolete API call is still correct. A software maintainer should verify syntax and actual behaviour. Both sign-offs matter. Keep their evidence alongside the page so an editor can determine whether a later incident came from source drift, text ambiguity or configuration.
3. Understand the current locale configuration
Current official Rspress guidance uses a locales array in rspress.config.ts and a lang value identifying the default language. Each locale entry may have a language code, a switcher label and local title or description. The documented default-language route omits that language prefix: a file under docs/en/ may publish as /guide/ rather than /en/guide/.
Never derive public URLs purely from a file tree. Record the actual generated address and preserve old deep links with redirects when moving from one routing scheme to another. An absent prefix does not mean a document has no language. It can mean it belongs to the configured default edition.
4. Build language folder parity around tasks
An official example separates docs/en and docs/zh and includes navigation files such as _nav.json and _meta.json. Matching page subjects make it easier to switch language without losing a task. However, a word-for-word mirrored folder tree is not itself a quality objective: some regions legitimately need additional explanations, local product availability notices or distinct support instructions.
Use stable identities for the same task and distinguish target-specific information explicitly. If the source splits one migration chapter into two, assess the matching Chinese pages and links. Do not let an old target tutorial remain published as though it were an equivalent version of the updated source.
5. Use translation data for custom interface strings
Rspress documents i18n.json and i18nSource as ways to provide translated text. Teams can choose a coherent source instead of storing duplicate translations in multiple locations. The documented object form of i18nSource takes precedence for a matching language and key when both it and JSON are configured.
Keys are program identifiers and must remain stable; values are the text people read. Custom MDX components can obtain localized text using useI18n from @rspress/core/runtime. Review all component states: loading, success, failure, empty search, permission denial and irreversible confirmation. A translated heading is insufficient when the form error tells people to do the wrong thing.
6. Watch for version-one configuration examples
Older Rspress tutorials may place related language settings under themeConfig.locales. Current documentation instead describes top-level locales and warns that the themeConfig.locales approach is being phased out. A tutorial copied without its version context can create unexpected routing or UI behaviour.
Before applying any example, inspect the dependency version and the matching official documentation. Validate current API names with a safe build. Avoid using old screenshots as evidence of how the present release behaves. Explain why a migration is needed rather than quietly changing configuration until the compiler stops complaining.
7. Keep version and language as distinct coordinates
Rspress supports documentation versions. The official guide illustrates version directories with language subdirectories when both features are enabled. A default version and default locale can omit their prefixes, while another release and a nondefault language have their own segments. This gives a matrix of pages rather than one linear translation list.
Write down which releases are supported in each language. A missing Japanese article for an old release should not lead a reader to current-release instructions without an explicit warning. Changing language and changing product version are different decisions and should remain visible in navigation and search.
8. Make search scope understandable
The current Rspress multiversion guide documents search.versioned as true by default and describes a way to search across versions. The appropriate choice depends on the audience. Beginners usually need results for their current release; migration specialists may need older material as well. Search across versions can produce plausible but harmful instructions if labels do not show release context.
Test queries in the language people naturally use, including product errors, common synonyms, and literal command names. Follow results rather than judging only search counts. Confirm that readers know when a result comes from a different release and how to return to the original language and version.
9. Protect exact syntax and controlled meaning
Translate explanation and helpful context, not executable semantics. Package identifiers, code flags, configuration keys, command order, placeholder variables and endpoint paths generally remain literal. Reformat dates and numbers for readability only when their numerical meaning is unchanged.
Warnings require equally strict care. Preserve may versus must, if versus unless, before versus after, and conditions about permissions or versions. Ask native-language readers to explain what action they believe is required. If they interpret the target sentence differently from the source’s intended operation, repair the translation even when it is grammatically fluent.
10. Validate the complete rendered result
A green build is a technical signal, not a comprehension test. Inspect a local preview, a staging deployment and the final public route. Navigate from the homepage and from a deep link; change languages and versions; copy code; search for errors; and test keyboard focus and accessible labels.
Record source and target URLs, dependency version, source revision, reviewer and observed result. Keep failed tests open until someone reproduces the correction on the public page. A source file existing on disk does not guarantee discoverability in the sidebar or search index.
11. Make a credible partial-translation promise
A site can safely publish a small, reviewed Japanese getting-started path while most advanced material remains in English, provided the difference is clear. Incomplete language coverage is a normal project state. What misleads users is implying the entire site is available because the switcher displays a language name.
Classify pages as reviewed, awaiting review, intentionally untranslated, unavailable or retired. Give highest priority to permissions, security and data-loss topics. Provide feedback links that capture locale, release and exact page. If a source page changes meaning, flag the related translations and do not declare them current without checking the impact.
12. Maintain a repeatable release process
At each release, connect source changes to the affected version-locale pairs. A changed setting, renamed parameter or new prerequisite should trigger target-language review; a punctuation-only correction may need less work. Keep a short changelog recording who reviewed what and which public examples were tested.
The durable result is not a large translated corpus but a documentation service people can trust months later. Preserve known-good builds and rollback instructions. Monitor broken routes, misleading search results, delayed translations and user confusion. Treat all four as maintainable defects rather than separate departments’ problems.
Practical reader tests and recovery decisions
Use these cases as small acceptance exercises. Each begins with a recognisable reader situation, isolates a specific localization risk, and asks for observable proof that the public documentation actually works.
Case 1: First-time Chinese reader
Situation and intent. Consider a new user configuring the SDK. The specific localization danger is a Chinese homepage that leads to an English prerequisite. This matters because documentation is used to take action, not merely to recognize familiar words. If the page fails to distinguish language, release or user permissions, an apparently polished translation can direct a reader toward the wrong outcome.
Editorial and configuration decision. The responsible team should identify the complete beginner path and localize its actual entry points. Put the decision into the page inventory with the relevant source version, locale and reviewer. The wording must make the intended action clear to a person who has not read the original source material. Technical identifiers and product capabilities must remain evidence-based.
Acceptance evidence. To test it, follow installation entirely from a clean Chinese browser session. Record the public URL, the expected behaviour and what actually happened. Verify the rendered page rather than trusting a successful compiler message or a screenshot detached from its context. A reader should be able to follow the result without private knowledge of how the project is organized.
Correction and maintenance. Watch specifically for an untranslated prerequisite or misleading promise of full coverage. If it appears, repair both the text and its affected route, UI state or release relationship, then retest. Link the correction to the source change so that the same misunderstanding cannot quietly return in another language or product version.
Case 2: Default English route
Situation and intent. Consider a existing bookmarks to /en/guide. The specific localization danger is prefix removal under the configured default lang. This matters because documentation is used to take action, not merely to recognize familiar words. If the page fails to distinguish language, release or user permissions, an apparently polished translation can direct a reader toward the wrong outcome.
Editorial and configuration decision. The responsible team should record the real build output and establish appropriate redirects. Put the decision into the page inventory with the relevant source version, locale and reviewer. The wording must make the intended action clear to a person who has not read the original source material. Technical identifiers and product capabilities must remain evidence-based.
Acceptance evidence. To test it, open both current and old addresses without session history. Record the public URL, the expected behaviour and what actually happened. Verify the rendered page rather than trusting a successful compiler message or a screenshot detached from its context. A reader should be able to follow the result without private knowledge of how the project is organized.
Correction and maintenance. Watch specifically for 404 errors or duplicate routes competing in search. If it appears, repair both the text and its affected route, UI state or release relationship, then retest. Link the correction to the source change so that the same misunderstanding cannot quietly return in another language or product version.
Case 3: Version two Japanese command
Situation and intent. Consider a developer maintaining an older installation. The specific localization danger is an option that exists only in a newer product release. This matters because documentation is used to take action, not merely to recognize familiar words. If the page fails to distinguish language, release or user permissions, an apparently polished translation can direct a reader toward the wrong outcome.
Editorial and configuration decision. The responsible team should bind the Japanese example to the version two source and glossary. Put the decision into the page inventory with the relevant source version, locale and reviewer. The wording must make the intended action clear to a person who has not read the original source material. Technical identifiers and product capabilities must remain evidence-based.
Acceptance evidence. To test it, execute the command against a safe matching version. Record the public URL, the expected behaviour and what actually happened. Verify the rendered page rather than trusting a successful compiler message or a screenshot detached from its context. A reader should be able to follow the result without private knowledge of how the project is organized.
Correction and maintenance. Watch specifically for a command that compiles but changes the wrong product behaviour. If it appears, repair both the text and its affected route, UI state or release relationship, then retest. Link the correction to the source change so that the same misunderstanding cannot quietly return in another language or product version.
Case 4: Version switch from a deep page
Situation and intent. Consider a reader troubleshooting an old API. The specific localization danger is language selection redirecting to the newest release. This matters because documentation is used to take action, not merely to recognize familiar words. If the page fails to distinguish language, release or user permissions, an apparently polished translation can direct a reader toward the wrong outcome.
Editorial and configuration decision. The responsible team should preserve page subject and release during language navigation. Put the decision into the page inventory with the relevant source version, locale and reviewer. The wording must make the intended action clear to a person who has not read the original source material. Technical identifiers and product capabilities must remain evidence-based.
Acceptance evidence. To test it, switch languages and inspect the version badge and heading. Record the public URL, the expected behaviour and what actually happened. Verify the rendered page rather than trusting a successful compiler message or a screenshot detached from its context. A reader should be able to follow the result without private knowledge of how the project is organized.
Correction and maintenance. Watch specifically for silent movement from a compatible to an incompatible guide. If it appears, repair both the text and its affected route, UI state or release relationship, then retest. Link the correction to the source change so that the same misunderstanding cannot quietly return in another language or product version.
Case 5: Custom MDX confirmation
Situation and intent. Consider a administrator deleting a test project. The specific localization danger is an untranslated confirmation with inverted yes and cancel labels. This matters because documentation is used to take action, not merely to recognize familiar words. If the page fails to distinguish language, release or user permissions, an apparently polished translation can direct a reader toward the wrong outcome.
Editorial and configuration decision. The responsible team should localize component text through the defined translation source. Put the decision into the page inventory with the relevant source version, locale and reviewer. The wording must make the intended action clear to a person who has not read the original source material. Technical identifiers and product capabilities must remain evidence-based.
Acceptance evidence. To test it, trigger the modal and inspect the action behind each control. Record the public URL, the expected behaviour and what actually happened. Verify the rendered page rather than trusting a successful compiler message or a screenshot detached from its context. A reader should be able to follow the result without private knowledge of how the project is organized.
Correction and maintenance. Watch specifically for a button that makes a more destructive action than its label suggests. If it appears, repair both the text and its affected route, UI state or release relationship, then retest. Link the correction to the source change so that the same misunderstanding cannot quietly return in another language or product version.
Case 6: Version-one config snippet
Situation and intent. Consider a maintainer following a search result. The specific localization danger is an obsolete themeConfig.locales example in a current project. This matters because documentation is used to take action, not merely to recognize familiar words. If the page fails to distinguish language, release or user permissions, an apparently polished translation can direct a reader toward the wrong outcome.
Editorial and configuration decision. The responsible team should use the API documented for installed Rspress dependencies. Put the decision into the page inventory with the relevant source version, locale and reviewer. The wording must make the intended action clear to a person who has not read the original source material. Technical identifiers and product capabilities must remain evidence-based.
Acceptance evidence. To test it, build the project and inspect actual locale options. Record the public URL, the expected behaviour and what actually happened. Verify the rendered page rather than trusting a successful compiler message or a screenshot detached from its context. A reader should be able to follow the result without private knowledge of how the project is organized.
Correction and maintenance. Watch specifically for deprecation warnings masked by apparently successful output. If it appears, repair both the text and its affected route, UI state or release relationship, then retest. Link the correction to the source change so that the same misunderstanding cannot quietly return in another language or product version.
Case 7: Separate site titles
Situation and intent. Consider a public reader scanning search results. The specific localization danger is two languages displaying an identical ambiguous title. This matters because documentation is used to take action, not merely to recognize familiar words. If the page fails to distinguish language, release or user permissions, an apparently polished translation can direct a reader toward the wrong outcome.
Editorial and configuration decision. The responsible team should set appropriate locale title and description without changing the product identity. Put the decision into the page inventory with the relevant source version, locale and reviewer. The wording must make the intended action clear to a person who has not read the original source material. Technical identifiers and product capabilities must remain evidence-based.
Acceptance evidence. To test it, inspect rendered titles and search snippets in each language. Record the public URL, the expected behaviour and what actually happened. Verify the rendered page rather than trusting a successful compiler message or a screenshot detached from its context. A reader should be able to follow the result without private knowledge of how the project is organized.
Correction and maintenance. Watch specifically for claims implying distinct products where one product exists. If it appears, repair both the text and its affected route, UI state or release relationship, then retest. Link the correction to the source change so that the same misunderstanding cannot quietly return in another language or product version.
Case 8: Language folder completeness
Situation and intent. Consider a French support reader. The specific localization danger is a page present only in the English folder. This matters because documentation is used to take action, not merely to recognize familiar words. If the page fails to distinguish language, release or user permissions, an apparently polished translation can direct a reader toward the wrong outcome.
Editorial and configuration decision. The responsible team should record intended availability and the critical missing steps. Put the decision into the page inventory with the relevant source version, locale and reviewer. The wording must make the intended action clear to a person who has not read the original source material. Technical identifiers and product capabilities must remain evidence-based.
Acceptance evidence. To test it, complete an account recovery journey without guessing from English. Record the public URL, the expected behaviour and what actually happened. Verify the rendered page rather than trusting a successful compiler message or a screenshot detached from its context. A reader should be able to follow the result without private knowledge of how the project is organized.
Correction and maintenance. Watch specifically for partial translation passed off as completed work. If it appears, repair both the text and its affected route, UI state or release relationship, then retest. Link the correction to the source change so that the same misunderstanding cannot quietly return in another language or product version.
Case 9: Localized navigation metadata
Situation and intent. Consider a Arabic reader opening setup. The specific localization danger is a translated sidebar label linked to the wrong category. This matters because documentation is used to take action, not merely to recognize familiar words. If the page fails to distinguish language, release or user permissions, an apparently polished translation can direct a reader toward the wrong outcome.
Editorial and configuration decision. The responsible team should review language-specific _nav.json and _meta.json relationships. Put the decision into the page inventory with the relevant source version, locale and reviewer. The wording must make the intended action clear to a person who has not read the original source material. Technical identifiers and product capabilities must remain evidence-based.
Acceptance evidence. To test it, browse from the homepage and compare menu to destination. Record the public URL, the expected behaviour and what actually happened. Verify the rendered page rather than trusting a successful compiler message or a screenshot detached from its context. A reader should be able to follow the result without private knowledge of how the project is organized.
Correction and maintenance. Watch specifically for a label that promises security but opens profile preferences. If it appears, repair both the text and its affected route, UI state or release relationship, then retest. Link the correction to the source change so that the same misunderstanding cannot quietly return in another language or product version.
Case 10: i18nSource conflict
Situation and intent. Consider a theme developer maintaining shared strings. The specific localization danger is one key supplied in JSON and in configuration with different values. This matters because documentation is used to take action, not merely to recognize familiar words. If the page fails to distinguish language, release or user permissions, an apparently polished translation can direct a reader toward the wrong outcome.
Editorial and configuration decision. The responsible team should choose a single ownership rule and inspect documented precedence. Put the decision into the page inventory with the relevant source version, locale and reviewer. The wording must make the intended action clear to a person who has not read the original source material. Technical identifiers and product capabilities must remain evidence-based.
Acceptance evidence. To test it, render both locales and both components that share the key. Record the public URL, the expected behaviour and what actually happened. Verify the rendered page rather than trusting a successful compiler message or a screenshot detached from its context. A reader should be able to follow the result without private knowledge of how the project is organized.
Correction and maintenance. Watch specifically for apparently random text changes after a configuration update. If it appears, repair both the text and its affected route, UI state or release relationship, then retest. Link the correction to the source change so that the same misunderstanding cannot quietly return in another language or product version.
Case 11: Form validation failure
Situation and intent. Consider a beginner entering an invalid access token. The specific localization danger is a translated error that implies authorization succeeded. This matters because documentation is used to take action, not merely to recognize familiar words. If the page fails to distinguish language, release or user permissions, an apparently polished translation can direct a reader toward the wrong outcome.
Editorial and configuration decision. The responsible team should preserve the exact state and action required for recovery. Put the decision into the page inventory with the relevant source version, locale and reviewer. The wording must make the intended action clear to a person who has not read the original source material. Technical identifiers and product capabilities must remain evidence-based.
Acceptance evidence. To test it, submit invalid data and read the visible and accessible errors. Record the public URL, the expected behaviour and what actually happened. Verify the rendered page rather than trusting a successful compiler message or a screenshot detached from its context. A reader should be able to follow the result without private knowledge of how the project is organized.
Correction and maintenance. Watch specifically for confusion between authentication and account activation. If it appears, repair both the text and its affected route, UI state or release relationship, then retest. Link the correction to the source change so that the same misunderstanding cannot quietly return in another language or product version.
Case 12: Deprecated API navigation
Situation and intent. Consider a engineer upgrading after a breaking change. The specific localization danger is old and new API topics sharing the same localized label. This matters because documentation is used to take action, not merely to recognize familiar words. If the page fails to distinguish language, release or user permissions, an apparently polished translation can direct a reader toward the wrong outcome.
Editorial and configuration decision. The responsible team should add clear release context and preserve deprecated status. Put the decision into the page inventory with the relevant source version, locale and reviewer. The wording must make the intended action clear to a person who has not read the original source material. Technical identifiers and product capabilities must remain evidence-based.
Acceptance evidence. To test it, search the translated name and follow each result. Record the public URL, the expected behaviour and what actually happened. Verify the rendered page rather than trusting a successful compiler message or a screenshot detached from its context. A reader should be able to follow the result without private knowledge of how the project is organized.
Correction and maintenance. Watch specifically for accidental use of a removed method in a new release. If it appears, repair both the text and its affected route, UI state or release relationship, then retest. Link the correction to the source change so that the same misunderstanding cannot quietly return in another language or product version.
Case 13: Search across versions
Situation and intent. Consider a migration specialist researching a former error. The specific localization danger is cross-version results lacking release labels. This matters because documentation is used to take action, not merely to recognize familiar words. If the page fails to distinguish language, release or user permissions, an apparently polished translation can direct a reader toward the wrong outcome.
Editorial and configuration decision. The responsible team should choose versioned scope intentionally and surface differences visibly. Put the decision into the page inventory with the relevant source version, locale and reviewer. The wording must make the intended action clear to a person who has not read the original source material. Technical identifiers and product capabilities must remain evidence-based.
Acceptance evidence. To test it, search from two releases with versioned setting checked. Record the public URL, the expected behaviour and what actually happened. Verify the rendered page rather than trusting a successful compiler message or a screenshot detached from its context. A reader should be able to follow the result without private knowledge of how the project is organized.
Correction and maintenance. Watch specifically for old instructions appearing as current recommendations. If it appears, repair both the text and its affected route, UI state or release relationship, then retest. Link the correction to the source change so that the same misunderstanding cannot quietly return in another language or product version.
Case 14: Search in the target language
Situation and intent. Consider a Spanish speaker asking a natural-language question. The specific localization danger is an index that finds only the literal English command name. This matters because documentation is used to take action, not merely to recognize familiar words. If the page fails to distinguish language, release or user permissions, an apparently polished translation can direct a reader toward the wrong outcome.
Editorial and configuration decision. The responsible team should test regional synonyms plus technical identifiers. Put the decision into the page inventory with the relevant source version, locale and reviewer. The wording must make the intended action clear to a person who has not read the original source material. Technical identifiers and product capabilities must remain evidence-based.
Acceptance evidence. To test it, run realistic Spanish search queries and inspect destinations. Record the public URL, the expected behaviour and what actually happened. Verify the rendered page rather than trusting a successful compiler message or a screenshot detached from its context. A reader should be able to follow the result without private knowledge of how the project is organized.
Correction and maintenance. Watch specifically for a functional search box with unusable answer retrieval. If it appears, repair both the text and its affected route, UI state or release relationship, then retest. Link the correction to the source change so that the same misunderstanding cannot quietly return in another language or product version.
Case 15: Copied JSON fields
Situation and intent. Consider a technical reader configuring a plugin. The specific localization danger is translated property names inside machine-readable JSON. This matters because documentation is used to take action, not merely to recognize familiar words. If the page fails to distinguish language, release or user permissions, an apparently polished translation can direct a reader toward the wrong outcome.
Editorial and configuration decision. The responsible team should protect schema keys and treat comments separately. Put the decision into the page inventory with the relevant source version, locale and reviewer. The wording must make the intended action clear to a person who has not read the original source material. Technical identifiers and product capabilities must remain evidence-based.
Acceptance evidence. To test it, paste the example into a validator and compare with source schema. Record the public URL, the expected behaviour and what actually happened. Verify the rendered page rather than trusting a successful compiler message or a screenshot detached from its context. A reader should be able to follow the result without private knowledge of how the project is organized.
Correction and maintenance. Watch specifically for invalid configuration despite a fluent explanation. If it appears, repair both the text and its affected route, UI state or release relationship, then retest. Link the correction to the source change so that the same misunderstanding cannot quietly return in another language or product version.
Case 16: Shell quote corruption
Situation and intent. Consider a developer copying a command from MDX. The specific localization danger is typographic punctuation replacing executable quotes. This matters because documentation is used to take action, not merely to recognize familiar words. If the page fails to distinguish language, release or user permissions, an apparently polished translation can direct a reader toward the wrong outcome.
Editorial and configuration decision. The responsible team should keep code blocks byte-for-byte where command syntax matters. Put the decision into the page inventory with the relevant source version, locale and reviewer. The wording must make the intended action clear to a person who has not read the original source material. Technical identifiers and product capabilities must remain evidence-based.
Acceptance evidence. To test it, copy and run in a sandbox, then compare output. Record the public URL, the expected behaviour and what actually happened. Verify the rendered page rather than trusting a successful compiler message or a screenshot detached from its context. A reader should be able to follow the result without private knowledge of how the project is organized.
Correction and maintenance. Watch specifically for an error incorrectly attributed to the developer’s environment. If it appears, repair both the text and its affected route, UI state or release relationship, then retest. Link the correction to the source change so that the same misunderstanding cannot quietly return in another language or product version.
Case 17: A localized warning banner
Situation and intent. Consider a operator preparing a destructive migration. The specific localization danger is a warning weakened into a vague suggestion. This matters because documentation is used to take action, not merely to recognize familiar words. If the page fails to distinguish language, release or user permissions, an apparently polished translation can direct a reader toward the wrong outcome.
Editorial and configuration decision. The responsible team should retain prohibition, scope and prerequisite in target text. Put the decision into the page inventory with the relevant source version, locale and reviewer. The wording must make the intended action clear to a person who has not read the original source material. Technical identifiers and product capabilities must remain evidence-based.
Acceptance evidence. To test it, ask native reviewer to explain the required safe sequence. Record the public URL, the expected behaviour and what actually happened. Verify the rendered page rather than trusting a successful compiler message or a screenshot detached from its context. A reader should be able to follow the result without private knowledge of how the project is organized.
Correction and maintenance. Watch specifically for data loss because the target phrasing changed obligation. If it appears, repair both the text and its affected route, UI state or release relationship, then retest. Link the correction to the source change so that the same misunderstanding cannot quietly return in another language or product version.
Case 18: Locale-specific numerical format
Situation and intent. Consider a reader scheduling a maintenance window. The specific localization danger is ambiguous 03/04 and missing time-zone information. This matters because documentation is used to take action, not merely to recognize familiar words. If the page fails to distinguish language, release or user permissions, an apparently polished translation can direct a reader toward the wrong outcome.
Editorial and configuration decision. The responsible team should retain exact instant and duration using clear local rendering. Put the decision into the page inventory with the relevant source version, locale and reviewer. The wording must make the intended action clear to a person who has not read the original source material. Technical identifiers and product capabilities must remain evidence-based.
Acceptance evidence. To test it, ask readers in different regions for the same time. Record the public URL, the expected behaviour and what actually happened. Verify the rendered page rather than trusting a successful compiler message or a screenshot detached from its context. A reader should be able to follow the result without private knowledge of how the project is organized.
Correction and maintenance. Watch specifically for a release notice understood as two different dates. If it appears, repair both the text and its affected route, UI state or release relationship, then retest. Link the correction to the source change so that the same misunderstanding cannot quietly return in another language or product version.
Case 19: Mobile version menu
Situation and intent. Consider a field technician reading on a phone. The specific localization danger is screen layout hiding selected documentation release. This matters because documentation is used to take action, not merely to recognize familiar words. If the page fails to distinguish language, release or user permissions, an apparently polished translation can direct a reader toward the wrong outcome.
Editorial and configuration decision. The responsible team should make language and version separately apparent. Put the decision into the page inventory with the relevant source version, locale and reviewer. The wording must make the intended action clear to a person who has not read the original source material. Technical identifiers and product capabilities must remain evidence-based.
Acceptance evidence. To test it, navigate and switch on a narrow viewport. Record the public URL, the expected behaviour and what actually happened. Verify the rendered page rather than trusting a successful compiler message or a screenshot detached from its context. A reader should be able to follow the result without private knowledge of how the project is organized.
Correction and maintenance. Watch specifically for following instructions without knowing the version context. If it appears, repair both the text and its affected route, UI state or release relationship, then retest. Link the correction to the source change so that the same misunderstanding cannot quietly return in another language or product version.
Case 20: Keyboard search dialog
Situation and intent. Consider a screen-reader user locating an error code. The specific localization danger is English accessible control name inside a translated interface. This matters because documentation is used to take action, not merely to recognize familiar words. If the page fails to distinguish language, release or user permissions, an apparently polished translation can direct a reader toward the wrong outcome.
Editorial and configuration decision. The responsible team should localize visible and assistive text through the right component. Put the decision into the page inventory with the relevant source version, locale and reviewer. The wording must make the intended action clear to a person who has not read the original source material. Technical identifiers and product capabilities must remain evidence-based.
Acceptance evidence. To test it, complete search using keyboard and screen reader. Record the public URL, the expected behaviour and what actually happened. Verify the rendered page rather than trusting a successful compiler message or a screenshot detached from its context. A reader should be able to follow the result without private knowledge of how the project is organized.
Correction and maintenance. Watch specifically for sighted-only sign-off missing a real accessibility failure. If it appears, repair both the text and its affected route, UI state or release relationship, then retest. Link the correction to the source change so that the same misunderstanding cannot quietly return in another language or product version.
Case 21: Mixed-script API example
Situation and intent. Consider a Arabic-language engineer reading Latin URLs. The specific localization danger is directionality altering visual order of separators. This matters because documentation is used to take action, not merely to recognize familiar words. If the page fails to distinguish language, release or user permissions, an apparently polished translation can direct a reader toward the wrong outcome.
Editorial and configuration decision. The responsible team should isolate code fragments and preserve underlying characters. Put the decision into the page inventory with the relevant source version, locale and reviewer. The wording must make the intended action clear to a person who has not read the original source material. Technical identifiers and product capabilities must remain evidence-based.
Acceptance evidence. To test it, copy and open the exact address from the rendered page. Record the public URL, the expected behaviour and what actually happened. Verify the rendered page rather than trusting a successful compiler message or a screenshot detached from its context. A reader should be able to follow the result without private knowledge of how the project is organized.
Correction and maintenance. Watch specifically for a route that looks right but does not reach the intended service. If it appears, repair both the text and its affected route, UI state or release relationship, then retest. Link the correction to the source change so that the same misunderstanding cannot quietly return in another language or product version.
Case 22: Translated screenshot labels
Situation and intent. Consider a support agent comparing product interface. The specific localization danger is a target screenshot depicting labels unavailable in the actual application. This matters because documentation is used to take action, not merely to recognize familiar words. If the page fails to distinguish language, release or user permissions, an apparently polished translation can direct a reader toward the wrong outcome.
Editorial and configuration decision. The responsible team should use authentic target-language UI captures or explanatory captions. Put the decision into the page inventory with the relevant source version, locale and reviewer. The wording must make the intended action clear to a person who has not read the original source material. Technical identifiers and product capabilities must remain evidence-based.
Acceptance evidence. To test it, match every instructed click to a real product control. Record the public URL, the expected behaviour and what actually happened. Verify the rendered page rather than trusting a successful compiler message or a screenshot detached from its context. A reader should be able to follow the result without private knowledge of how the project is organized.
Correction and maintenance. Watch specifically for misleading images that invent localized product capabilities. If it appears, repair both the text and its affected route, UI state or release relationship, then retest. Link the correction to the source change so that the same misunderstanding cannot quietly return in another language or product version.
Case 23: Obsolete FAQ answer
Situation and intent. Consider a user searching for failed payment cause. The specific localization danger is an old target FAQ promising a feature already removed. This matters because documentation is used to take action, not merely to recognize familiar words. If the page fails to distinguish language, release or user permissions, an apparently polished translation can direct a reader toward the wrong outcome.
Editorial and configuration decision. The responsible team should compare revision histories and product release notes. Put the decision into the page inventory with the relevant source version, locale and reviewer. The wording must make the intended action clear to a person who has not read the original source material. Technical identifiers and product capabilities must remain evidence-based.
Acceptance evidence. To test it, perform a safe mock transaction and read the localized result. Record the public URL, the expected behaviour and what actually happened. Verify the rendered page rather than trusting a successful compiler message or a screenshot detached from its context. A reader should be able to follow the result without private knowledge of how the project is organized.
Correction and maintenance. Watch specifically for a stale translated answer with plausible but wrong details. If it appears, repair both the text and its affected route, UI state or release relationship, then retest. Link the correction to the source change so that the same misunderstanding cannot quietly return in another language or product version.
Case 24: Renamed Markdown path
Situation and intent. Consider a returning reader following a saved link. The specific localization danger is a translated filename moved without redirect planning. This matters because documentation is used to take action, not merely to recognize familiar words. If the page fails to distinguish language, release or user permissions, an apparently polished translation can direct a reader toward the wrong outcome.
Editorial and configuration decision. The responsible team should maintain page identity and repair navigation and redirects. Put the decision into the page inventory with the relevant source version, locale and reviewer. The wording must make the intended action clear to a person who has not read the original source material. Technical identifiers and product capabilities must remain evidence-based.
Acceptance evidence. To test it, open a saved deep link and switch to another language. Record the public URL, the expected behaviour and what actually happened. Verify the rendered page rather than trusting a successful compiler message or a screenshot detached from its context. A reader should be able to follow the result without private knowledge of how the project is organized.
Correction and maintenance. Watch specifically for site visitors lost despite a successful new build. If it appears, repair both the text and its affected route, UI state or release relationship, then retest. Link the correction to the source change so that the same misunderstanding cannot quietly return in another language or product version.
Case 25: Term used for two permissions
Situation and intent. Consider a administrator comparing editor and owner roles. The specific localization danger is one target word collapsing distinct privilege levels. This matters because documentation is used to take action, not merely to recognize familiar words. If the page fails to distinguish language, release or user permissions, an apparently polished translation can direct a reader toward the wrong outcome.
Editorial and configuration decision. The responsible team should create a role glossary with examples and exceptions. Put the decision into the page inventory with the relevant source version, locale and reviewer. The wording must make the intended action clear to a person who has not read the original source material. Technical identifiers and product capabilities must remain evidence-based.
Acceptance evidence. To test it, ask a native reviewer which role can perform each action. Record the public URL, the expected behaviour and what actually happened. Verify the rendered page rather than trusting a successful compiler message or a screenshot detached from its context. A reader should be able to follow the result without private knowledge of how the project is organized.
Correction and maintenance. Watch specifically for excess permissions granted because terms were conflated. If it appears, repair both the text and its affected route, UI state or release relationship, then retest. Link the correction to the source change so that the same misunderstanding cannot quietly return in another language or product version.
Case 26: Chinese plural-like quantity
Situation and intent. Consider a reader viewing a custom status component. The specific localization danger is a localized count label giving the wrong interpretation of how many errors occurred. This matters because documentation is used to take action, not merely to recognize familiar words. If the page fails to distinguish language, release or user permissions, an apparently polished translation can direct a reader toward the wrong outcome.
Editorial and configuration decision. The responsible team should use meaningful translated text and test interpolated values. Put the decision into the page inventory with the relevant source version, locale and reviewer. The wording must make the intended action clear to a person who has not read the original source material. Technical identifiers and product capabilities must remain evidence-based.
Acceptance evidence. To test it, render zero, one and multiple real results. Record the public URL, the expected behaviour and what actually happened. Verify the rendered page rather than trusting a successful compiler message or a screenshot detached from its context. A reader should be able to follow the result without private knowledge of how the project is organized.
Correction and maintenance. Watch specifically for a correct number attached to an incorrect status description. If it appears, repair both the text and its affected route, UI state or release relationship, then retest. Link the correction to the source change so that the same misunderstanding cannot quietly return in another language or product version.
Case 27: New security prerequisite
Situation and intent. Consider a release editor updating authentication guidance. The specific localization danger is a source change that has not reached older language pages. This matters because documentation is used to take action, not merely to recognize familiar words. If the page fails to distinguish language, release or user permissions, an apparently polished translation can direct a reader toward the wrong outcome.
Editorial and configuration decision. The responsible team should record change impact per version and locale. Put the decision into the page inventory with the relevant source version, locale and reviewer. The wording must make the intended action clear to a person who has not read the original source material. Technical identifiers and product capabilities must remain evidence-based.
Acceptance evidence. To test it, diff meaningful requirements and retest login in safe environment. Record the public URL, the expected behaviour and what actually happened. Verify the rendered page rather than trusting a successful compiler message or a screenshot detached from its context. A reader should be able to follow the result without private knowledge of how the project is organized.
Correction and maintenance. Watch specifically for unreviewed target instructions remaining confidently published. If it appears, repair both the text and its affected route, UI state or release relationship, then retest. Link the correction to the source change so that the same misunderstanding cannot quietly return in another language or product version.
Case 28: Publication sign-off
Situation and intent. Consider a team preparing a multilingual documentation launch. The specific localization danger is a green build used as a substitute for actual reader testing. This matters because documentation is used to take action, not merely to recognize familiar words. If the page fails to distinguish language, release or user permissions, an apparently polished translation can direct a reader toward the wrong outcome.
Editorial and configuration decision. The responsible team should record public URLs, reviewer decisions and version-specific test evidence. Put the decision into the page inventory with the relevant source version, locale and reviewer. The wording must make the intended action clear to a person who has not read the original source material. Technical identifiers and product capabilities must remain evidence-based.
Acceptance evidence. To test it, run one full task per supported release and high-priority locale. Record the public URL, the expected behaviour and what actually happened. Verify the rendered page rather than trusting a successful compiler message or a screenshot detached from its context. A reader should be able to follow the result without private knowledge of how the project is organized.
Correction and maintenance. Watch specifically for no rollback plan or ownership when a harmful error is reported. If it appears, repair both the text and its affected route, UI state or release relationship, then retest. Link the correction to the source change so that the same misunderstanding cannot quietly return in another language or product version.
Frequently asked questions
Does Rspress handle language folders?
Official documentation shows organizing Markdown or MDX under language directories with matching locale configuration and navigation. A folder is only one part of the publishing workflow.
Why is English missing from a URL?
When English is the configured default lang, Rspress can remove its language prefix. Inspect the generated route and preserve old URLs through a deliberate migration plan.
Can i18nSource replace i18n.json?
The official guide describes both approaches. Choose one predictable translation ownership path and examine precedence if both appear in a legacy project.
Are version and locale interchangeable?
No. Product version identifies applicable behaviour; locale identifies the language. Every meaningful combination needs accurate routes, copyable commands and review.
Should search include old releases?
The answer depends on reader tasks. The documented versioned-search default is useful for avoiding accidental cross-release results, but migration research may require another scope.
Does a green build prove localization quality?
No. It is necessary technical evidence, not a guarantee about reader understanding, code accuracy, accessibility or link destinations.
Can machine translation produce the first draft?
It can assist, but technical reviewers must protect commands and product facts, while native-language reviewers protect the meaning, especially conditions and warnings.
What should a small team prioritize?
Finish one valuable reader journey per language and supported release, test it publicly, disclose remaining gaps and maintain a source-change queue.
Official documentation and further reading
- Rspress i18n guide
- Rspress multi-version documentation
- Rspress introduction
- Master Art of Translation
- Translate Like a Pro series index
Reliable multilingual documentation is built from connected evidence: an accurate source, a correctly identified release, a meaningful translation, a working route and a reader who can complete the task. Treat each as a separate acceptance question before the public launch.