From nobody Thu Apr  9 11:16:18 2026
Received: from mail-pg1-f180.google.com (mail-pg1-f180.google.com
 [209.85.215.180])
	(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 74FEA3859C6
	for <linux-kernel@vger.kernel.org>; Mon,  9 Mar 2026 09:58:39 +0000 (UTC)
Authentication-Results: smtp.subspace.kernel.org;
 arc=none smtp.client-ip=209.85.215.180
ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116;
	t=1773050320; cv=none;
 b=KawikWEkYUyP87IYColWCKud48/6Eeq+sYzbUG4xxEhxc//0jsdHMIiLhnphJFe+xsdUZLZI+Dfm901qxoEfkYYOFpD4KX8gVNSbsDPS/YZ2sYqw/7ZaB5L4Zx9zCz6pKe9gDuUEcdvWIjU71t+/RevmqGu3kdbM/fAUhrZhsrI=
ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org;
	s=arc-20240116; t=1773050320; c=relaxed/simple;
	bh=HFUCoglJbXbiR8kUrCXuOUU8Xmz7mxY7BJqznpbLkm0=;
	h=From:To:Cc:Subject:Date:Message-ID:MIME-Version;
 b=KM5Xq6+i8BgVzMDvd7mX9EzDQBM9osPuLCAT5wIUFrONiAJz9kf6SlyOm5xdMqO4KSirH0nH684yLA6nGafztMVbH0LuitSXtu2o1ppMQLe7r2RoVDSN5ktiUOzCMEbrr7ZUqyyxeFclTmt5rx/OTy8fAk36kqa3kStKqO3jOOs=
ARC-Authentication-Results: i=1; smtp.subspace.kernel.org;
 dmarc=pass (p=none dis=none) header.from=gmail.com;
 spf=pass smtp.mailfrom=gmail.com;
 dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com
 header.b=EOPQDGZ+; arc=none smtp.client-ip=209.85.215.180
Authentication-Results: smtp.subspace.kernel.org;
 dmarc=pass (p=none dis=none) header.from=gmail.com
Authentication-Results: smtp.subspace.kernel.org;
 spf=pass smtp.mailfrom=gmail.com
Authentication-Results: smtp.subspace.kernel.org;
	dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com
 header.b="EOPQDGZ+"
Received: by mail-pg1-f180.google.com with SMTP id
 41be03b00d2f7-c738d327336so2461641a12.0
        for <linux-kernel@vger.kernel.org>;
 Mon, 09 Mar 2026 02:58:39 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
        d=gmail.com; s=20230601; t=1773050319; x=1773655119;
 darn=vger.kernel.org;
        h=content-transfer-encoding:mime-version:message-id:date:subject:cc
         :to:from:from:to:cc:subject:date:message-id:reply-to;
        bh=8Yvkz94goFK1X6HfxlloW5SpPhXOJ/hm+dKJ/2I7lmU=;
        b=EOPQDGZ+XBZOawrpIts+mBeBTf12QehaJYAy4j+89Th+rfFKzemhpSpeqyGnDzmfNB
         h0BrNTP3Z96yBXLiWI4Pf1RjOtrYTzJaqo1jJJP/0Z9XMQoQeC/CGCw88ofJxtqPK2iI
         NMophoBE8DPXxac4wC5Z7m1QeIiNoe528rRpETojyh2KT5H9amklzANgPdV8Y7qL63nU
         UoSOzctQDkyLXxnQEdjaZJITUvhihbfIBexWquQ5nYjLmf8GvJdDpghOyAZ7rvXPurUD
         KFUxsYsjt7xD4MMqzP+QvgaWLZGHNOGe8Fmpf9nu/hWavqfXBjkguXRLpjFELoKaWUgs
         y+kQ==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
        d=1e100.net; s=20230601; t=1773050319; x=1773655119;
        h=content-transfer-encoding:mime-version:message-id:date:subject:cc
         :to:from:x-gm-gg:x-gm-message-state:from:to:cc:subject:date
         :message-id:reply-to;
        bh=8Yvkz94goFK1X6HfxlloW5SpPhXOJ/hm+dKJ/2I7lmU=;
        b=i96vMJu7NcVRhmaSkjoep1InrR+aRnu4UzK+ZN3Rw/6f7PPTZYZTBJA4jGiwTGg3qd
         ITp+I9K3NSuenFCzKMHAJ70zvcbzrWuAeaOkJKCVuhZDIlruEZpEV9Yerq52Xcoz36uv
         trkc3zvM9ZV3uOThgT4pzx/Tn4LZiwqNn/53fjagT+sY/HLG295yDgZQK9D2hrfN/0/M
         /z2iVOKwXEVV70uxJ3TjO7YfXWGqH2hCSEVJAMgX9j20rce3AVzzmPqCyDRkhs8Dxe66
         a6xzW+YHbf/CtansDUemiZDzB6GtkcGELyOSMy9sDoMOZUm+mT0QqVJccc1pkcPoTZDG
         +aXg==
X-Forwarded-Encrypted: i=1;
 AJvYcCXaLTrBhrZ5FPOfYFvplFIm3YPXYPi81vP9fS9ugAeNRqlJDJMBPdhAGq8AckMldIc7bgnfS/gf32YP5yU=@vger.kernel.org
X-Gm-Message-State: AOJu0YzJbvC3kFELoCS95EwJ2j36HfRNwukOGyTi5e0J9lMzTdwRGThe
	JorGQpIR7Zf0hHW9TnK3ACq4TntxuOAxF1KoBuEfdfBefA7OOC/3KU9p
X-Gm-Gg: ATEYQzyI79oQvl5l8LY8KxbTcaXlJ4H9038CFiHb7Hbd55FZiDdHrkGaEy+VtoprdAS
	pKMysoHg2hA3M3bjPPZMmAXt9SYqP4bLEPoSA0+YldhRs1JM80BmqRmkycOVvgpN+x5A1xa0ecS
	EBaf9SrTGTkUJ4hkIGe38+klGxDdhe9pgmY17lx8h/6jCagW5hkttfKNvK6dqYjYLRfLAArnF+O
	W4ws4FdFNduN6/MTiq6lWkP76oyef3Gap8aA5nOjKmSL6+4vv8JX3X2rQndo3u7UZOBzJ1Rea1a
	SUHyIox2vCLmB644YyzDUFVw5VDxGcKzUQXKDiD/XX45DNoy1KuQP9itfXOK4lYfVB9wPfZYDF8
	LhUotp7bW4wlwnjkuurF9DS57p3ROOY9kRUyp83ffNUzLKZDypdpCSZ39YJlXY9WviCJ0U97wvk
	XUJr2qkgoqhr0o6BfFA2+VwuxlwiEZ3m6YTVBRQnAIVWy7wS9qXh9TXKJZGLolZtK8HGJaJA/ks
	5reG+CG+KLZJNlJUQ==
X-Received: by 2002:a17:903:b4e:b0:2a9:622e:fd46 with SMTP id
 d9443c01a7336-2ae82265ddemr106533375ad.0.1773050318715;
        Mon, 09 Mar 2026 02:58:38 -0700 (PDT)
Received: from russ.ust.hk
 (ec2-54-255-20-216.ap-southeast-1.compute.amazonaws.com. [54.255.20.216])
        by smtp.gmail.com with ESMTPSA id
 d9443c01a7336-2ae83e77197sm109972725ad.20.2026.03.09.02.58.36
        (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);
        Mon, 09 Mar 2026 02:58:38 -0700 (PDT)
From: Haoyang LIU <tttturtleruss@gmail.com>
To: Dongliang Mu <dzm91@hust.edu.cn>,
	Yanteng Si <si.yanteng@linux.dev>,
	Alex Shi <alexs@kernel.org>,
	Jonathan Corbet <corbet@lwn.net>,
	Mauro Carvalho Chehab <mchehab@kernel.org>,
	Shuah Khan <skhan@linuxfoundation.org>
Cc: Haoyang LIU <tttturtleruss@gmail.com>,
	linux-doc@vger.kernel.org,
	linux-kernel@vger.kernel.org
Subject: [PATCH] tools/docs/checktransupdate.py: use metadata to lookup origin
 path
Date: Mon,  9 Mar 2026 17:58:31 +0800
Message-ID: <20260309095832.41209-1-tttturtleruss@gmail.com>
X-Mailer: git-send-email 2.53.0
Precedence: bulk
X-Mailing-List: linux-kernel@vger.kernel.org
List-Id: <linux-kernel.vger.kernel.org>
List-Subscribe: <mailto:linux-kernel+subscribe@vger.kernel.org>
List-Unsubscribe: <mailto:linux-kernel+unsubscribe@vger.kernel.org>
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable
Content-Type: text/plain; charset="utf-8"

The get_origin_path() function assumes that translation files have the
same relative path as their origin files, just with "translations/{locale}"
inserted after "Documentation/". However, this assumption is incorrect
for several translation files where the origin path differs. For example:
translations/zh_CN/dev-tools/gdb-kernel-debugging.rst
-> process/debugging/gdb-kernel-debugging.rst


The correct origin path is specified in each translation file's
:Original: metadata field, which can appear in several formats:
1. Plain path: :Original: Documentation/path/to/file.rst
2. With :ref: :Original: :ref:`Documentation/path/to/file.rst <label>`
3. With :doc: :Original: :doc:`../../../path/to/file`


Add get_origin_path_from_metadata() to parse the :Original: metadata
from translation files and extract the actual origin path. Update
check_per_file() to use metadata-based lookup first, falling back to
the path manipulation heuristic only when no metadata is found.

Signed-off-by: Haoyang LIU <tttturtleruss@gmail.com>
---
 tools/docs/checktransupdate.py | 63 ++++++++++++++++++++++++++++++++--
 1 file changed, 61 insertions(+), 2 deletions(-)

diff --git a/tools/docs/checktransupdate.py b/tools/docs/checktransupdate.py
index cc07cda667fc..b3c695fa0f7a 100755
--- a/tools/docs/checktransupdate.py
+++ b/tools/docs/checktransupdate.py
@@ -32,7 +32,7 @@ from datetime import datetime
=20
=20
 def get_origin_path(file_path):
-    """Get the origin path from the translation path"""
+    """Get the origin path from the translation path by path manipulation =
(fallback)"""
     paths =3D file_path.split("/")
     tidx =3D paths.index("translations")
     opaths =3D paths[:tidx]
@@ -40,6 +40,62 @@ def get_origin_path(file_path):
     return "/".join(opaths)
=20
=20
+def get_origin_path_from_metadata(file_path):
+    """Get the origin path from the :Original: metadata in the translation=
 file.
+
+    The :Original: metadata can have several formats:
+    1. Plain path: :Original: Documentation/path/to/file.rst
+    2. With :ref: directive: :Original: :ref:`Documentation/path/to/file.r=
st <label>`
+    3. With :doc: directive: :Original: :doc:`../../../path/to/file`
+
+    Returns the origin path if found, None otherwise.
+    """
+    # Pattern to match :Original: line
+    original_re =3D re.compile(r'^:Original:\s*(.+?)\s*$', re.IGNORECASE)
+    # Pattern to extract path from :ref:`path <label>` or :ref:`path`
+    ref_re =3D re.compile(r':ref:`([^`<]+?)(?:\s*<[^>]+>)?`')
+    # Pattern to extract path from :doc:`path`
+    doc_re =3D re.compile(r':doc:`([^`]+)`')
+
+    try:
+        with open(file_path, 'r', encoding=3D'utf-8') as f:
+            # Only check the first 20 lines for metadata
+            for _ in range(20):
+                line =3D f.readline()
+                if not line:
+                    break
+                match =3D original_re.match(line.strip())
+                if match:
+                    original_value =3D match.group(1).strip()
+
+                    # Try to extract from :ref:`...`
+                    ref_match =3D ref_re.search(original_value)
+                    if ref_match:
+                        return ref_match.group(1).strip()
+
+                    # Try to extract from :doc:`...`
+                    doc_match =3D doc_re.search(original_value)
+                    if doc_match:
+                        doc_path =3D doc_match.group(1).strip()
+                        # Handle relative paths - resolve relative to tran=
slation file
+                        if doc_path.startswith('../'):
+                            trans_dir =3D os.path.dirname(file_path)
+                            resolved =3D os.path.normpath(os.path.join(tra=
ns_dir, doc_path))
+                            # Add .rst extension if not present
+                            if not resolved.endswith('.rst'):
+                                resolved +=3D '.rst'
+                            return resolved
+
+                    # Plain path (no directive wrapper)
+                    if original_value.startswith('Documentation/'):
+                        return original_value
+
+    except (IOError, OSError) as e:
+        logging.debug("Could not read file %s: %s", file_path, e)
+
+    return None
+
+
 def get_latest_commit_from(file_path, commit):
     """Get the latest commit from the specified commit for the specified f=
ile"""
     command =3D f"git log --pretty=3Dformat:%H%n%aD%n%cD%n%n%B {commit} -1=
 -- {file_path}"
@@ -128,7 +184,10 @@ def valid_commit(commit):
=20
 def check_per_file(file_path):
     """Check the translation status for the specified file"""
-    opath =3D get_origin_path(file_path)
+    opath =3D get_origin_path_from_metadata(file_path)
+    if opath is None:
+        opath =3D get_origin_path(file_path)
+        logging.debug("No :Original: metadata found, using path-based fall=
back for %s", file_path)
=20
     if not os.path.isfile(opath):
         logging.error("Cannot find the origin path for %s", file_path)
--=20
2.53.0