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

[Dongliang Mu <dzm91@hust.edu.cn>]

On 10/24/26 9:28 PM, Daniel Pereira wrote:
> 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
Good job. I will quickly verify them and send a patch to move them.
> 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@hust.edu.cn> 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@hust.edu.cn> escreveu:
>>>>> 发件人: "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