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

[慕冬亮 <dzm91@hust.edu.cn>]

> 发件人: "Weijie Yuan" <wy@wyuan.org>
> 发送时间:2026-10-18 11:40:09 (星期日)
> 收件人: "Daniel Pereira" <danielmaraboo@gmail.com>
> 抄送: "Jonathan Corbet" <corbet@lwn.net>, "Shuah Khan" <skhan@linuxfoundation.org>, "Randy Dunlap" <rdunlap@infradead.org>, "Alex Shi" <alexs@kernel.org>, "Yanteng Si" <si.yanteng@linux.dev>, "Dongliang Mu" <dzm91@hust.edu.cn>, "Chen-Yu Yeh" <chenyou910331@gmail.com>, "Federico Vaga" <federico.vaga@vaga.pv.it>, "Akira Yokosawa" <akiyks@gmail.com>, "Carlos Bilbao" <carlos.bilbao@kernel.org>, "Avadhut Naik" <avadhut.naik@amd.com>, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, "Jani Nikula" <jani.nikula@linux.intel.com>
> 主题: Re: [PATCH v2 1/2] docs: doc-guide: add a guide for translators
> 
> +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?

Hi Jani and Weijie,

if all the translation documentation follows the relocation style -

Documentation/XXX/XXX.rst to Documentation/translations/XXX/XXX.rst,

the ":Original:" has no meaning, but actually this convention does not work sometimes.

BTW, tools/docs/checktransupdate.py uses this relocation style in the zh_CN translation. When I try to test this script in other translations, this issue occurs.

So my suggestion is that, after confirming all the translated docuementation follows this style, we can delete this field and write this relocation style in the translation guidance.

Dongliang Mu

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


------------------------------
Best regards,
Dongliang Mu