sphinx-doc / sphinx-doc/sphinx

Feature request: support translating the generated HTML files

Open
#8,161 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

i18n type:proposal
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:

  1. adding a i18n-pagenames.json file and adding filename translations to it;
  2. replacing occurences of {{ pagename }} in my templates to {{ i18n_pagenames[lang][pagename] }} to link to the translated pagename;
  3. renaming files in the temporary build directory with mv $from.rst $to.rst;
  4. running sed -i "/^ $from/ $to/" index.rst for each entry in the
    i18n-pagenames.json so 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

Commit where I implement the brute force approach.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.