Localization of The Highlight.js Documentation

## Announcement

Hello Highlight.js Community,

I am the author of the @localizethedocs organization. And I’m glad to announce that the 🎉 **highlightjs-docs-l10n** 🎉 project is published now:

- 🚀 **Preview:** [highlightjs-docs-l10n](https://projects.localizethedocs.org/highlightjs-docs-l10n)
- 🌐 **Crowdin:** [highlightjs-docs-l10n](https://localizethedocs.crowdin.com/highlightjs-docs-l10n)
- 🐙 **GitHub:** [highlightjs-docs-l10n](https://github.com/localizethedocs/highlightjs-docs-l10n)

The goal of this project is to translate The Highlight.js Documentation into multiple languages. Translations are contributed via the Crowdin platform, automatically synchronized with the GitHub repository, and can be previewed on GitHub Pages.

## How to Contribute Translations?

To contribute the translations to the project, just follow the following steps:

1. Create an account on [Crowdin Enterprise](https://localizethedocs.crowdin.com/u/signup) if you don't have one.
2. Log in and go the [highlightjs-docs-l10n](https://localizethedocs.crowdin.com/highlightjs-docs-l10n) project.
3. Choose the language you would like to contribute.

If translators want to translate a language that is not yet supported, they just need to open a new [issue](https://github.com/localizethedocs/highlightjs-docs-l10n/issues/new?template=language_request.yml) to request the new language. Once the requested language is added, they can begin translating.

## How to Keep Content Up-to-date?

An FAQ that is sure to come up in the Highlight.js community is: ***How to keep translations up-to-date?***

First and foremost, in my opinion, the focus should be on how to keep the **"Translatable Content (`msgid`)**" up-to-date, rather than the **"Translations (`msgstr`)**". I will focus on the most critical part of the whole infrastructure here.

In short, the [ci-sphinx-update-pot.yml](https://github.com/localizethedocs/highlightjs-docs-l10n/blob/main/.github/workflows/ci-sphinx-update-pot.yml) workflow will be executed weekly to check the upstream project for any required updates to the document content, which in turn triggers the update of the `.pot` files. If an update is needed, a Pull Request (PR) is automatically created to merge into the `l10n` branch. For example:

- https://github.com/localizethedocs/highlightjs-docs-l10n/pull/3
- https://github.com/localizethedocs/highlightjs-docs-l10n/pull/4

Once those PRs are merged, the [ci-gettext-update-po.yml](https://github.com/localizethedocs/highlightjs-docs-l10n/blob/main/.github/workflows/ci-gettext-update-po.yml) workflow will be triggered to merge the updated content from the `.pot` files into the `.po` files for each language. This is essentially how it keeps the "Translatable Content" up-to-date.

Therefore, the core responsibility of the code maintainers, besides ensuring the stable operation of the scripts and workflows, is to regularly _**check whether there are any pending PRs that need to be merged**_.

## How to Reuse Translations?

If the upstream project or anyone wants to reuse the translated `.po` files prepared by the `highlightjs-docs-l10n` project, they can clone the `.po` files from the `po/${VERSION}` branch by using the following command:

```bash
git clone --depth=1 --branch=po/${VERSION} https://github.com/localizethedocs/highlightjs-docs-l10n.git docs/locale
```

Those `po/${VERSION}` branches are created to facilitate reusage by the upstream project. For instance, the `zh_TW` documentation for the `latest` version can be generated using the commands below:

```bash
BRANCH=main
VERSION=latest
LANGUAGE=zh_TW
BUILDER=html

# Prepare the repository and environment
git clone --branch=${BRANCH} --depth=1 https://github.com/highlightjs/highlight.js.git hljs-docs
cd hljs-docs
conda create --prefix ./.conda --yes
conda activate ./.conda
conda install python=3.13 -c conda-forge -c nodefaults --yes
export PYTHONNOUSERSITE=1
pip install sphinx myst-parser sphinx-rtd-theme

# Clone the .po files to the 'locale' directory
git clone --branch=po/${VERSION} --depth=1 https://github.com/localizethedocs/highlightjs-docs-l10n.git docs/locale

# Build the documentation
sphinx-build \
-b ${BUILDER} \
-D language=${LANGUAGE} \
-D locale_dirs=locale \
-D gettext_compact=0 \
-D gettext_additional_targets=index,literal-block,raw \
docs \
docs/_build/${LANGUAGE}

# Preview the documentation
firefox docs/_build/${LANGUAGE}/index.html
```

## Related Discussions

There was an issue discussing about translation for The Highlight.js Documentation:

- https://github.com/highlightjs/highlight.js/issues/2777

And I believe that the `highlightjs-docs-l10n` project can serve this purpose.