docs: add all files translation example

content/1.docs/2.content-translator/3.php-api.md

@@ -206,7 +206,6 @@ Create a new PHP file for your command, for example `site/commands/translate-pag
 
 ```php
 use Kirby\CLI\CLI;
-use Kirby\Cms\App;
 
 return [
     'description' => 'Translates the content of a specific page.',
@@ -254,7 +253,6 @@ Create a new PHP file for your command, for example `site/commands/translate-chi
 
 ```php
 use Kirby\CLI\CLI;
-use Kirby\Cms\App;
 
 return [
     'description' => 'Translates the content of all children of a specific page.',
@@ -297,3 +295,54 @@ Run the command in your terminal:
 # Translate all children of a selected page to German
 kirby translate-children de
 ```
+
+#### Translate Files Metadata of a Page
+
+Most of the time, you will want to translate the content of a page. But sometimes, you might want to translate the metadata of files (like the title or description) of a page. Use the `translate-files.php` command to translate the files metadata of all children of a specific page:
+
+```php
+use Kirby\CLI\CLI;
+
+return [
+    'description' => 'Translates the files metadata of listed children pages.',
+    'args' => [
+        'language' => [
+            'description' => 'The target language to translate the content to.',
+            'defaultValue' => 'de'
+        ]
+    ],
+    'command' => static function (CLI $cli): void {
+        $kirby = $cli->kirby();
+        $defaultLanguage = $kirby->defaultLanguage()->code();
+        $targetLanguage = $cli->arg('language');
+
+        $siteChildren = $kirby->site()->children();
+        $input = $cli->radio(
+            'Which page\'s files metadata should be translated?',
+            $siteChildren->pluck('title')
+        );
+        $response = $input->prompt();
+        $cli->success('Selected parent page: ' . $response);
+
+        $page = $siteChildren->findBy('title', $response);
+
+        foreach ($page->children()->listed() as $child) {
+            foreach ($child->files() as $file) {
+                $translator = $file->translator();
+                $translator->copyContent($targetLanguage, $defaultLanguage);
+                $translator->translateContent($targetLanguage, $targetLanguage, $defaultLanguage);
+                $cli->out('Translated ' . $file->id() . ' metadata');
+            }
+        }
+
+        $cli->success('Successfully translated all ' . $page->id() . ' files');
+    }
+];
+```
+
+Run the command in your terminal:
+
+```bash
+# Translate all children of a selected page to German
+kirby translate-files de
+```