refactor(content-blog): replace reading-time with Intl.Segmenter API

[shreedharbhat98]

Soft Breaking Change

Note from @slorber:

• This changes the behavior of the default blog readingTime() custom computation function (not considered as a breaking change)
• This also changes the signature of the readingTime() function: the options.wordBound param is removed, and the locale param is added (soft breaking change)
• This is technically a breaking change, but we suspect it may affect nobody in practice, and it's easy to restore the former behavior, so we'll ship it in Docusaurus v3

The former behavior can be easily restored with the following config:

npm install reading-time

export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          showReadingTime: true, 
	      readingTime: ({content}) => {
	        const readingTime = require('reading-time');
	        return readingTime(content, {
	          wordsPerMinute: 300,
	          // wordBound: (str) => { your impl... },
	        }).minutes;
	      },
        },
      },
    ],
  ],
};

---

Context

This PR is a continuation of the effort to replace the reading-time npm package with the native Intl.Segmenter API in Docusaurus, as discussed in issue #11086.

The initial implementation was proposed in PR #11091. During the review (see this comment), it was suggested to split the work into two separate pull requests for easier review and to clearly show the differences in behavior between the old and new implementations.

• First part: PR #11116
  This PR adds unit tests for the original reading-time package and refactors the code to make the behavior explicit and testable, without changing the implementation.

• Second part: (this PR)
  This PR replaces the reading-time npm package with the native Intl.Segmenter API, updates the implementation, and adjusts the tests to reflect the new, more accurate, and locale-aware word segmentation and reading time calculation.

---

References:

• Issue #11086: Replace reading-time npm package by Intl.Segmenter API
• Initial PR #11091
• Review comment suggesting PR split
• First part PR #11116 (unit tests for original implementation)

Pre-flight checklist

• I have read the Contributing Guidelines on pull requests.
• If this is a code change: I have written unit tests and/or added dogfooding pages to fully verify the new behavior.
• If this is a new API or substantial change: the PR has an accompanying issue (closes #11086) and the maintainers have approved on my working plan.

---

Motivation

This PR refactors the Docusaurus blog plugin to replace the reading-time npm package with the native Intl.Segmenter API for calculating reading time. This improves accuracy for all languages (especially CJK), removes an external dependency, and makes the implementation fully locale-aware.

---

Test Plan

• All unit tests for reading time and word counting pass.
• Updated tests to match the new, more accurate word segmentation.
• Linting passes with no errors or warnings.
• Manual verification of reading time display in blog posts.
• (If applicable) Previewed changes on a dogfooding page.

Test links

Deploy preview: https://deploy-preview-_____--docusaurus-2.netlify.app/

---

Breaking Changes

• Removed the wordBound parameter from reading time calculation options. This parameter is no longer supported as we now use the native Intl.Segmenter API which handles word boundaries based on locale. The new implementation provides more accurate word segmentation for all languages, especially CJK languages.

Related issues/PRs

• Closes #11086
• Supersedes the old reading-time implementation (PR #11091)

[netlify]

✅ [V2]

Name	Link
🔨 Latest commit	fa90f7d
🔍 Latest deploy log	https://app.netlify.com/projects/docusaurus-2/deploys/6825ca5fcd3b170008d7f111
😎 Deploy Preview	https://deploy-preview-11138--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

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

[shreedharbhat98]

Hi @slorber ,

Here's the PR to replace the usage of the reading-time package with the Intl.Segmenter API.
As you mentioned, wordBound might be a potential blocker for us in moving forward with this change, since Intl.Segmenter doesn't support a similar configuration.

I’d appreciate your thoughts or suggestions on how we might handle this. Thanks in advance!

[github-actions]

⚡️ Lighthouse report for the deploy preview of this PR

URL	Performance	Accessibility	Best Practices	SEO	Report
/	🔴 40	🟢 98	🟢 100	🟢 100	Report
/docs/installation	🔴 49	🟢 97	🟢 100	🟢 100	Report
/docs/category/getting-started	🟠 73	🟢 100	🟢 100	🟠 86	Report
/blog	🟠 60	🟢 96	🟢 100	🟠 86	Report
/blog/preparing-your-site-for-docusaurus-v3	🔴 45	🟢 92	🟢 100	🟢 100	Report
/blog/tags/release	🟠 63	🟢 96	🟢 100	🟠 86	Report
/blog/tags	🟠 73	🟢 100	🟢 100	🟠 86	Report

[argos-ci]

The latest updates on your projects. Learn more about Argos notifications ↗︎

Build	Status	Details	Updated (UTC)
default (Inspect)	⚠️ Changes detected (Review)	35 changed	May 15, 2025, 11:30 AM

[slorber]

Looks almost good thanks.

I still need to study if we can roll this out without a breaking change, although technically maybe it can be considered as a bugfix (see #11091 (comment)), there's now a wordBound param that becomes unused. I doubt anyone is using it though.

@Josh-Cena do you think it's safe to release in a minor?

[slorber]

I'd prefer not to have this magic value hardcoded. This probably requires to refactor types a bit.

[slorber]

In our case, the locale should probably be required; there's no single case we would pass undefined here, we always have a site locale available

[Josh-Cena]

I think it's safe for a minor. There's no specced behavior about what the time should be, and this is probably more sensible anyway.

[shreedharbhat98]

Looks almost good thanks.

I still need to study if we can roll this out without a breaking change, although technically maybe it can be considered as a bugfix (see #11091 (comment)), there's now a wordBound param that becomes unused. I doubt anyone is using it though.

@Josh-Cena do you think it's safe to release in a minor?

I have removed the default value provided to locale. Please have a look.
Thanks 👍

[shreedharbhat98]

@slorber Just a quick reminder!

[shreedharbhat98]

Hi @slorber, just a gentle reminder—whenever you get a chance, I'd appreciate a review on this PR. Let me know if anything needs to be updated or improved. Thanks!

[Josh-Cena]

Almost looks good. Just a few comments and suggestions

[Josh-Cena]

This is technically a breaking change. Pretty confident it affects precisely zero person though.

[shreedharbhat98]

I think this change is necessary since this parameter is no longer supported as we now use the native Intl.Segmenter API which handles word boundaries based on locale

[Josh-Cena]

Yes I understand. Just a comment

[Josh-Cena]

If you don't treat locale as an option elsewhere (for example, the exposed API), why not pass it separately everywhere? You should consistently spread it into options, or not.

[shreedharbhat98]

I understand your concern! I've made the local as second mandatory param and updated the tests

[Josh-Cena]

Just a suggestion: I don't think this is worth testing. Just test the reading time function. This way you don't have to "export something just to test it".

[shreedharbhat98]

Addressed!

[shreedharbhat98]

Almost looks good. Just a few comments and suggestions

Fixed the types faster than you can say Intl.Segmenter! 🚀 Let me know if you spot anything else that needs a quick fix. 😄

[shreedharbhat98]

Hi @slorber Just checking in—if everything looks good with this PR, could you please merge it? Let me know if there's anything else needed from my side. Thanks!

[slorber]

LGTM thanks 👍

I just tweaked the docs a bit

I hope nobody will complain about this new behavior, and the "soft breaking change" will not be harmful to anyone