Re: [PATCH v2 1/2] docs: doc-guide: add a guide for translators
From: Dongliang Mu
Date: Sat Oct 24 2026 - 23:23:38 EST
On 10/24/26 9:28 PM, Daniel Pereira wrote:
On Fri, Oct 23, 2026 at 10:10 +0800, Dongliang Mu wrote:Good job. I will quickly verify them and send a patch to move them.
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.
It seems the original English documentation moves fast. I would write a script or skill to check this relationship maybe daily or weekly.
Dongliang Mu
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 translatedHi Weijie, Dongliang, Alex, Jani,
docuementation follows this style, we can delete this field and write
this relocation style in the translation guidance.
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>Hi Jani and Weijie,
发送时间: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 documentOh, btw. There's a comment about ":Original:" from Jani [1]:
+================================
+
+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.
| 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?
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