Proposal: Migrate the MSYS2 Website to Sphinx for Localization

Proposal

Migrate the MSYS2 Website to Sphinx for Localization

About Us

Hello MSYS2 Team,

I am the author of the @localizethedocs organization, which focuses on creating l10n projects for open-source documentation. Currenlty, I have already established a comprehensive localization infrastructure applicable to almost all Sphinx-based documentation, and have successfully created l10n projects for several major open-source projects. For example:

• localizethedocs/cmake-docs-l10n
• localizethedocs/conan-docs-l10n
• localizethedocs/ros2-docs-l10n
• localizethedocs/llvm-docs-l10n
• and more

For every l10n project, translations are contributed via the Crowdin platform, automatically synchronized with the GitHub repository, and can be previewed on GitHub Pages.

Motivation

I noticed an existing issue where users expressed a desire for the MSYS2 website to support multiple languages:

• https://github.com/msys2/msys2.github.io/issues/275

Currently, the MSYS2 team's solution appears to be the automatic generation of translations via Google Translate. However, I always believe that even as machine or AI translation matures, the final decision on whether to adopt those translations must be made by humans. Therefore, I do not consider the current approach to be an ideal long-term solution.

Since MkDocs itself has not yet implemented an "Internationalization with Gettext" feature comparable to Sphinx's, I am currently unable to create a similar localization infrastructure for MkDocs documentation. However:

If the MSYS2 website is migrated from MkDocs to Sphinx, I would be able to immediately leverage my existing infrastructure to create the msys2-site-l10n project.

Additional Information

If the MSYS2 team decides to migrate the website to Sphinx and wishes to maintain a theme and layout consistent with the current MkDocs-based website, I recommend considering sphinx-immaterial. Here are a few projects that use the sphinx-immaterial theme for reference:

• https://www.statsmodels.org
• https://tortoise.github.io
• https://docs.robusta.dev
• https://flux-framework.readthedocs.io
• https://www.cvxpy.org
• https://neuroglancer-docs.web.app
• https://isort.readthedocs.io/

Start by reviewing the current MkDocs-based MSYS2 website and the related localization request in issue 275. Compare the proposed Sphinx migration and sphinx-immaterial theme with the existing site, and treat a team decision on scope, migration feasibility, and localization support as the completion point.