Localization of The LLVM C Library Documentation

Announcement

We’re glad to announce that the :tada: llvm-libc-docs-l10n :tada: project is now published:

The goal of this project is to translate The LLVM C Library 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, please follow the following steps:

  1. Create an account on Crowdin Enterprise if you don’t have one.
  2. Log in and go to the llvm-libc-docs-l10n project.
  3. Choose the target language you would like to contribute.

If the target language is not yet supported, please open an issue to request the new language. Once the requested language is added, you can start translating.

How to Reuse Translations?

If the upstream project or anyone wants to reuse the .po files maintained by the this project, they can download the .po files from the po/<version> branch with the following command:

git clone --branch=po/<version> https://github.com/localizethedocs/llvm-libc-docs-l10n.git <locale-dir>

Those po/<version> branches are created to facilitate reusage by the upstream project. For instance, the zh_TW documentation for the main version can be generated using the demo commands below:

Click to expand the demo commands
BRANCH=main
VERSION=main
LANGUAGE=zh_TW
BUILDER=html
REPODIR=$(pwd)/llvm-libc-docs
VENVDIR=$REPODIR/.venv

# Prepare the repository and environment
git clone --branch=$BRANCH \
    --depth=1 \
    --recurse-submodules \
    --shallow-submodules \
    https://github.com/llvm/llvm-project.git \
    $REPODIR
cd $REPODIR
conda create --prefix $VENVDIR --yes
conda activate $VENVDIR
export PYTHONNOUSERSITE=1
conda install cmake gcc gxx graphviz ninja pkg-config python -c conda-forge -c nodefaults --yes
python -m ensurepip
python -m pip install -r llvm/docs/requirements.txt

# Configure and build the llvm project
cmake -S $REPODIR/runtimes -B $REPODIR/build -G Ninja \
    -D CMAKE_BUILD_TYPE=Release \
    -D LLVM_ENABLE_RUNTIMES=libc \
    -D LLVM_TARGETS_TO_BUILD=host \
    -D LLVM_INCLUDE_TESTS=OFF \
    -D LLVM_INCLUDE_BENCHMARKS=OFF \
    -D LLVM_INCLUDE_EXAMPLES=OFF \
    -D LLVM_BUILD_TOOLS=OFF \
    -D LLVM_BUILD_UTILS=OFF \
    -D LLVM_ENABLE_SPHINX=ON \
    -D SPHINX_OUTPUT_HTML=ON
cmake --build $REPODIR/build --target docs-libc-html

# Clone the .po files to the 'locale' directory
git clone --branch=po/$VERSION \
    https://github.com/localizethedocs/llvm-libc-docs-l10n.git \
    $REPODIR/build/libc/docs/locale

# Build the documentation
pushd $REPODIR/build/libc/docs
PYTHONPATH=$REPODIR/utils/docs \
sphinx-build \
    -b $BUILDER \
    -D language=$LANGUAGE \
    -D locale_dirs=locale \
    -D gettext_compact=0 \
    -D gettext_additional_targets=index,literal-block,raw \
    . \
    ./_build/$LANGUAGE
popd

# Preview the documentation
firefox $REPODIR/build/libc/docs/_build/$LANGUAGE/index.html

Thanks for publishing this. One thing worth clarifying for contributors: when the upstream LLVM C Library docs change, how are the .po templates regenerated and pushed to Crowdin? If new or edited source strings appear, does the sync preserve existing translations (fuzzy matching), or do some translated segments silently revert to untranslated in the preview? Related: is there a documented review step for fuzzy entries so translators can catch strings that fell back to English before a version branch is cut?

1 Like