IBX-12091: Added TypeScript translation extraction support

.github/workflows/backend-ci.yaml

@@ -84,6 +84,13 @@ jobs:
             satis-network-key: ${{ secrets.SATIS_NETWORK_KEY }}
             satis-network-token: ${{ secrets.SATIS_NETWORK_TOKEN }}
 
+      - uses: actions/setup-node@v7
+        with:
+            node-version: '24'
+
+      - name: Install frontend dependencies
+        run: yarn install --frozen-lockfile --ignore-scripts
+
       - name: Setup problem matchers for PHPUnit
         run: echo "::add-matcher::${{ runner.tool_cache }}/phpunit.json"
 
@@ -131,6 +138,13 @@ jobs:
               satis-network-key: ${{ secrets.SATIS_NETWORK_KEY }}
               satis-network-token: ${{ secrets.SATIS_NETWORK_TOKEN }}
 
+      -   uses: actions/setup-node@v7
+          with:
+              node-version: '24'
+
+      -   name: Install frontend dependencies
+          run: yarn install --frozen-lockfile --ignore-scripts
+
       -   name: Setup problem matchers for PHPUnit
           run: echo "::add-matcher::${{ runner.tool_cache }}/phpunit.json"
 
@@ -182,6 +196,13 @@ jobs:
               satis-network-key: ${{ secrets.SATIS_NETWORK_KEY }}
               satis-network-token: ${{ secrets.SATIS_NETWORK_TOKEN }}
 
+      -   uses: actions/setup-node@v7
+          with:
+              node-version: '24'
+
+      -   name: Install frontend dependencies
+          run: yarn install --frozen-lockfile --ignore-scripts
+
       -   name: Setup problem matchers for PHPUnit
           run: echo "::add-matcher::${{ runner.tool_cache }}/phpunit.json"
 

composer.json

@@ -45,6 +45,7 @@
         "symfony/http-foundation": "^7.4",
         "symfony/http-kernel": "^7.4",
         "symfony/options-resolver": "^7.4",
+        "symfony/process": "^7.4",
         "symfony/routing": "^7.4",
         "symfony/security-core": "^7.4",
         "symfony/security-http": "^7.4",

package.json

@@ -8,7 +8,8 @@
         "@ibexa/eslint-config": "https://github.com/ibexa/eslint-config-ibexa.git#~v2.0.0",
         "@ibexa/ts-config": "https://github.com/ibexa/ts-config-ibexa#~v1.1.0",
         "@types/react": "^19.1.2",
