Localization of The Solidity Documentation

## Announcement

Hello Solidity Community,

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

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

The goal of this project is to translate [The Solidity Documentation](https://docs.soliditylang.org/) 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, 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 [solidity-docs-l10n](https://localizethedocs.crowdin.com/solidity-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/solidity-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 Solidity 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/solidity-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/solidity-docs-l10n/pull/2
- https://github.com/localizethedocs/solidity-docs-l10n/pull/3
- https://github.com/localizethedocs/solidity-docs-l10n/pull/4

Once those PRs are merged, the [ci-gettext-update-po.yml](https://github.com/localizethedocs/solidity-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 @localizethedocs 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 `solidity-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/solidity-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=develop
VERSION=latest
LANGUAGE=zh_TW
BUILDER=html

# Prepare the repository and environment
git clone --branch=${BRANCH} --depth=1 https://github.com/argotorg/solidity.git solidity-docs
cd solidity-docs
conda create --prefix ./.conda --yes
conda activate ./.conda
conda install python=3.12 -c conda-forge -c nodefaults --yes
export PYTHONNOUSERSITE=1
python -m ensurepip --default-pip
python -m pip install -r docs/requirements.txt

# Clone the .po files to the 'locale' directory
git clone --branch=po/${VERSION} --depth=1 https://github.com/localizethedocs/solidity-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
```

## Previous Arts and Discussions

The @solidity-docs community has been established for a long while. However, its maintenance approach involves **directly translating the original `.rst` files**, rather than utilizing Sphinx's **["Internationalization with Gettext"](https://www.sphinx-doc.org/en/master/usage/advanced/intl.html)** feature.

1. The former is *easy to set up initially* but is *highly labor-intensive for long-term maintenance*.
2. The latter is *slightly complex to set up* but *allows for automation via command-line tools*.

And the infrastructure of the @localizethedocs organization utilizes the latter one. Besides, I saw the following "Help Needed" message for Automation in this [issue](https://github.com/argotorg/solidity/issues/10119#issuecomment-802714891):

> ## Automation - Help Needed!
>
> Optimally, we would like to have a bot similar to the [reactjs-translation-bot](https://github.com/reactjs-translation-bot), which would create PRs with new content that needs to be translated every time the original documentation is updated.
>
> Currently we have nobody who can set this up, so if you have experience in setting something like this up and want to help, please reach out! :)

Therefore, I believe that the `solidity-docs-l10n` project should be able to serve this purpose.