[Translations] Add seperate CREATE endpoint (#991)

lukmzig · web-flow · commit f7411634a32f · 2025-04-03T10:49:59.000+02:00
* feat: add translation create endpoint

* Apply php-cs-fixer changes
diff --git a/src/Translation/Controller/CreateController.php b/src/Translation/Controller/CreateController.php
@@ -0,0 +1,78 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * Pimcore
+ *
+ * This source file is available under two different licenses:
+ * - GNU General Public License version 3 (GPLv3)
+ * - Pimcore Commercial License (PCL)
+ * Full copyright and license information is available in
+ * LICENSE.md which is distributed with this source code.
+ *
+ *  @copyright  Copyright (c) Pimcore GmbH (http://www.pimcore.org)
+ *  @license    http://www.pimcore.org/license     GPLv3 and PCL
+ */
+
+namespace Pimcore\Bundle\StudioBackendBundle\Translation\Controller;
+
+use OpenApi\Attributes\Post;
+use Pimcore\Bundle\StudioBackendBundle\Controller\AbstractApiController;
+use Pimcore\Bundle\StudioBackendBundle\Exception\Api\ElementExistsException;
+use Pimcore\Bundle\StudioBackendBundle\OpenApi\Attribute\Response\DefaultResponses;
+use Pimcore\Bundle\StudioBackendBundle\OpenApi\Attribute\Response\SuccessResponse;
+use Pimcore\Bundle\StudioBackendBundle\OpenApi\Config\Tags;
+use Pimcore\Bundle\StudioBackendBundle\Translation\Attribute\Request\TranslationRequestBody;
+use Pimcore\Bundle\StudioBackendBundle\Translation\Schema\CreateTranslation;
+use Pimcore\Bundle\StudioBackendBundle\Translation\Service\TranslatorServiceInterface;
+use Pimcore\Bundle\StudioBackendBundle\Util\Constant\HttpResponseCodes;
+use Pimcore\Bundle\StudioBackendBundle\Util\Constant\UserPermissions;
+use Symfony\Component\HttpFoundation\Response;
+use Symfony\Component\HttpKernel\Attribute\MapRequestPayload;
+use Symfony\Component\Routing\Attribute\Route;
+use Symfony\Component\Security\Http\Attribute\IsGranted;
+use Symfony\Component\Serializer\SerializerInterface;
+
+/**
+ * @internal
+ */
+final class CreateController extends AbstractApiController
+{
+    private const string ROUTE = '/translations/create';
+
+    public function __construct(
+        SerializerInterface $serializer,
+        private readonly TranslatorServiceInterface $translatorService
+    ) {
+        parent::__construct($serializer);
+    }
+
+    /**
+     * @throws ElementExistsException
+     */
+    #[Route(self::ROUTE, name: 'pimcore_studio_api_translations_create', methods: ['POST'])]
+    #[IsGranted(UserPermissions::TRANSLATIONS->value)]
+    #[Post(
+        path: self::PREFIX . self::ROUTE,
+        operationId: 'translation_create',
+        description: 'translation_create_description',
+        summary: 'translation_create_summary',
+        tags: [Tags::Translation->name]
+    )]
+    #[TranslationRequestBody(CreateTranslation::class)]
+    #[SuccessResponse(
+        description: 'translation_create_success_response'
+    )]
+    #[DefaultResponses([
+        HttpResponseCodes::CONFLICT,
+        HttpResponseCodes::NOT_FOUND,
+        HttpResponseCodes::UNAUTHORIZED,
+    ])]
+    public function createTranslations(
+        #[MapRequestPayload] CreateTranslation $translation
+    ): Response {
+        $this->translatorService->createTranslations($translation);
+
+        return new Response();
+    }
+}
diff --git a/src/Translation/Repository/TranslationRepository.php b/src/Translation/Repository/TranslationRepository.php
@@ -17,13 +17,15 @@
 namespace Pimcore\Bundle\StudioBackendBundle\Translation\Repository;
 
 use Pimcore\Bundle\StaticResolverBundle\Lib\Tools\AdminResolverInterface;
+use Pimcore\Bundle\StudioBackendBundle\Exception\Api\ElementExistsException;
 use Pimcore\Bundle\StudioBackendBundle\Exception\Api\InvalidLocaleException;
 use Pimcore\Bundle\StudioBackendBundle\Exception\Api\NotFoundException;
 use Pimcore\Bundle\StudioBackendBundle\Translation\Schema\TranslationData;
 use Pimcore\Bundle\StudioBackendBundle\Translation\Service\TranslatorServiceInterface;
 use Pimcore\Model\Translation;
 use Pimcore\Model\Translation\Listing;
 use function in_array;
