From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mta0.migadu.com (out-64.mta0.migadu.com [91.218.175.64]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 841CE1BD9D0 for ; Sun, 18 Oct 2026 03:40:19 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=91.218.175.64 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1792294823; cv=none; b=DlwYkHFAyEChTVIfZX3Rg05eqGQQE5R64nwSioplI03ZRuwNlGunhYumf7ycnz93JK5m4XrNG1ipO4cJjU/ZB87H7KIDBhar08rx5QnZZViYKC0rJhXjHezYBxevUNASvCuRrQejrgncS2As5bbIDbtASYFUBWOJabdMRhQynAg= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1792294823; c=relaxed/simple; bh=6O+om/N5nsSX+OZd+gHsZmbTWkyBWjGNtLKULO0LteU=; h=Date:From:To:Cc:Subject:Message-ID:References:MIME-Version: Content-Type:Content-Disposition:In-Reply-To; b=B4GZ77sZ8GNVgx4Cf224Xoog5ioraZmQ65NVvQvxhrP8TOUUYcbx6Ugk6D0hf7EvHM9fZl4UtHV1zsxNC/wuTs2ibZZhCyZsxnD42ERcVr1SFFiZKc50Fw6+vBivhFVj/mZn0gqnyaxX1VtJwl4SQrlL78iN1KQoPMS0o/bbrHc= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dmarc=pass (p=quarantine dis=none) header.from=wyuan.org; spf=pass smtp.mailfrom=wyuan.org; dkim=pass (2048-bit key) header.d=wyuan.org header.i=@wyuan.org header.b=oFpUEel4; arc=none smtp.client-ip=91.218.175.64 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=quarantine dis=none) header.from=wyuan.org Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=wyuan.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=wyuan.org header.i=@wyuan.org header.b="oFpUEel4" X-Envelope-To: linux-doc@vger.kernel.org DKIM-Signature: a=rsa-sha256; bh=6O+om/N5nsSX+OZd+gHsZmbTWkyBWjGNtLKULO0LteU=; c=simple/simple; d=wyuan.org; h=from:to:subject:date:message-id:mime-version:content-type; s=key1; t=1792294816; v=1; x=1792899616; b=oFpUEel4qGe7ViwHLLCYmlxgRMlDQf+fbbYA/Uj4DoT+VW9Q6hVM6wZ6FbWig8vy8lU1DGow zMjB3eDbzd2699oeCsGi18EFD176yH6oNhDT+UpopPZQVZWUFtOeCGhwLL658hRktyGbJyroRB1 l8VKmmeQnuw7LMuX65jUocuLhlGNa69qByl30l5aScCjeGsgz+9UkEtGu8J0H4iVKW60iLHsR+R aYGOWuZ3p+gIbvd/rRh9vjZOmouK8F8sx/r+WuapzgpKVt8Dh2fHhp6Sue4wQTU12EXaTF0Tuqm AnnwWajt+Odbh55H/65i8rGzsDIl1unhggyDwBUIeHygw== X-Envelope-To: linux-doc@vger.kernel.org Received: by smtp.migadu.com with ESMTPS id e0b0a0b21c66541c; Sun, 18 Oct 2026 03:40:14 +0000 X-Mizu-Trace-ID: e0b0a0b21c66541c X-Migadu-Flow: FLOW_OUT Date: Sun, 18 Oct 2026 11:40:09 +0800 From: Weijie Yuan To: Daniel Pereira Cc: 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 Subject: Re: [PATCH v2 1/2] docs: doc-guide: add a guide for translators Message-ID: References: <20261015125644.12908-1-danielmaraboo@gmail.com> <20261015125644.12908-2-danielmaraboo@gmail.com> Precedence: bulk X-Mailing-List: linux-doc@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20261015125644.12908-2-danielmaraboo@gmail.com> +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? Thanks. [1] https://lore.kernel.org/linux-doc/c719c6756f345c6c39db483654578ef09de1948f@intel.com/