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

[Daniel Pereira]

On Fri, Oct 23, 2026 at 10:10 +0800, Dongliang Mu wrote:
> Daniel, can you list all 14 files in sp_SP, zh_CN and zh_TW?

Hi Dongliang,

Sure. First a correction: when I counted, I only looked at .rst files.
With the .txt files included, ja_JP and ko_KR do not fully mirror the
original paths either, so my earlier statement about them was wrong.
The full list follows, translation first and current original below.

The 14 .rst files. Original moved, translation not moved with it:

sp_SP/process/magic-number.rst
-> staging/magic-number.rst
sp_SP/wrappers/memory-barriers.rst
-> core-api/wrappers/memory-barriers.rst
zh_CN/dev-tools/gdb-kernel-debugging.rst
-> process/debugging/gdb-kernel-debugging.rst
zh_CN/filesystems/gfs2.rst
-> filesystems/gfs2/index.rst
zh_CN/filesystems/gfs2-glocks.rst
-> filesystems/gfs2/glocks.rst
zh_CN/filesystems/gfs2-uevents.rst
-> filesystems/gfs2/uevents.rst
zh_CN/networking/xfrm_proc.rst
-> networking/xfrm/xfrm_proc.rst
zh_CN/process/magic-number.rst
-> staging/magic-number.rst
zh_TW/admin-guide/security-bugs.rst
-> process/security-bugs.rst
zh_TW/dev-tools/gdb-kernel-debugging.rst
-> process/debugging/gdb-kernel-debugging.rst
zh_TW/process/magic-number.rst
-> staging/magic-number.rst

Document exists only in the translation:

zh_CN/glossary.rst
zh_CN/how-to.rst
zh_TW/glossary.rst

As Chen-Yu pointed out, the three zh_TW moves are already in the zh_TW
tree and will go away once that series lands upstream.

The .txt files whose original is now an .rst file elsewhere:

zh_CN/arch/arm/kernel_user_helpers.txt
zh_TW/arch/arm/kernel_user_helpers.txt
-> arch/arm/kernel_user_helpers.rst
zh_CN/arch/arm64/{booting,legacy_instructions,memory,
silicon-errata,tagged-pointers}.txt
zh_TW/arch/arm64/{booting,legacy_instructions,memory,
silicon-errata,tagged-pointers}.txt
-> arch/arm64/*.rst
zh_CN/filesystems/sysfs.txt
zh_TW/filesystems/sysfs.txt
-> filesystems/sysfs.rst
zh_CN/video4linux/omap3isp.txt
-> admin-guide/media/omap3isp.rst
zh_CN/video4linux/v4l2-framework.txt
-> split into driver-api/media/v4l2-*.rst
zh_TW/IRQ.txt
-> core-api/irq/index.rst (according to its own header)
zh_TW/io_ordering.txt
-> driver-api/io_ordering.rst
ja_JP/stable_api_nonsense.txt
ko_KR/stable_api_nonsense.txt
-> process/stable-api-nonsense.rst
ja_JP/stable_kernel_rules.txt
-> process/stable-kernel-rules.rst

These .txt files are not part of the Sphinx build, so the language
switcher never sees them, but they still break the path mapping that
checktransupdate.py relies on. Whether each one should be converted and
moved, or dropped as outdated, is up to the maintainers of each
translation.

Thanks,
Daniel


Em qui., 22 de out. de 2026 às 23:10, Dongliang Mu <dzm91@xxxxxxxxxxx> escreveu:
>
>
> On 10/23/26 1:09 AM, Daniel Pereira wrote:
> > 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.
>
>
> I agree with this proposal. Ask maintainers of each translation to
> solves these issues first.
>
> Daniel, can you list all 14 files in sp_SP, zh_CN and zh_TW?
>
> Dongliang Mu
>
>
> >
> > 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
>