+use function sprintf;
 
 /**
  * @internal
@@ -53,23 +55,48 @@ public function getAllTranslations(string $locale): array
     /**
      * {@inheritdoc}
      */
-    public function createTranslations(array $translationData, string $locale): void
+    public function createTranslations(string $key, string $type): void
+    {
+        $languages = $this->adminResolver->getLanguages();
+
+        if ($this->getTranslationByKey($key) !== null) {
+            throw new ElementExistsException(
+                sprintf("Translation with key '%s' already exists", $key),
+            );
+        }
+
+        $t = new Translation();
+        $t->setDomain(TranslatorServiceInterface::DOMAIN);
+        $t->setKey($key);
+        $t->setType($type);
+        $t->setCreationDate(time());
+        $t->setModificationDate(time());
+        $this->setNewValues($t, $languages);
+        $t->save();
+
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function updateTranslations(array $translationData, string $locale): void
     {
         $languages = $this->adminResolver->getLanguages();
         $this->validateLocale($locale, $languages);
 
         /** @var TranslationData $translation */
         foreach ($translationData as $translation) {
+            if ($this->getTranslationByKey($translation->getKey()) === null) {
+                throw new NotFoundException('translation', $translation->getKey(), 'key');
+            }
+
             $t = new Translation();
             $t->setDomain(TranslatorServiceInterface::DOMAIN);
             $t->setKey($translation->getKey());
             $t->setType($translation->getType());
             $t->addTranslation($locale, $translation->getTranslation());
             $t->setCreationDate(time());
             $t->setModificationDate(time());
-            if ($this->getTranslationByKey($translation->getKey()) === null) {
-                $this->setNewValues($t, $languages, $locale);
-            }
             $t->save();
         }
     }
@@ -94,14 +121,10 @@ private function getTranslationList(): Listing
         return $list;
     }
 
-    private function setNewValues(Translation $translation, array $languages, string $locale): void
+    private function setNewValues(Translation $translation, array $languages): void
     {
-        $translation->setCreationDate(time());
-
         foreach ($languages as $language) {
-            if ($language !== $locale) {
-                $translation->addTranslation($language, '');
-            }
+            $translation->addTranslation($language, '');
         }
     }
 
diff --git a/src/Translation/Repository/TranslationRepositoryInterface.php b/src/Translation/Repository/TranslationRepositoryInterface.php
@@ -16,6 +16,7 @@
 
 namespace Pimcore\Bundle\StudioBackendBundle\Translation\Repository;
 
+use Pimcore\Bundle\StudioBackendBundle\Exception\Api\ElementExistsException;
 use Pimcore\Bundle\StudioBackendBundle\Exception\Api\InvalidLocaleException;
 use Pimcore\Bundle\StudioBackendBundle\Translation\Schema\TranslationData;
 use Pimcore\Model\Translation;
@@ -32,12 +33,17 @@ interface TranslationRepositoryInterface
      */
     public function getAllTranslations(string $locale): array;
 
+    /**
+     * @throws ElementExistsException
+     */
+    public function createTranslations(string $key, string $type): void;
+
     /**
      * @param array<TranslationData> $translationData
      *
      * @throws InvalidLocaleException
      */
-    public function createTranslations(array $translationData, string $locale): void;
+    public function updateTranslations(array $translationData, string $locale): void;
 
     public function deleteTranslation(string $key): void;
 }
