[DOC-CVS] [doc-base] master: Creates the do-not-translate mark (#311)

Author: alfsb (alfsb)
Committer: GitHub (web-flow)
Pusher: alfsb
Date: 2026-07-06T09:33:46-03:00

Commit: https://github.com/php/doc-base/commit/d8c8493247061a9cafc1fea5dd8a9abd3f4a9f61
Raw diff: https://github.com/php/doc-base/commit/d8c8493247061a9cafc1fea5dd8a9abd3f4a9f61.diff

Creates the do-not-translate mark (#311)

Changed paths:
  M  docs/editing.md
  M  scripts/broken.php
  M  scripts/translation/lib/RevcheckIgnore.php
  M  scripts/translation/lib/RevcheckRun.php


Diff:

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.
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 );