Re: [PATCH v2 1/2] docs: doc-guide: add a guide for translators

[Weijie Yuan <wy@wyuan.org>]

+cc Jani Nikula

On 2026-10-15 09:56:42 -0300, Daniel Pereira <danielmaraboo@gmail.com> wrote:

> The documentation has seven translations, but nothing in the English
> documentation explains how to contribute to them.  The only guide that
> exists, Documentation/translations/zh_CN/how-to.rst, is written in
> Chinese and covers the zh_CN translation only.
> 
> As a result, the same problems come up over and over in the review of
> translation patches: labels and citations copied from the original,
> which are global in Sphinx and collide with the English ones; partial
> builds with SPHINXDIRS that hide those collisions; lines over 80
> columns; translations not added to any toctree; missing commit
> descriptions, tags separated by blank lines, HTML email rejected by the
> lists, and the documentation maintainer left out of the recipients.
> 
> Add Documentation/doc-guide/translations.rst, a guide that covers the
> whole workflow of a translation: choosing what to translate, the layout
> of a translated document (path, header, labels, citations,
> cross-references, what must not be translated), translation quality and
> terminology, adding the document to the build, checking it with a full
> htmldocs build, checkpatch and checktransupdate.py, preparing and
> sending the patch, the review process, keeping translations up to date
> and starting a new translation.  The commit message format it suggests
> is the one already recognized by tools/docs/checktransupdate.py.
> 
> Link the guide from the doc-guide index and from the translations
> index.
> 
> Signed-off-by: Daniel Pereira <danielmaraboo@gmail.com>
> ---
> Changes in v2:
> - Drop the Assisted-by references from the AI tools section, the tags
>   example and the checklist (Weijie Yuan).
> - Use a plain path in the ":Original:" example and drop ":Translator:"
>   from it (Weijie Yuan).
> 
> v1: https://lore.kernel.org/linux-doc/20261013003702.5824-2-danielmaraboo@gmail.com/
> 
>  Documentation/doc-guide/index.rst        |   1 +
>  Documentation/doc-guide/translations.rst | 694 +++++++++++++++++++++++
>  Documentation/translations/index.rst     |   3 +
>  3 files changed, 698 insertions(+)
>  create mode 100644 Documentation/doc-guide/translations.rst

[...]

> +Anatomy of a translated document
> +================================
> +
> +Location and file name
> +----------------------
> +
> +A translation mirrors the path of its original under the language
> +directory, and keeps the same file name::
> +
> +  Documentation/process/howto.rst
> +  Documentation/translations/<lang>/process/howto.rst
> +
> +Do not translate file or directory names.  The documentation build uses
> +this mapping to add, at the top of every page, links to the same page in
> +the other languages; it only works if the paths match.
> +
> +The file header
> +---------------
> +
> +Start the file with the same SPDX license identifier as the original.
> +Most translations then indicate, in some form, which document was
> +translated and include the language's disclaimer.  For example, the
> +Italian translation uses::
> +
> +  .. include:: ../disclaimer-ita.rst
> +
> +  :Original: Documentation/core-api/symbol-namespaces.rst
> +
> +A plain path is enough in the ``:Original:`` field: the documentation
> +build turns ``Documentation/...`` paths into links automatically.

Oh, btw. There's a comment about ":Original:" from Jani [1]:

| I'm wondering, are these :Original: fields useful anymore since the
| translations extension adds the button to switch between languages?
| 
| The pretty much hard-coded expectation is that the English version at
| path/to/foo.rst is the original, and its translations are at
| translations/xx_YY/path/to/foo.rst.
| 
| I.e. neither the HTML nor the RST benefit from it, and it's just
| repetition.

Perhaps we could have a bit of discussion here?

Thanks.

[1] https://lore.kernel.org/linux-doc/c719c6756f345c6c39db483654578ef09de1948f@intel.com/