diff --git a/src/Translation/Schema/CreateTranslation.php b/src/Translation/Schema/CreateTranslation.php
@@ -0,0 +1,51 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * Pimcore
+ *
+ * This source file is available under two different licenses:
+ * - GNU General Public License version 3 (GPLv3)
+ * - Pimcore Commercial License (PCL)
+ * Full copyright and license information is available in
+ * LICENSE.md which is distributed with this source code.
+ *
+ *  @copyright  Copyright (c) Pimcore GmbH (http://www.pimcore.org)
+ *  @license    http://www.pimcore.org/license     GPLv3 and PCL
+ */
+
+namespace Pimcore\Bundle\StudioBackendBundle\Translation\Schema;
+
+use OpenApi\Attributes\Property;
+use OpenApi\Attributes\Schema;
+
+/**
+ * @internal
+ */
+#[Schema(
+    schema: 'CreateTranslation',
+    title: 'Translation Create',
+    description: 'Translation Crete Scheme for API',
+    required: ['key', 'type'],
+    type: 'object'
+)]
+final readonly class CreateTranslation
+{
+    public function __construct(
+        #[Property(description: 'Key', type: 'string', example: 'my_translation_key')]
+        private string $key,
+        #[Property(description: 'Type', type: 'string', example: 'simple')]
+        private string $type = 'simple',
+    ) {
+    }
+
+    public function getKey(): string
+    {
+        return $this->key;
+    }
+
+    public function getType(): string
+    {
+        return $this->type;
+    }
+}
diff --git a/src/Translation/Service/TranslatorService.php b/src/Translation/Service/TranslatorService.php
@@ -19,6 +19,7 @@
 use InvalidArgumentException;
 use Pimcore\Bundle\StudioBackendBundle\Exception\Api\InvalidLocaleException;
 use Pimcore\Bundle\StudioBackendBundle\Translation\Repository\TranslationRepositoryInterface;
+use Pimcore\Bundle\StudioBackendBundle\Translation\Schema\CreateTranslation;
 use Pimcore\Bundle\StudioBackendBundle\Translation\Schema\Translation;
 use Pimcore\Bundle\StudioBackendBundle\Translation\Schema\UpdateTranslation;
 use Symfony\Component\Translation\TranslatorBagInterface;
@@ -41,9 +42,14 @@ public function __construct(
         $this->translatorBag = $this->getTranslatorBag();
     }
 
+    public function createTranslations(CreateTranslation $translation): void
+    {
+        $this->translationRepository->createTranslations($translation->getKey(), $translation->getType());
+    }
+
     public function updateTranslations(UpdateTranslation $translation): void
     {
-        $this->translationRepository->createTranslations($translation->getTranslationData(), $translation->getLocale());
+        $this->translationRepository->updateTranslations($translation->getTranslationData(), $translation->getLocale());
     }
 
     /**
diff --git a/src/Translation/Service/TranslatorServiceInterface.php b/src/Translation/Service/TranslatorServiceInterface.php
@@ -16,7 +16,9 @@
 
 namespace Pimcore\Bundle\StudioBackendBundle\Translation\Service;
 
+use Pimcore\Bundle\StudioBackendBundle\Exception\Api\ElementExistsException;
 use Pimcore\Bundle\StudioBackendBundle\Exception\Api\InvalidLocaleException;
+use Pimcore\Bundle\StudioBackendBundle\Translation\Schema\CreateTranslation;
 use Pimcore\Bundle\StudioBackendBundle\Translation\Schema\Translation;
 use Pimcore\Bundle\StudioBackendBundle\Translation\Schema\UpdateTranslation;
 
@@ -27,6 +29,14 @@ interface TranslatorServiceInterface
 {
     public const string DOMAIN = 'studio';
 
+    /**
+     * @throws ElementExistsException
+     */
+    public function createTranslations(CreateTranslation $translation): void;
+
+    /**
+     * @throws InvalidLocaleException
+     */
     public function updateTranslations(UpdateTranslation $translation): void;
 
     /**
diff --git a/translations/studio_api_docs.en.yaml b/translations/studio_api_docs.en.yaml
@@ -618,13 +618,19 @@ thumbnail_video_get_collection_description: |
   Get collection of all thumbnails for videos.
 thumbnail_video_get_collection_success_response: All video thumbnails
 thumbnail_video_get_collection_summary: Get collection of thumbnails for videos
+translation_create_description: | 
+  Add new translation entries for given translation key
+translation_create_success_response: Successfully created translations
+translation_create_summary: Create translations
 translation_get_collection_description: Get translations for given keys and locale
 translation_get_collection_success_response: Key value pairs for given keys and locale
 translation_get_collection_summary: Get translations
 translation_delete_by_key_description: Delete translations for given translation key
 translation_delete_by_key_success_response: Successfully deleted translations
 translation_delete_by_key_summary: Delete translations
-translation_update_description: Update translations for given translation data and locale
+translation_update_description: |
+  Update translations for given translation data and locale.The <strong>{key}</strong> must be an existing translation key. <br> 
+  See the full description of updatable translation data fields with the schema <strong>TranslationData</strong>
 translation_update_success_response: Successfully updated translations
 translation_update_summary: Update translations
 user_clone_by_id_success_response: Node of the cloned user.
