conan-io
Localization of Conan Documentation
Hello, Conan Community,
I’m glad to announce that the 🎉 conan-docs-l10n 🎉 project is published now:
- 🚀 Preview: conan-docs-l10n
- 🌐 Crowdin: conan-docs-l10n
- 🐙 GitHub: conan-docs-l10n
The goal of this project is to translate the Conan Documentation into multiple languages. Translations are contributed via the Crowdin platform, automatically synchronized with the GitHub repository, and can be previewed on GitHub Pages.
I noticed that there was an issue requesting for multi-language for the Conan Documentation:
- https://github.com/conan-io/docs/issues/832
I believe this conan-docs-l10n project can fulfill such needs.
Hi @hwhsu1231
Thanks very much for adding and sharing it. It would be great to see the community adding translations to different languages. I think it might be a bit challenging, because few people like writing docs, but maybe some interested people with the help of AI translators and some Conan knowledge and quick reviewing can do a god job there. We will see how it goes, let us know if there are any issues, or you have any questions with it. It would be interesting to see how the translations move forward, like for example with every release that happens every month, a new version of the docs goes out. Most of the docs will be the same as previous version, there will be just some small additions and corrections. So it would be great if the translation system can also forward the translations of the previous versions, and introduce some markers based on the diff with the base (English) language or something?
We have added a new section of the docs here: https://docs.conan.io/2/knowledge/community_resources.html, feel free to do a PR to our docs to add a link to this project, to give it some visibility also in the live docs.
Hello, @memsharded
I think it might be a bit challenging, because few people like writing docs, but maybe some interested people with the help of AI translators and some Conan knowledge and quick reviewing can do a god job there. We will see how it goes, let us know if there are any issues, or you have any questions with it.
I believe what you're trying to discuss is about manually maintained translations vs automated translations. In fact, I have discussed a similar viewpoint with the Open Robotics community on this topic:
Open Robotics Discourse - Localization of ROS 2 Documentation
The following is what I replied:
If readers intend to read a document translated entirely by machine or AI, they can already do so using their browser’s built-in translation tools, such as Google Translate, or third-party extensions like Immersive Translate.
However, I’ve always believed that no matter how much translation tools improve, the final decision on how to translate something should always be made by a human during proofreading. The goal of the l10n project I’m working on is to provide a platform that makes it easy for users to perform manually maintained translation.
BTW, Crowdin actually provides a feature called “Pre-Translation via AI”. See the following links for more details:
Currently, for all l10n projects, I’m using the most basic Crowdsourcing workflow:
Since using AI-powered features requires a paid subscription, which is not included in the Crowdin Open-Source License, I don’t plan to look into this feature for now. If I secure enough funding in the future, for example through sponsorships, I believe this feature could significantly accelerate the translation speed and efficiency.
@memsharded
Regarding how to handle new versions:
It would be interesting to see how the translations move forward, like for example with every release that happens every month, a new version of the docs goes out.
First, for an existing release branch like release/2.20, I've set up a GitHub workflow called ci-sphinx-update-pot.yml. This workflow runs weekly and automatically creates a PR to update the .pot files whenever new commits are merged into the tracking branch. For example:
- https://github.com/localizethedocs/conan-docs-l10n/pull/76
Second, when a new release branch is created (for example, release/2.21), this process must be initiated manually by the project's code maintainers. They need to submit a pull request, similar to the one I created for the cmake-docs-l10n project:
- https://github.com/localizethedocs/cmake-docs-l10n/pull/42
Regarding how to forward translations:
Most of the docs will be the same as previous version, there will be just some small additions and corrections. So it would be great if the translation system can also forward the translations of the previous versions, and introduce some markers based on the diff with the base (English) language or something?
First, translators perform their work on the Crowdin platform. However, you'll notice that the conan-docs-l10n project only has two versions, 1 and 2, which track the develop and develop2 branches respectively.
Translations for other X.Y versions are forwarded using the ci-gettext-compendium.yml workflow. This process relies on the VERSION_COMPENDIUM values found in the versions.json file. For example:
- Translations from the
2version are forwarded to versions2.0,2.1, ...,2.20. - Translations from the
1version are forwarded to versions1.3,1.4, ...,1.66.
FYI, if Conan Team plans to use the .po files prepared by the conan-docs-l10n project, you can clone them to the specified directory using the following commands from the po/${VERSION} branch:
VERSION=2
git clone --depth=1 --branch=po/${VERISION} https://github.com/localizethedocs/conan-docs-l10n.git locale
For example, you can build the Conan documentation in the zh_TW language using the following commands:
BRANCH=develop2
VERSION=2
LANGUAGE=zh_TW
# Prepare the repositories.
git clone --depth=1 --branch=${BRANCH} https://github.com/conan-io/docs.git conan-docs
cd conan-docs
git clone --depth=1 --branch=${BRANCH} https://github.com/conan-io/conan.git conan_sources
git clone --depth=1 --branch=po/${VERSION} https://github.com/localizethedocs/conan-docs-l10n.git locale
# Install the dependencies.
conda create --prefix ./.conda --yes
conda activate ./.conda
conda install conda-forge::python=3.12 --channel conda-forge --yes
export PYTHONNOUSERSITE=1
pip install -r requirements.txt
pip install -e conan_sources
# Build and preivew the documentation.
sphinx-build -b html -Dlanguage=${LANGUAGE} -Dlocale_dirs=./locale -Dgettext_compact=0 -Dgettext_additional_targets=index,literal-block,raw . _build/${LANGUAGE}/${VERSION}
firefox _build/${LANGUAGE}/${VERSION}/index.html
Thanks very much for sharing @hwhsu1231
I am checking this https://localizethedocs.crowdin.com/conan-docs-l10n, and it seems the translation is still quite minimal. If this keeps getting traction we will be happy to consider the different possibilities, even hosting it directly ourselves if it makes sense and it is possible.
In the meantime, recall that we have added a new section of the docs here: https://docs.conan.io/2/knowledge/community_resources.html, feel free to do a PR to our docs to add a link to this project, to give it some visibility also in the live docs.