Localization of MLX Documentation

[hwhsu1231]

Introduction

Hello, MLX Community,

I’m glad to announce that the 🎉 mlx-docs-l10n 🎉 project is published now:

• 🚀 Preview: mlx-docs-l10n
• 🌐 Crowdin: mlx-docs-l10n
• 🐙 GitHub: mlx-docs-l10n

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

Tip

If the target language is not yet supported, just open a new issue to request the new language. Once the requested language is added, you can begin translating.

Note

I notice that there is an existing issue (#617) requesting Chinese translation for the MLX Documentation, and I believe this mlx-docs-l10n project can fulfill such needs.

Important

Due to the limitation of the Breathe (breathe-doc/breathe#832), the content read by the .. doxygengroup:: directive in docs/src/cpp/ops.rst cannot be fully extracted by the gettext builder of Sphinx. Therefore, the doxygen-generated content cannot be translated, currently.

How to Reuse Translations

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

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

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

BRANCH=v0.29.4
VERSION=0.29
LANGUAGE=zh_TW

# Prepare the repository and environment
git clone --branch=${BRANCH} --depth=1 https://github.com/ml-explore/mlx.git mlx-docs
cd mlx-docs
conda create --prefix ./.conda --yes
conda activate ./.conda
conda install \
    conda-forge::zsh \
    conda-forge::git \
    conda-forge::gcc=13 \
    conda-forge::gxx=13 \
    conda-forge::binutils \
    conda-forge::doxygen \
    conda-forge::openblas \
    conda-forge::openmpi \
    conda-forge::python=3.12 \
    --channel conda-forge --yes
export PYTHONNOUSERSITE=1
pip install -r docs/requirements.txt
pip install . --progress-bar=off --verbose

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

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

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

Suggestion to MLX Projects

Currently, within the @ml-explore organization, it seems that only the documentation for these two projects, mlx-data and mlx-c , are written with Sphinx. These two projects are therefore also listed in the TODO Lists:

• [Project] mlx-data-docs-l10n localizethedocs/localizethedocs.github.io#329
• [Project] mlx-c-docs-l10n localizethedocs/localizethedocs.github.io#330

If possible, I would suggest that other MLX-related or derived projects (e.g., mlx-xxx) also adopt Sphinx for their documentation. This way, they can all be localized by the infrastructure in the @localizethedocs organization.