docs: docusaurus versioning setup

[yslpn]

Description

Implement Docusaurus versioning for js-lingui documentation website with support for current version (5.x) and archived version (4.x). Reorganize project structure to separate versioned documentation from static pages and blog content.

Closes #2126

Types of changes

• Documentation update
• Breaking change (fix or feature that would cause existing functionality to not work as expected)

Checklist

• I have read the CONTRIBUTING and CODE_OF_CONDUCT docs
• I have added the necessary documentation

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
js-lingui	✅ Ready (Inspect)	Visit Preview	Jul 2, 2025 7:23pm

[github-actions]

size-limit report 📦

Path	Size
packages/core/dist/index.mjs	2.91 KB (0%)
packages/detect-locale/dist/index.mjs	618 B (0%)
packages/react/dist/index.mjs	1.35 KB (0%)

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 76.82%. Comparing base (6bb8983) to head (88905f8).
Report is 198 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2270      +/-   ##
==========================================
- Coverage   77.05%   76.82%   -0.24%     
==========================================
  Files          84       89       +5     
  Lines        2157     2498     +341     
  Branches      555      650      +95     
==========================================
+ Hits         1662     1919     +257     
- Misses        382      463      +81     
- Partials      113      116       +3     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[yslpn]

I don't know, we should think about an approach to not refer to the code in the main repository. Because the links always show the current main branch. Referencing tags is not very convenient, but it's better.

I think we can leave it like this for now, and do something later. The current version is quite good.

[yslpn]

There were a lot of file changes. It's very difficult to review. I apologize, but it's necessary.

[timofei-iatsenko]

LGTM

[vonovak]

I'm here just to comment on one thing: we don't release major versions all too often, and therefore I'm not sure versioned docs are worth adding - there's a non-negligible amount of complexity and extra maintenance this brings; also outlined in https://docusaurus.io/docs/versioning

Up for @andrii-bodnar to decide, personally I'd avoid adding this. Just my 2 cents.

[andrii-bodnar]

I agree with @vonovak. Adding versioned docs brings more work and complexity, especially since we don't release major updates very often. This is actually why I've put off dealing with this for so long myself - I had a lot of doubts and lacked strong reasons to implement it.

About the v4 docs requests after v5 was released, there have only been a couple, and we just shared the right links, like this one for v4: https://js-lingui-git-stable-4x-crowdin.vercel.app/. We could also set up a separate Vercel deployment for each stable-xx branch if needed.

At the very least, we can make those existing links easier for people to find without pulling this bunch of documents into the repository which will grow with each major version.

Anyway, @yslpn thank you for the contribution! I believe we can create separate PRs for some commits (deps update, Readme, prism-react-renderer, etc.)

[timofei-iatsenko]

I strongly believe Lingui need a versioned docs. Even if the major versions are not released oftenly, many people not updating they projects right away. They may keep version 3 or 4 for longer periods. Having docs only for latest versions very confusing, because the docs doesnt have a hints "was added in v5.1.0". So even considering increased mainteance work i strongly see value in this.

[andrii-bodnar]

Having a dedicated deployment for each version solves this issue. We can just put these links in a more prominent place. Even in versioned docs, new features don't mention exactly which version they were added in, so this confusion may appear there as well.