From cf3434b91fa55c62b31425a66e606d8a11629a17 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9=20L=20F=20S=20Bacci?= <ae@php.net>
Date: Sat, 27 Jun 2026 11:54:57 -0300
Subject: [PATCH 1/2] Mark for do-not-translate files

---
 scripts/broken.php                         | 53 ++++++++++++++--------
 scripts/translation/lib/RevcheckIgnore.php |  9 +++-
 scripts/translation/lib/RevcheckRun.php    |  3 ++
 3 files changed, 46 insertions(+), 19 deletions(-)

diff --git a/scripts/broken.php b/scripts/broken.php
index 8908786487..8d6c80b016 100644
--- a/scripts/broken.php
+++ b/scripts/broken.php
@@ -1,6 +1,6 @@
 <?php /*
 +----------------------------------------------------------------------+
-| Copyright (c) 1997-2025 The PHP Group                                |
+| Copyright (c) 1997-2026 The PHP Group                                |
 +----------------------------------------------------------------------+
 | This source file is subject to version 3.01 of the PHP license,      |
 | that is bundled with this package in the file LICENSE, and is        |
@@ -38,20 +38,28 @@
         $dos2unix = true;
         $arg = null;
     }
+    else
+        $arg = str_replace( '\\' , '/' , $arg );
 }
-$argv = array_filter( $argv );
+$paths = array_filter( $argv );
+if ( count( $paths) == 0 )
+    print_usage_exit();
 
-foreach( $argv as $arg )
+foreach( $paths as $path )
 {
-    if ( file_exists( $arg ) )
+    $dnt = true;
+    if ( $path == 'en' || str_ends_with( $path , '/en' ) )
+        $dnt = false;
+
+    if ( file_exists( $path ) )
     {
-        if ( is_file( $arg ) )
-            testFile( $arg );
-        if ( is_dir( $arg ) )
-            testDir( $arg );
+        if ( is_file( $path ) )
+            testFile( $path , $dnt );
+        if ( is_dir( $path ) )
+            testDir( $path , $dnt );
         continue;
     }
-    echo "Path does not exist: $arg\n";
+    echo "Path does not exist: $path\n";
 }
 
 function print_usage_exit( $cmd )
@@ -87,7 +95,7 @@ function setup( string & $prefix , string & $suffix , string & $extra )
     libxml_clear_errors();
 }
 
-function testFile( string $filename , bool $fragment = false )
+function testFile( string $filename , bool $checkDnt , bool $fragmentDir = false )
 {
     $contents = file_get_contents( $filename );
 
@@ -96,7 +104,7 @@ function testFile( string $filename , bool $fragment = false )
         echo "Wrong XML file:\n";
         echo "  Issue: XML file with BOM. Several tools may misbehave.\n";
         echo "  Path:  $filename\n";
-        echo "  Hint:  You can try autofix this with 'doc-base/scripts/broken.php --dos2unix langdir'.\n";
+        echo "  Hint:  You can try auto fix this with 'doc-base/scripts/broken.php --dos2unix langdir'.\n";
         echo "\n";
         autofix_dos2unix( $filename );
     }
@@ -106,7 +114,16 @@ function testFile( string $filename , bool $fragment = false )
         echo "Wrong XML file:\n";
         echo "  Issue: XML file contains \\r. Several tools may misbehave.\n";
         echo "  Path:  $filename\n";
-        echo "  Hint:  You can try autofix this with 'doc-base/scripts/broken.php --dos2unix langdir'.\n";
+        echo "  Hint:  You can try auto fix this with 'doc-base/scripts/broken.php --dos2unix langdir'.\n";
+        echo "\n";
+        autofix_dos2unix( $filename );
+    }
+
+    if ( $checkDnt && strpos( $contents , '<?do-not-translate?>' ) !== false )
+    {
+        echo "File marked do-not-translate in translation:\n";
+        echo "  Issue: Manual build may fail.\n";
+        echo "  Path:  $filename\n";
         echo "\n";
         autofix_dos2unix( $filename );
     }
@@ -121,7 +138,7 @@ function testFile( string $filename , bool $fragment = false )
     $doc->substituteEntities = false;
     libxml_use_internal_errors( true );
 
-    if ( $fragment )
+    if ( $fragmentDir )
         $contents = "<f>{$contents}</f>";
     $doc->loadXML( $contents );
 
@@ -152,18 +169,18 @@ function testFile( string $filename , bool $fragment = false )
     }
 }
 
-function testDir( string $dir )
+function testDir( string $dir , bool $checkDnt )
 {
     $dir = realpath( $dir );
     $files = scandir( $dir );
-    $fragment = false;
+    $fragmentDir = false;
     $subdirs = [];
 
     foreach( $files as $file )
     {
         if ( $file == ".xmlfragmentdir" )
         {
-            $fragment = true;
+            $fragmentDir = true;
             continue;
         }
         if ( $file[0] == "." )
@@ -178,11 +195,11 @@ function testDir( string $dir )
         }
 
         if ( str_ends_with( $fullpath , ".xml" ) )
-            testFile( $fullpath , $fragment );
+            testFile( $fullpath , $checkDnt , $fragmentDir );
     }
 
     foreach( $subdirs as $dir )
-        testDir( $dir );
+        testDir( $dir , $checkDnt );
 }
 
 function autofix_dos2unix( string $filename )
diff --git a/scripts/translation/lib/RevcheckIgnore.php b/scripts/translation/lib/RevcheckIgnore.php
index 657d3707e2..27f77104d3 100644
--- a/scripts/translation/lib/RevcheckIgnore.php
+++ b/scripts/translation/lib/RevcheckIgnore.php
@@ -1,7 +1,7 @@
 <?php
 /**
  *  +----------------------------------------------------------------------+
- *  | Copyright (c) 1997-2023 The PHP Group                                |
+ *  | Copyright (c) 1997-2026 The PHP Group                                |
  *  +----------------------------------------------------------------------+
  *  | This source file is subject to version 3.01 of the PHP license,      |
  *  | that is bundled with this package in the file LICENSE, and is        |
@@ -65,4 +65,11 @@ public static function ignore( $filename ) : bool
         // At least, do not ignore
         return false;
     }
+
+    public static function mark( $filename )
+    {
+        $contents = file_get_contents( $filename );
+        $skip = strpos( $contents , '<?do-not-translate?>' ) !== false;
+        return $skip;
+    }
 }
diff --git a/scripts/translation/lib/RevcheckRun.php b/scripts/translation/lib/RevcheckRun.php
index e80f5dfb48..119dfebdb7 100644
--- a/scripts/translation/lib/RevcheckRun.php
+++ b/scripts/translation/lib/RevcheckRun.php
@@ -82,6 +82,9 @@ private function calculateStatus()
 
             if ( $target == null )
             {
+                if ( RevcheckIgnore::mark( "{$this->sourceDir}/{$source->file}" ) )
+                    continue;
+
                 $source->status = RevcheckStatus::Untranslated;
                 $this->filesUntranslated[] = $source;
                 $this->addData( $source , null );

From 432b59fdba655e66fdfed613b2e538ba02603618 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9=20L=20F=20S=20Bacci?= <ae@php.net>
Date: Sat, 27 Jun 2026 12:10:28 -0300
Subject: [PATCH 2/2] Update docs

---
 docs/editing.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/docs/editing.md b/docs/editing.md
index b73f75a676..bb1111318a 100644
--- a/docs/editing.md
+++ b/docs/editing.md
@@ -38,6 +38,9 @@ Changes in the English version are eventually picked up by the translators.
 If a change doesn't affect translations (e.g. fixing a typo in English) then the
 commit message should start with `[skip-revcheck]`.
 
+Files that are not to be translated, or copied on translations, should include
+an `<?do-not-translate?>` mark.
+
 ## Validating your changes
 Every time you make changes to documentation sources (both English or translation),
 you have to validate your changes to ensure that the manual still builds without error.