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

[Daniel Pereira]

On Mon, Oct 19, 2026 at 12:37 +0800, Dongliang Mu wrote:
> 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.

Hi Weijie, Dongliang, Alex, Jani,

I checked docs-next. it_IT, pt_BR, ja_JP and ko_KR already mirror the
original path for every file. There are 14 files in sp_SP, zh_CN and
zh_TW that do not, for two reasons:

- the original has moved and the translation was not moved with it:
magic-number (now in staging/), gdb-kernel-debugging (now in
process/debugging/), security-bugs (now in process/), xfrm_proc
(now in networking/xfrm/), memory-barriers (now in
core-api/wrappers/), and the three gfs2 documents in zh_CN;
- the document exists only in the translation: glossary.rst in zh_CN
and zh_TW, and how-to.rst in zh_CN.

So I agree with Dongliang's order. For v3 of the guide I propose:

- state the path mirroring as a rule, since the language switcher and
checktransupdate.py both depend on it;
- describe ":Original:" as optional and not needed when the path
mirrors the original, instead of showing it in the header example.

Moving the files above and removing the existing ":Original:" fields
can then be done per language, as separate series, by people who know
each translation. I can send the moves for the files whose originals
were relocated, if the maintainers of those translations agree.

Thanks,
Daniel


Em seg., 19 de out. de 2026 às 01:37, 慕冬亮 <dzm91@xxxxxxxxxxx> escreveu:
>
>
> > 发件人: "Weijie Yuan" <wy@xxxxxxxxx>
> > 发送时间:2026-10-18 11:40:09 (星期日)
> > 收件人: "Daniel Pereira" <danielmaraboo@xxxxxxxxx>
> > 抄送: "Jonathan Corbet" <corbet@xxxxxxx>, "Shuah Khan" <skhan@xxxxxxxxxxxxxxxxxxx>, "Randy Dunlap" <rdunlap@xxxxxxxxxxxxx>, "Alex Shi" <alexs@xxxxxxxxxx>, "Yanteng Si" <si.yanteng@xxxxxxxxx>, "Dongliang Mu" <dzm91@xxxxxxxxxxx>, "Chen-Yu Yeh" <chenyou910331@xxxxxxxxx>, "Federico Vaga" <federico.vaga@xxxxxxxxxx>, "Akira Yokosawa" <akiyks@xxxxxxxxx>, "Carlos Bilbao" <carlos.bilbao@xxxxxxxxxx>, "Avadhut Naik" <avadhut.naik@xxxxxxx>, linux-doc@xxxxxxxxxxxxxxx, linux-kernel@xxxxxxxxxxxxxxx, "Jani Nikula" <jani.nikula@xxxxxxxxxxxxxxx>
> > 主题: 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@xxxxxxxxx> 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@xxxxxxxxx>
> > > ---
> > > 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@xxxxxxxxx/
> > >
> > >  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@xxxxxxxxx/
>
>
> ------------------------------
> Best regards,
> Dongliang Mu