@translate annotation: allows to add any string to dictionary (#107)

* @translate annotation: allows to add any string to dictionary

* applying styleci

* php5.x compatibility

* weird behavior of ValidatorAnnotation (which affects usage of "@translate" annotation in some use cases)

* removal of test files related to ValidatorAnnotation issues

Author: noofaq

src/Annotation/Translate.php

@@ -0,0 +1,41 @@
+<?php
+
+/*
+ * This file is part of the PHP Translation package.
+ *
+ * (c) PHP Translation team <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Translation\Extractor\Annotation;
+
+/**
+ * @Annotation
+ */
+class Translate
+{
+    /** @var string */
+    private $domain = 'messages';
+
+    /**
+     * Translate constructor.
+     *
+     * @param array $values
+     */
+    public function __construct($values)
+    {
+        if (isset($values['domain'])) {
+            $this->domain = $values['domain'];
+        }
+    }
+
+    /**
+     * @return string
+     */
+    public function getDomain()
+    {
+        return $this->domain;
+    }
+}

src/Visitor/Php/TranslateAnnotationVisitor.php

@@ -0,0 +1,85 @@
+<?php
+
+/*
+ * This file is part of the PHP Translation package.
+ *
+ * (c) PHP Translation team <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Translation\Extractor\Visitor\Php;
+
+use Doctrine\Common\Annotations\DocParser;
+use PhpParser\Comment;
+use PhpParser\Node;
+use PhpParser\NodeVisitor;
+use Translation\Extractor\Annotation\Translate;
+
+/**
+ * Class TranslationAnnotationVisitor.
+ *
+ * Supports using @Translate annotation for marking string nodes to be added to the dictionary
+ */
+class TranslateAnnotationVisitor extends BasePHPVisitor implements NodeVisitor
+{
+    /** @var DocParser */
+    protected $translateDocParser;
+
+    /**
+     * @return DocParser
+     */
+    private function getTranslateDocParser()
+    {
+        if (null === $this->translateDocParser) {
+            $this->translateDocParser = new DocParser();
+
+            $this->translateDocParser->setImports([
+                'translate' => Translate::class,
+            ]);
+            $this->translateDocParser->setIgnoreNotImportedAnnotations(true);
+        }
+
+        return $this->translateDocParser;
+    }
+
+    public function enterNode(Node $node)
+    {
+        // look for strings
+        if (!$node instanceof Node\Scalar\String_) {
+            return null;
+        }
+
+        //look for string with comment
+        $comments = $node->getAttribute('comments', []);
+        if (!count($comments)) {
+            return null;
+        }
+
+        foreach ($comments as $comment) {
+            if (!$comment instanceof Comment\Doc) {
+                return null;
+            }
+
+            foreach ($this->getTranslateDocParser()->parse($comment->getText()) as $annotation) {
+                //add phrase to dictionary
+                $this->addLocation($node->value, $node->getAttribute('startLine'), $node, ['domain' => $annotation->getDomain()]);
+
+                break;
+            }
+        }
+    }
+
+    public function leaveNode(Node $node)
+    {
+    }
+
+    public function beforeTraverse(array $nodes)
+    {
+    }
+
+    public function afterTraverse(array $nodes)
+    {
+    }
+}

tests/Functional/Visitor/Php/TranslateAnnotationVisitorTest.php

@@ -0,0 +1,38 @@
+<?php
+
+/*
+ * This file is part of the PHP Translation package.
+ *
+ * (c) PHP Translation team <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Translation\Extractor\Tests\Functional\Visitor\Php;
+
+use Translation\Extractor\Tests\Resources\Php\TestTranslateAnnotationFile;
+use Translation\Extractor\Visitor\Php\TranslateAnnotationVisitor;
+
+final class TranslateAnnotationVisitorTest extends BasePHPVisitorTest
+{
+    public function testExtract()
+    {
+        $collection = $this->getSourceLocations(new TranslateAnnotationVisitor(),
+            TestTranslateAnnotationFile::class);
+
+        $this->assertCount(4, $collection);
+
+        $this->assertEquals('const_for_translation', $collection->get(0)->getMessage());
+        $this->assertEquals(['domain' => 'messages'], $collection->get(0)->getContext());
+
+        $this->assertEquals('x_to_messages_implicit', $collection->get(1)->getMessage());
+        $this->assertEquals(['domain' => 'messages'], $collection->get(1)->getContext());
+
+        $this->assertEquals('y_to_messages_explicit', $collection->get(2)->getMessage());
+        $this->assertEquals(['domain' => 'messages'], $collection->get(2)->getContext());
+
+        $this->assertEquals('z_to_validators_explicit', $collection->get(3)->getMessage());
+        $this->assertEquals(['domain' => 'validators'], $collection->get(3)->getContext());
+    }
+}

tests/Resources/Php/TestTranslateAnnotationFile.php

@@ -0,0 +1,25 @@
+<?php
+
+
+namespace Translation\Extractor\Tests\Resources\Php;
+
+use Translation\Extractor\Annotation\Desc;
+
+class TestTranslateAnnotationFile
+{
+    const SOME_CONST = /** @Translate */'const_for_translation';
+
+    protected function test()
+    {
+        $a = 'not_commented';
+        $b = /* some weird comment */'commented';
+        $c = 'commented_too'; //some other weird comment
+        $d = /* @Translate */'incorrectly_annotated';
+        $e = /** @foo */'unknown_annotation';
+        $f = /** @Desc(text="something) */'desc_annotation';
+
+        $x = /** @Translate */'x_to_messages_implicit';
+        $y = /** @Translate(domain="messages") */'y_to_messages_explicit';
+        $z = /** @Translate(domain="validators") */'z_to_validators_explicit';
+    }
+}

tests/Smoke/AllExtractorsTest.php

@@ -29,6 +29,7 @@
 use Translation\Extractor\Visitor\Php\Symfony\FormTypeLabelExplicit;
 use Translation\Extractor\Visitor\Php\Symfony\FormTypeLabelImplicit;
 use Translation\Extractor\Visitor\Php\Symfony\FormTypePlaceholder;
+use Translation\Extractor\Visitor\Php\TranslateAnnotationVisitor;
 use Translation\Extractor\Visitor\Twig\TwigVisitorFactory;
 
 /**
@@ -153,6 +154,7 @@ private function getPHPFileExtractor()
         $file->addVisitor(new FormTypeLabelImplicit());
         $file->addVisitor(new FormTypePlaceholder());
         $file->addVisitor(new SourceLocationContainerVisitor());
+        $file->addVisitor(new TranslateAnnotationVisitor());
 
         return $file;
     }