feature #30909 [Translator] Add comments when dumping po files (deguif)

This PR was merged into the 4.3-dev branch.

Discussion
----------

[Translator] Add comments when dumping po files

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | ?    <!-- please add some, will be required by reviewers -->
| Fixed tickets | #29962
| License       | MIT
| Doc PR        |

This code
```php
$catalogue = new MessageCatalogue('fr');
$dumper = new PoFileDumper();

$catalogue->set('key.one', 'First key', 'custom');
$catalogue->setMetadata('key.one', ['sources' => 'src/file_1', 'comments' => 'Comment', 'flags' => 'fuzzy'], 'custom');

$catalogue->set('key.second', 'Second key', 'custom');
$catalogue->setMetadata('key.second', ['sources' => ['src/file_1', 'src/file_2'], 'comments' => ['Comment 1', 'Comment 2'], 'flags' => ['fuzzy', 'another']], 'custom');

$dumper->dump($catalogue, [
    'path' => 'xxx',
]);
```

Will produces this output:
```
msgid ""
msgstr ""
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Language: fr\n"

# Comment
#, fuzzy
#: src/file_1
msgid "key.one"
msgstr "First key"

# Comment 1
# Comment 2
#, fuzzy,another
#: src/file_1 src/file_2
msgid "key.second"
msgstr "Second key"
```

Commits
-------

31b3a55787 Add comments when dumping po files

src/Symfony/Component/Translation/Dumper/PoFileDumper.php

@@ -39,6 +39,18 @@ class PoFileDumper extends FileDumper
             } else {
                 $newLine = true;
             }
+            $metadata = $messages->getMetadata($source, $domain);
+
+            if (isset($metadata['comments'])) {
+                $output .= $this->formatComments($metadata['comments']);
+            }
+            if (isset($metadata['flags'])) {
+                $output .= $this->formatComments(implode(',', (array) $metadata['flags']), ',');
+            }
+            if (isset($metadata['sources'])) {
+                $output .= $this->formatComments(implode(' ', (array) $metadata['sources']), ':');
+            }
+
             $output .= sprintf('msgid "%s"'."\n", $this->escape($source));
             $output .= sprintf('msgstr "%s"'."\n", $this->escape($target));
         }
@@ -58,4 +70,15 @@ class PoFileDumper extends FileDumper
     {
         return addcslashes($str, "\0..\37\42\134");
     }
+
+    private function formatComments($comments, string $prefix = ''): ?string
+    {
+        $output = null;
+
+        foreach ((array) $comments as $comment) {
+            $output .= sprintf('#%s %s'."\n", $prefix, $comment);
+        }
+
+        return $output;
+    }
 }

src/Symfony/Component/Translation/Tests/Dumper/PoFileDumperTest.php

@@ -20,7 +20,26 @@ class PoFileDumperTest extends TestCase
     public function testFormatCatalogue()
     {
         $catalogue = new MessageCatalogue('en');
-        $catalogue->add(['foo' => 'bar', 'bar' => 'foo']);
+        $catalogue->add(['foo' => 'bar', 'bar' => 'foo', 'foo_bar' => 'foobar', 'bar_foo' => 'barfoo']);
+        $catalogue->setMetadata('foo_bar', [
+            'comments' => [
+                'Comment 1',
+                'Comment 2',
+            ],
+            'flags' => [
+                'fuzzy',
+                'another',
+            ],
+            'sources' => [
+                'src/file_1',
+                'src/file_2:50',
+            ],
+        ]);
+        $catalogue->setMetadata('bar_foo', [
+            'comments' => 'Comment',
+            'flags' => 'fuzzy',
+            'sources' => 'src/file_1',
+        ]);
 
         $dumper = new PoFileDumper();
 

src/Symfony/Component/Translation/Tests/fixtures/resources.po

@@ -9,3 +9,16 @@ msgstr "bar"
 
 msgid "bar"
 msgstr "foo"
+
+# Comment 1
+# Comment 2
+#, fuzzy,another
+#: src/file_1 src/file_2:50
+msgid "foo_bar"
+msgstr "foobar"
+
+# Comment
+#, fuzzy
+#: src/file_1
+msgid "bar_foo"
+msgstr "barfoo"