From mboxrd@z Thu Jan 1 00:00:00 1970 Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.remote-ip=52.187.6.220 ARC-Seal: i=1; d=subspace.kernel.org; s=arc20261015; a=rsa-sha256; cv=none; t=1792898612; b=HPEkCPKg6Ej3xWA+okCVKIIugvS1Pj2u4rBB1UjONgJ/GDs+Q666Pm9nwefLg/ZgdR3q +gbdKmlHJYg6InVghgqSnD5XJDKPIJANeVykhcmgK3iv30qEZNXLVinqk9PVYEi0yHc/w lGOatvsm3Kt94Fx3uegHI0skw65aP6SoOB5ak5xx7IYSMCMvQAvWbLtYbmK/InnY5g+4W zzxndkm5qdxm2ReONfSITtleZwKSwvKGzZi5ne/gzhxIuTe07Qzvzi/+gl0VoUNImA02v 4UYJ1PAExyHuiK05LCFVWytuOVmFXxEJ9aLY4Wqz3Azp3MWd/Rzp8wHWTghL8fSGGxw== ARC-Message-Signature: i=1; d=subspace.kernel.org; s=arc20261015; a=rsa-sha256; c=relaxed/relaxed; t=1792898612; h=DMARC-Filter:Received:Received:Message-ID:Date:MIME-Version: User-Agent:Subject:To:Cc:References:From:In-Reply-To:Content-Type: Content-Transfer-Encoding:X-CM-TRANSID:X-Coremail-Antispam: X-CM-SenderInfo; bh=+CEND9LNEbGqZK0RMafj7krsiQI5NK+7VAVtk3WXtP8=; b=TL+mE81RhcZHYq3YowBdqLHjCb+W5hhwKPgt3hZlBPfIAvHhAsdqdCAi/V4P6ihOHJW1 L6Ym9mIKw6J8wu4eXxAtJLaabcxFPZGRipnixM6x2adQaNJe2Ny2WD4rZnkkI5giv+XYq 2/stJyMzP+Og+yoSanIRg77UBbjm/9qykEQW7t+Z+fXgPyv3iypjhC5uVqzT8Wvwi4xIk h07rHCmxubAfwbFwHXHV5jBlI1gvacpaknnRsHrI7+A4r1y7hY3oG8OdsBJV635RRq1Qi Q9ELa8rR66L7dsVJRkQV9dg7G1p+wdXVVC9sCkUEDP5sK7cFLmNRt0OjnAPZPSodQNA== ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=none header.from=hust.edu.cn; spf=pass smtp.mailfrom=hust.edu.cn; arc=none smtp.remote-ip=52.187.6.220 Received: from azure-sdnproxy.icoremail.net (azure-sdnproxy.icoremail.net [52.187.6.220]) by smtp.subspace.kernel.org (Postfix) with ESMTP id 26180606A31A; Sun, 25 Oct 2026 03:23:27 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.4.2 smtp.subspace.kernel.org 26180606A31A Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=hust.edu.cn Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=hust.edu.cn Received: from hust.edu.cn (unknown [172.16.0.50]) by app1 (Coremail) with UTF8SMTP id IAEQrMB2u6Endt1qY_ArAQ--.9583S2; Sun, 25 Oct 2026 11:23:19 +0800 (CST) Received: from [100.81.40.43] (unknown [222.20.126.216]) by gateway (Coremail) with SMTP id _____wCnY6oddt1qreO6AA--.14806S2; Sun, 25 Oct 2026 11:23:15 +0800 (CST) Message-ID: <8ff98b43-248e-4568-a5fc-6f84f9cdbe33@hust.edu.cn> Date: Sun, 25 Oct 2026 11:22:33 +0800 X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Post: List-Help: List-Subscribe: List-Unsubscribe: List-Owner: Precedence: list MIME-Version: 1.0 User-Agent: Mozilla Thunderbird Subject: Re: [PATCH v2 1/2] docs: doc-guide: add a guide for translators To: Daniel Pereira Cc: wy@wyuan.org, jani.nikula@linux.intel.com, alexs@kernel.org, corbet@lwn.net, skhan@linuxfoundation.org, rdunlap@infradead.org, si.yanteng@linux.dev, chenyou910331@gmail.com, federico.vaga@vaga.pv.it, akiyks@gmail.com, carlos.bilbao@kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org References: <20261015125644.12908-1-danielmaraboo@gmail.com> <20261015125644.12908-2-danielmaraboo@gmail.com> <79dd90f0.11f3f.1a15272eff3.Coremail.dzm91@hust.edu.cn> <40aeaf0a-6e04-461c-a507-52f791b45541@hust.edu.cn> From: Dongliang Mu In-Reply-To: Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 8bit X-CM-TRANSID:IAEQrMB2u6Endt1qY_ArAQ--.9583S2 Authentication-Results: app1; spf=neutral smtp.mail=dzm91@hust.edu.cn; X-Coremail-Antispam: 1UD129KBjvJXoWfGF4UCryrXFyfCw4xKw1rWFg_yoWkAw1Dpa 45GFyxK3ZxJry7Ar1xKw4UZF1SyayxGw45WryDt3s3AwnYyryIqr43tr9IgFykXrW8ua4j qr4UKrya9rWUAFJanT9S1TB71UUUUbUqnTZGkaVYY2UrUUUUjbIjqfuFe4nvWSU5nxnvy2 9KBjDU0xBIdaVrnRJUUUQCb7Iv0xC_Cr1lb4IE77IF4wAFc2x0x2IEx4CE42xK8VAvwI8I cIk0rVWrJVCq3wA2ocxC64kIII0Yj41l84x0c7CEw4AK67xGY2AK021l84ACjcxK6xIIjx v20xvE14v26F1j6w1UM28EF7xvwVC0I7IYx2IY6xkF7I0E14v26F4j6r4UJwA2z4x0Y4vE x4A2jsIE14v26rxl6s0DM28EF7xvwVC2z280aVCY1x0267AKxVW0oVCq3wAaw2AFwI0_JF 0_Jw1lnxkEFVAIw20F6cxK64vIFxWle2I262IYc4CY6c8Ij28IcVAaY2xG8wAqjxCEc2xF 0cIa020Ex4CE44I27wAqx4xG64xvF2IEw4CE5I8CrVC2j2WlYx0EF7xvrVAajcxG14v26r 4UJVWxJr1lYx0E74AGY7Cv6cx26r4fZr1UJr1lYx0Ec7CjxVAajcxG14v26r4UJVWxJr1l Ox8S6xCaFVCjc4AY6r1j6r4UM4x0Y48IcVAKI48JMxkF7I0En4kS14v26r1q6r43MxkIec xEwVCm-wCF04k20xvY0x0EwIxGrwCF04k20xvE74AGY7Cv6cx26r4fZr1UJr1l4I8I3I0E 4IkC6x0Yz7v_Jr0_Gr1l4IxYO2xFxVAFwI0_JF0_Jw1lx2IqxVAqx4xG67AKxVWUJVWUGw C20s026x8GjcxK67AKxVWUGVWUWwC2zVAF1VAY17CE14v26r1q6r43MIIYrxkI7VAKI48J MIIF0xvE2Ix0cI8IcVAFwI0_JFI_Gr1lIxAIcVC0I7IYx2IY6xkF7I0E14v26r4j6F4UMI IF0xvE42xK8VAvwI8IcIk0rVWUJVWUCwCI42IY6I8E87Iv67AKxVWUJVW8JwCI42IY6I8E 87Iv6xkF7I0E14v26r4j6r4UJbIYCTnIWIevJa73UjIFyTuYvjxUsqjgDUUUU X-CM-SenderInfo: asqsiiirqrkko6kx23oohg3hdfq/ 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 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, 慕冬亮 escreveu: >>>>> 发件人: "Weijie Yuan" >>>>> 发送时间:2026-10-18 11:40:09 (星期日) >>>>> 收件人: "Daniel Pereira" >>>>> 抄送: "Jonathan Corbet" , "Shuah Khan" , "Randy Dunlap" , "Alex Shi" , "Yanteng Si" , "Dongliang Mu" , "Chen-Yu Yeh" , "Federico Vaga" , "Akira Yokosawa" , "Carlos Bilbao" , "Avadhut Naik" , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, "Jani Nikula" >>>>> 主题: 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 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 >>>>>> --- >>>>>> 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//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