Skip to content

docs: improve English clarity and natural flow in documentation#6382

Merged
chenjiahan merged 11 commits intomainfrom
copilot/update-english-docs-tone
Oct 22, 2025
Merged

docs: improve English clarity and natural flow in documentation#6382
chenjiahan merged 11 commits intomainfrom
copilot/update-english-docs-tone

Conversation

Copy link
Contributor

Copilot AI commented Oct 19, 2025

Overview

This PR improves the English documentation in 8 files to make them read more naturally and professionally. Many paragraphs were originally translated from Chinese and contained phrasing that, while technically correct, didn't sound like authentic English.

What Changed

Improved documentation in the following files:

  • guide/basic/server.mdx - Dev server functionality and middleware integration
  • guide/framework/react.mdx - React Compiler and hot reload sections
  • guide/configuration/rsbuild.mdx - Config file loading and export functions
  • guide/start/quick-start.mdx - Setup instructions
  • guide/advanced/browser-compatibility.mdx - Polyfills and transpilation explanations
  • guide/basic/output-files.mdx - Asset handling descriptions
  • guide/advanced/browserslist.mdx - Browser configuration examples
  • guide/basic/static-assets.mdx - Static asset handling

Examples of Improvements

Before:

Rsbuild includes a built-in dev server designed to improve the development experience.

After:

Rsbuild includes a built-in dev server that enhances the development experience.

Before:

When the entry is `index`, the page can be accessed at `/`.

After:

When the entry is `index`, you can access the page at `/`.

Before:

Before you start using React Compiler, it is recommended to read the React Compiler documentation.

After:

Before using React Compiler, we recommend reading the React Compiler documentation.

Key Changes

  • Replaced verbose phrasing with concise, natural English
  • Changed passive to active voice where appropriate ("can be accessed" → "you can access")
  • Simplified complex structures for better readability
  • Used contractions where natural ("will not" → "won't")
  • Streamlined conditionals ("If you want to skip" → "To skip")

What Didn't Change

  • No meaning changes - All technical content preserved exactly
  • No structural changes - Same sections, headings, and organization
  • No code changes - All code examples remain identical
  • Chinese docs unchanged - Chinese is the original source

Testing

  • ✅ Prettier formatting passes
  • ✅ Heading case linting passes (sentence case maintained)
  • ✅ Spell checking passes
  • ✅ Code review completed with no issues

Notes

This PR stays under the 10-file limit as requested. The changes are minimal and surgical, focused only on improving readability while maintaining technical accuracy and consistency with high-quality open-source documentation standards.

Original prompt

Improve the English docs in website/docs/en. Many paragraphs were
translated from Chinese and may sound unnatural.

  Rewrite sentences that don't read like authentic, professional English —
  **without changing their meaning** — so they match the tone of
  high-quality open-source docs.


  - **IMPORTANT:** Only change a sentence if it clearly improves clarity or
  correctness.

  - **IMPORTANT:** Don't alter the original meaning.

  - If you edit files in `docs/en`, check the same files in `docs/zh` to see
  if similar updates are needed.

  - Use clear, simple language for non-native English readers.

  - Keep reasonable technical abbreviations (e.g., `dev server`).

  - Use sentence case for Markdown headings.

  - Don't change more than 10 files in one PR.

  - Start PR titles with `docs:`

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

Copilot AI self-assigned this Oct 19, 2025
@netlify
Copy link

netlify bot commented Oct 19, 2025

Deploy Preview for rsbuild ready!

Name Link
🔨 Latest commit 5860ec2
🔍 Latest deploy log https://app.netlify.com/projects/rsbuild/deploys/68f84036be766f000829775a
😎 Deploy Preview https://deploy-preview-6382--rsbuild.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
Lighthouse
Lighthouse
1 paths audited
Performance: 59 (🔴 down 4 from production)
Accessibility: 97 (no change from production)
Best Practices: 100 (no change from production)
SEO: 100 (no change from production)
PWA: 60 (no change from production)
View the detailed breakdown and full score reports

To edit notification comments on pull requests, go to your Netlify project configuration.

@CLAassistant
Copy link

CLAassistant commented Oct 19, 2025

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ chenjiahan
❌ Copilot
You have signed the CLA already but the status is still pending? Let us recheck it.

Copilot AI and others added 3 commits October 19, 2025 00:48
Co-authored-by: chenjiahan <7237365+chenjiahan@users.noreply.github.com>
Co-authored-by: chenjiahan <7237365+chenjiahan@users.noreply.github.com>
Co-authored-by: chenjiahan <7237365+chenjiahan@users.noreply.github.com>
Copilot AI changed the title [WIP] Docs: Improve clarity and tone of English documentation docs: improve English clarity and natural flow in documentation Oct 19, 2025
Copilot AI requested a review from chenjiahan October 19, 2025 00:57
@chenjiahan chenjiahan marked this pull request as ready for review October 20, 2025 03:19
Copilot AI review requested due to automatic review settings October 20, 2025 03:19
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

This PR improves the clarity and natural flow of English documentation across 8 files to make them read more authentically. The changes focus on replacing verbose or unnatural phrasing with concise, professional English while preserving all technical content and meaning.

  • Replaced passive voice with active voice where appropriate ("can be accessed" → "you can access")
  • Simplified verbose constructions for better readability
  • Streamlined conditional statements ("If you want to skip" → "To skip")

Reviewed Changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 4 comments.

Show a summary per file
File Description
guide/start/quick-start.mdx Enhanced setup instructions and template descriptions
guide/framework/react.mdx Improved React Compiler and hot reload explanations
guide/configuration/rsbuild.mdx Clarified config file loading and export function descriptions
guide/basic/static-assets.mdx Enhanced static asset handling explanations
guide/basic/server.mdx Improved dev server functionality descriptions
guide/basic/output-files.mdx Refined asset handling descriptions
guide/advanced/browserslist.mdx Enhanced browser configuration examples and explanations
guide/advanced/browser-compatibility.mdx Improved polyfill and transpilation explanations

Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.

@chenjiahan chenjiahan merged commit 004f595 into main Oct 22, 2025
9 of 10 checks passed
@chenjiahan chenjiahan deleted the copilot/update-english-docs-tone branch October 22, 2025 02:24
@chenjiahan chenjiahan mentioned this pull request Oct 30, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants