sphinx-doc / sphinx-doc/sphinx
Feature request: support translating the generated HTML files
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
Is your feature request related to a problem? Please describe.
When adding full translation to a project's documentation, I want to be able to
fully translate the documentation, even the generated URIs.
Right now Sphinx supports everything by using gettext, image filename specific
to a language, etc. This allows me to translate the images, content, headers,
except the generated link.
Say I have a file called contributing.rst. When translating it's title to
pt_BR, I can add the "Contribuindo" translation in the generated .po file as
the translationg to the original "Contributing" title, but the final URI still
will be example.com/pt/contributing.html. Even anchors in the existing page
are translated, which is great, only the filename itself that isn't.
Describe the solution you'd like
Be able to have sphinx-doc understand such translation option. No real clue on
any solution on this, though.
Describe alternatives you've considered
I've hacked a brute force solution, by:
- adding a
i18n-pagenames.jsonfile and adding filename translations to it; - replacing occurences of
{{ pagename }}in my templates to{{ i18n_pagenames[lang][pagename] }}to link to the translated pagename; - renaming files in the temporary build directory with
mv $from.rst $to.rst; - running
sed -i "/^ $from/ $to/" index.rstfor each entry in the
i18n-pagenames.jsonso that the table of contants include the translated
version.
By doing this fake replacement before running sphinx-build, everything works
fine.
I'm happy with my current solution, but I was wondering if this is something
that should be added to Sphinx itself.
I might be able to help implement it with some guidance if possible, but I'm not
in any hurry.
Additional context
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by tracing sphinx-build's gettext flow from the generated .po files through HTML URI and anchor generation. Compare that behavior with the issue's i18n-pagenames.json, template {{ pagename }} replacement, temporary-file renaming, and index.rst workaround. Done should mean translated page filenames and links are handled by Sphinx without those external substitutions.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation, internationalization, localization
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100