feat: add reader/writer format for Crowdin (#26)

Author: ramsey

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ### Added
 
+- Add [Crowdin](https://crowdin.com) as a format for writing and reading extracted messages
 - Add `pseudo-locale` console command to allow conversion of a locale to one of the supported pseudo-locales (`en-XA`, `en-XB`, `xx-AC`, `xx-HA`, and `xx-LS`).
 - Provide `--flatten` extraction option to tell the extractor to hoist selectors and flatten sentences as much as possible. For example, `I have {count, plural, one{a dog} other{many dogs}}` becomes `{count, plural, one{I have a dog} other{I have many dogs}}`. The goal is to provide as many full sentences as possible, since fragmented sentences are not translator-friendly.
 - Provide `--add-missing-ids` extraction option to update source code with auto-generated identifiers

src/Format/Format.php

@@ -27,6 +27,8 @@
  */
 class Format
 {
+    public const CHROME = 'chrome';
+    public const CROWDIN = 'crowdin';
     public const FORMATPHP = 'formatphp';
     public const SIMPLE = 'simple';
     public const SMARTLING = 'smartling';

src/Format/Reader/ChromeReader.php

@@ -0,0 +1,84 @@
+<?php
+
+/**
+ * This file is part of skillshare/formatphp
+ *
+ * skillshare/formatphp is open source software: you can distribute
+ * it and/or modify it under the terms of the MIT License
+ * (the "License"). You may not use this file except in
+ * compliance with the License.
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ * implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ *
+ * @copyright Copyright (c) Skillshare, Inc. <https://www.skillshare.com>
+ * @license https://opensource.org/licenses/MIT MIT License
+ */
+
+declare(strict_types=1);
+
+namespace FormatPHP\Format\Reader;
+
+use FormatPHP\Exception\InvalidMessageShapeException;
+use FormatPHP\Format\ReaderInterface;
+use FormatPHP\Message;
+use FormatPHP\MessageCollection;
+
+use function gettype;
+use function is_array;
+use function is_string;
+use function sprintf;
+
+/**
+ * Returns a MessageCollection parsed from JSON-decoded data that was written
+ * using {@see ChromeWriter}
+ */
+class ChromeReader implements ReaderInterface
+{
+    /**
+     * @inheritdoc
+     */
+    public function __invoke(array $data): MessageCollection
+    {
+        $messages = new MessageCollection();
+
+        /**
+         * @var string $messageId
+         * @var array{message: string} $message
+         */
+        foreach ($data as $messageId => $message) {
+            $this->validateShape($messageId, $message);
+
+            $messages[] = new Message($messageId, $message['message']);
+        }
+
+        return $messages;
+    }
+
+    /**
+     * @param array-key $messageId
+     * @param mixed $message
+     *
+     * @throws InvalidMessageShapeException
+     */
+    private function validateShape($messageId, $message): void
+    {
+        if (!is_string($messageId)) {
+            throw new InvalidMessageShapeException(sprintf(
+                '%s expects a string message ID; received %s',
+                static::class,
+                gettype($messageId),
+            ));
+        }
+
+        if (!is_array($message) || !is_string($message['message'] ?? null)) {
+            throw new InvalidMessageShapeException(sprintf(
+                '%s expects a string message property; message does not exist or is not a string',
+                static::class,
+            ));
+        }
+    }
+}

src/Format/Reader/CrowdinReader.php

@@ -0,0 +1,31 @@
+<?php
+
+/**
+ * This file is part of skillshare/formatphp
+ *
+ * skillshare/formatphp is open source software: you can distribute
+ * it and/or modify it under the terms of the MIT License
+ * (the "License"). You may not use this file except in
+ * compliance with the License.
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ * implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ *
+ * @copyright Copyright (c) Skillshare, Inc. <https://www.skillshare.com>
+ * @license https://opensource.org/licenses/MIT MIT License
+ */
+
+declare(strict_types=1);
+
+namespace FormatPHP\Format\Reader;
+
+/**
+ * Returns a MessageCollection parsed from JSON-decoded data that was written
+ * using {@see CrowdinWriter}
+ */
+class CrowdinReader extends ChromeReader
+{
+}

src/Format/Reader/FormatPHPReader.php

@@ -24,7 +24,6 @@
 
 use FormatPHP\Exception\InvalidMessageShapeException;
 use FormatPHP\Format\ReaderInterface;
-use FormatPHP\Format\Writer\FormatPHPWriter;
 use FormatPHP\Message;
 use FormatPHP\MessageCollection;
 
@@ -35,9 +34,7 @@
 
 /**
  * Returns a MessageCollection parsed from JSON-decoded data that was written
- * using Writer\Format\FormatPHP
- *
- * @see FormatPHPWriter
+ * using {@see FormatPHPWriter}
  */
 class FormatPHPReader implements ReaderInterface
 {

src/Format/Reader/SimpleReader.php

@@ -24,7 +24,6 @@
 
 use FormatPHP\Exception\InvalidMessageShapeException;
 use FormatPHP\Format\ReaderInterface;
-use FormatPHP\Format\Writer\SimpleWriter;
 use FormatPHP\Message;
 use FormatPHP\MessageCollection;
 
@@ -35,9 +34,7 @@
 
 /**
  * Returns a MessageCollection parsed from JSON-decoded data that was written
- * using Writer\Format\Simple
- *
- * @see SimpleWriter
+ * using {@see SimpleWriter}
  */
 class SimpleReader implements ReaderInterface
 {

src/Format/Reader/SmartlingReader.php

@@ -22,68 +22,21 @@
 
 namespace FormatPHP\Format\Reader;
 
-use FormatPHP\Exception\InvalidMessageShapeException;
-use FormatPHP\Format\ReaderInterface;
-use FormatPHP\Format\Writer\SmartlingWriter;
-use FormatPHP\Message;
 use FormatPHP\MessageCollection;
 
-use function gettype;
-use function is_array;
-use function is_string;
-use function sprintf;
-
 /**
  * Returns a MessageCollection parsed from JSON-decoded data that was written
- * using Writer\Format\Smartling
- *
- * @see SmartlingWriter
+ * using {@see SmartlingWriter}
  */
-class SmartlingReader implements ReaderInterface
+class SmartlingReader extends ChromeReader
 {
     /**
      * @inheritdoc
      */
     public function __invoke(array $data): MessageCollection
     {
-        $messages = new MessageCollection();
-
         unset($data['smartling']);
 
-        /**
-         * @var string $messageId
-         * @var array{message: string} $message
-         */
-        foreach ($data as $messageId => $message) {
-            $this->validateShape($messageId, $message);
-
-            $messages[] = new Message($messageId, $message['message']);
-        }
-
-        return $messages;
-    }
-
-    /**
-     * @param array-key $messageId
-     * @param mixed $message
-     *
-     * @throws InvalidMessageShapeException
-     */
-    private function validateShape($messageId, $message): void
-    {
-        if (!is_string($messageId)) {
-            throw new InvalidMessageShapeException(sprintf(
-                '%s expects a string message ID; received %s',
-                self::class,
-                gettype($messageId),
-            ));
-        }
-
-        if (!is_array($message) || !is_string($message['message'] ?? null)) {
-            throw new InvalidMessageShapeException(sprintf(
-                '%s expects a string message property; message does not exist or is not a string',
-                self::class,
-            ));
-        }
+        return parent::__invoke($data);
     }
 }

src/Format/Writer/ChromeWriter.php

@@ -0,0 +1,70 @@
+<?php
+
+/**
+ * This file is part of skillshare/formatphp
+ *
+ * skillshare/formatphp is open source software: you can distribute
+ * it and/or modify it under the terms of the MIT License
+ * (the "License"). You may not use this file except in
+ * compliance with the License.
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ * implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ *
+ * @copyright Copyright (c) Skillshare, Inc. <https://www.skillshare.com>
+ * @license https://opensource.org/licenses/MIT MIT License
+ */
+
+declare(strict_types=1);
+
+namespace FormatPHP\Format\Writer;
+
+use FormatPHP\DescriptorCollection;
+use FormatPHP\Format\Reader\ChromeReader;
+use FormatPHP\Format\WriterInterface;
+use FormatPHP\Format\WriterOptions;
+
+/**
+ * Chrome formatter for FormatPHP
+ *
+ * This implements the Chrome JSON format.
+ *
+ * ```json
+ * {
+ *   "my.message": {
+ *     "description": "And I'm providing more details for translators here."
+ *     "message": "This is a message for translation."
+ *   }
+ * }
+ * ```
+ *
+ * @link hhttps://developer.chrome.com/docs/extensions/mv3/i18n-messages/ Chrome JSON format
+ * @see ChromeReader
+ */
+class ChromeWriter implements WriterInterface
+{
+    /**
+     * @inheritdoc
+     */
+    public function __invoke(DescriptorCollection $collection, WriterOptions $options): array
+    {
+        $format = [];
+
+        foreach ($collection as $item) {
+            $message = [];
+
+            if ($item->getDescription() !== null) {
+                $message['description'] = $item->getDescription();
+            }
+
+            $message['message'] = $item->getDefaultMessage() ?? '';
+
+            $format[(string) $item->getId()] = $message;
+        }
+
+        return $format;
+    }
+}

src/Format/Writer/CrowdinWriter.php

@@ -0,0 +1,45 @@
+<?php
+
+/**
+ * This file is part of skillshare/formatphp
+ *
+ * skillshare/formatphp is open source software: you can distribute
+ * it and/or modify it under the terms of the MIT License
+ * (the "License"). You may not use this file except in
+ * compliance with the License.
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ * implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ *
+ * @copyright Copyright (c) Skillshare, Inc. <https://www.skillshare.com>
+ * @license https://opensource.org/licenses/MIT MIT License
+ */
+
+declare(strict_types=1);
+
+namespace FormatPHP\Format\Writer;
+
+/**
+ * Crowdin formatter for FormatPHP
+ *
+ * This follows the same format as the Crowdin formatter for FormatJS and
+ * implements the Crowdin Chrome JSON format.
+ *
+ * ```json
+ * {
+ *   "my.message": {
+ *     "description": "And I'm providing more details for translators here."
+ *     "message": "This is a message for translation."
+ *   }
+ * }
+ * ```
+ *
+ * @link https://support.crowdin.com/file-formats/chrome-json/ Crowdin Chrome JSON format
+ * @see CrowdinReader
+ */
+class CrowdinWriter extends ChromeWriter
+{
+}