Localization of The Gazebo Documentation

## Announcement

Hello Gazebo Community,

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

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

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

Once those PRs are merged, the [ci-gettext-update-po.yml](https://github.com/localizethedocs/gazebosim-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 `gazebosim-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/gazebosim-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 `rotary` version can be generated using the commands below:

```bash
BRANCH=master
VERSION=rotary
LANGUAGE=zh_TW
BUILDER=dirhtml
VENVDIR=$(pwd)/.conda

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

# Generate source directory
cat << 'EOF' > generate_sources.py
import sys
from pathlib import Path
import yaml
from build_multiversion import generate_sources

def main():
src_dir = Path(".") # points to your project directory
tmp_dir = src_dir / ".tmp"
tmp_dir.mkdir(exist_ok=True)

# read index.yaml
with open(src_dir / "index.yaml") as f:
gz_nav_yaml = yaml.safe_load(f)

# extract command line argument as release
if len(sys.argv) < 2:
print("Usage: python generate_sources.py ")
sys.exit(1)

release = sys.argv[1]
generate_sources(gz_nav_yaml, src_dir, tmp_dir, release)

if __name__ == "__main__":
main()
EOF
python generate_sources.py $VERSION

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

# Build the documentation
pushd .tmp/$VERSION
sphinx-build \
-b ${BUILDER} \
-D language=${LANGUAGE} \
-D locale_dirs=locale \
-D gettext_compact=0 \
-D gettext_additional_targets=index,literal-block,raw \
-D gz_release=$VERSION \
-D gz_root_index_file=../../index.yaml \
. \
./_build/${LANGUAGE}
popd

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

Start by reading the linked .github/workflows/ci-sphinx-update-pot.yml and ci-gettext-update-po.yml workflows, then review the upstream documentation and the gazebosim-docs-l10n project. The announcement does not identify a change to make or a testable completion condition, so the scope and definition of done need clarification before implementation.

Written by the indexing model from the issue text.