-        "@types/react-dom": "^19.1.2"
+        "@types/react-dom": "^19.1.2",
+        "@typescript-eslint/typescript-estree": "^8.62.1"
     },
     "scripts": {
         "test": "yarn prettier-test && yarn ts-test && yarn eslint-test",

src/bundle/Resources/config/services/translation.yaml

@@ -8,6 +8,12 @@ services:
         tags:
             - { name: jms_translation.file_visitor }
 
+    Ibexa\AdminUi\Translation\Extractor\TypeScriptFileVisitor:
+        tags:
+            - { name: jms_translation.file_visitor }
+
+    Ibexa\AdminUi\Translation\Extractor\TypeScriptExtractorClient: ~
+
     Ibexa\AdminUi\Translation\Extractor\SortingTranslationExtractor:
         tags:
             - { name: jms_translation.extractor, alias: ez_location_sorting }

src/lib/Exception/TypeScriptExtractorException.php

@@ -0,0 +1,15 @@
+<?php
+
+/**
+ * @copyright Copyright (C) Ibexa AS. All rights reserved.
+ * @license For full copyright and license information view LICENSE file distributed with this source code.
+ */
+declare(strict_types=1);
+
+namespace Ibexa\AdminUi\Exception;
+
+use RuntimeException;
+
+final class TypeScriptExtractorException extends RuntimeException
+{
+}

src/lib/Translation/Extractor/TypeScriptExtractorClient.php

@@ -0,0 +1,205 @@
+<?php
+
+/**
+ * @copyright Copyright (C) Ibexa AS. All rights reserved.
+ * @license For full copyright and license information view LICENSE file distributed with this source code.
+ */
+declare(strict_types=1);
+
+namespace Ibexa\AdminUi\Translation\Extractor;
+
+use Ibexa\AdminUi\Exception\TypeScriptExtractorException;
+use JsonException;
+use Symfony\Component\Process\InputStream;
+use Symfony\Component\Process\Process;
+
+/**
+ * Talks to the Node script that reads translations from TypeScript files.
+ *
+ * The state below is on purpose and only lives during one extraction run:
+ * we keep one Node process running ({@see self::$serverProcess}) and send it the file paths,
+ * instead of starting Node again for every file. {@see self::$isRuntimeReady} remembers that
+ * we already checked Node works, so we do not check again for each file.
+ */
+final class TypeScriptExtractorClient
+{
+    private const float DEFAULT_RESPONSE_TIMEOUT_SECONDS = 30.0;
+
+    private string $parserScriptPath;
+
+    /** True once we checked Node works. Only kept in memory for this run. */
+    private bool $isRuntimeReady = false;
+
+    private ?Process $serverProcess = null;
+
+    private ?InputStream $serverInput = null;
+
+    private string $responseBuffer = '';
+
+    public function __construct(
+        ?string $parserScriptPath = null,
+        private readonly string $nodeBinary = 'node',
+        private readonly float $responseTimeoutSeconds = self::DEFAULT_RESPONSE_TIMEOUT_SECONDS,
+    ) {
+        $this->parserScriptPath = $parserScriptPath ?? __DIR__ . '/typescript_translation_extractor.mjs';
+    }
+
+    public function __destruct()
+    {
+        $this->discardServerProcess();
+    }
+
+    /**
+     * @return array{messages?: mixed, warnings?: mixed, error?: string}
+     */
+    public function extract(string $filePath): array
+    {
+        $this->assertRuntimeIsReady();
+        $this->ensureServerStarted();
+
+        $this->getServerInput()->write($filePath . "\n");
+
+        return $this->readExtractionResponse();
+    }
+
+    private function assertRuntimeIsReady(): void
+    {
+        if ($this->isRuntimeReady) {
+            return;
+        }
+
+        if (!is_file($this->parserScriptPath)) {
+            throw new TypeScriptExtractorException(sprintf(
+                'TypeScript translation extractor script not found: %s.',
+                $this->parserScriptPath,
+            ));
+        }
+
+        // Runs the Node script once to check it works: this fails early if Node is missing
+        // or the `@typescript-eslint/typescript-estree` package is not installed. Whether each
+        // file parses correctly is checked later in readExtractionResponse().
+        $runtimeCheckProcess = new Process([
+            $this->nodeBinary,
+            $this->parserScriptPath,
+            '--check-runtime',
+        ]);
+        $runtimeCheckProcess->run();
+
+        if (!$runtimeCheckProcess->isSuccessful()) {
+            throw new TypeScriptExtractorException(sprintf(
+                'TypeScript translation extractor runtime is not available. Please ensure `%s` is installed and `@typescript-eslint/typescript-estree` is available for the admin-ui package. %s',
+                $this->nodeBinary,
+                trim($runtimeCheckProcess->getErrorOutput()),
+            ));
+        }
+
+        $this->isRuntimeReady = true;
+    }
+
+    private function ensureServerStarted(): void
+    {
+        if ($this->serverProcess !== null && $this->serverProcess->isRunning()) {
+            return;
+        }
+
+        $processInput = new InputStream();
+
+        $extractorProcess = new Process([
+            $this->nodeBinary,
+            $this->parserScriptPath,
+            '--serve',
+        ]);
+        $extractorProcess->setInput($processInput);
+        $extractorProcess->setTimeout(null);
+        $extractorProcess->start();
+
+        $this->serverInput = $processInput;
+        $this->serverProcess = $extractorProcess;
+        $this->responseBuffer = '';
+    }
+
+    private function getServerInput(): InputStream
+    {
+        if ($this->serverInput === null) {
+            throw new TypeScriptExtractorException('TypeScript translation extractor input stream has not been started.');
+        }
+
+        return $this->serverInput;
+    }
+
+    private function getServerProcess(): Process
+    {
+        if ($this->serverProcess === null) {
+            throw new TypeScriptExtractorException('TypeScript translation extractor process has not been started.');
+        }
+
+        return $this->serverProcess;
+    }
+
+    /**
+     * @return array{messages?: mixed, warnings?: mixed, error?: string}
+     */
+    private function readExtractionResponse(): array
+    {
+        $process = $this->getServerProcess();
+        $responseDeadline = microtime(true) + $this->responseTimeoutSeconds;
+
+        while (!str_contains($this->responseBuffer, "\n")) {
+            if (!$process->isRunning()) {
+                $this->discardServerProcess();
+
+                throw new TypeScriptExtractorException(sprintf(
+                    'TypeScript translation extractor process terminated unexpectedly: %s',
+                    trim($process->getErrorOutput()),
+                ));
+            }
+
+            if (microtime(true) > $responseDeadline) {
+                $this->discardServerProcess();
+
+                throw new TypeScriptExtractorException(
+                    'Timed out waiting for the TypeScript translation extractor process to respond.',
+                );
+            }
+
+            $this->responseBuffer .= $process->getIncrementalOutput();
+
+            if (!str_contains($this->responseBuffer, "\n")) {
+                usleep(2000);
+            }
+        }
+
+        [$responseLine, $rest] = explode("\n", $this->responseBuffer, 2);
+        $this->responseBuffer = $rest;
+
+        return $this->decodeResponse($responseLine);
+    }
+
+    /**
+     * @return array{messages?: mixed, warnings?: mixed, error?: string}
+     */
+    private function decodeResponse(string $responseLine): array
+    {
+        try {
+            $responseData = json_decode($responseLine, true, 512, JSON_THROW_ON_ERROR);
+        } catch (JsonException) {
+            return ['error' => 'Unable to decode extractor output.'];
+        }
+
+        if (!is_array($responseData)) {
+            return ['error' => 'Extractor output must be a JSON object.'];
+        }
+
+        return $responseData;
+    }
+
+    private function discardServerProcess(): void
+    {
+        $this->serverInput?->close();
+        $this->serverProcess?->stop(3);
+
+        $this->serverProcess = null;
+        $this->serverInput = null;
+        $this->responseBuffer = '';
+    }
+}