feat: make engineId optional, use single /process/localize endpoint

AndreyHirsa · AndreyHirsa · commit 24db355ec23e · 2026-03-05T23:36:20.000+03:00
diff --git a/README.md b/README.md
@@ -12,7 +12,7 @@ composer require lingodotdev/sdk
 
 ## Basic Usage
 
-After installing the package, bootstrap the engine with your API key and Engine ID:
+After installing the package, bootstrap the engine with your API key:
 
 ```php
 require 'vendor/autoload.php';
@@ -21,7 +21,7 @@ use LingoDotDev\Sdk\LingoDotDevEngine;
 
 $engine = new LingoDotDevEngine([
     'apiKey' => 'your-api-key',       // replace with your actual key
-    'engineId' => 'your-engine-id',   // replace with your actual engine id
+    'engineId' => 'your-engine-id',   // optional — override the default engine
 ]);
 ```
 
@@ -30,7 +30,7 @@ $engine = new LingoDotDevEngine([
 | Option | Type | Required | Default | Description |
 |---|---|---|---|---|
 | `apiKey` | string | Yes | — | Your Lingo.dev API key |
-| `engineId` | string | Yes | — | Your Lingo.dev Engine ID |
+| `engineId` | string | No | — | Your Lingo.dev Engine ID |
 | `apiUrl` | string | No | `https://api.lingo.dev` | API base URL |
 | `batchSize` | int | No | `25` | Max items per chunk (1–250) |
 | `idealBatchItemSize` | int | No | `250` | Max words per chunk (1–2500) |
@@ -84,10 +84,10 @@ Follow these steps to create a new PHP project that uses the Lingo.dev SDK:
 
 use LingoDotDev\Sdk\LingoDotDevEngine;
 
-// Initialize the SDK with your API key and Engine ID
+// Initialize the SDK with your API key
 $engine = new LingoDotDevEngine([
     'apiKey' => 'your-api-key',
-    'engineId' => 'your-engine-id',
+    'engineId' => 'your-engine-id',   // optional
 ]);
 ```
 
@@ -104,17 +104,6 @@ $localizedText = $engine->localizeText('Hello, world!', [
 // Output: "¡Hola, mundo!"
 ```
 
-You can enable fast mode for quicker (but potentially lower quality) translations:
-
-```php
-// Localize with fast mode enabled
-$localizedText = $engine->localizeText('Hello, world!', [
-    'sourceLocale' => 'en',
-    'targetLocale' => 'es',
-    'fast' => true,
-]);
-```
-
 ### Object Localization
 
 Translate an array of strings while preserving the structure:
@@ -228,13 +217,13 @@ $engine->localizeText('Hello, world!', [
 
 ## Demo App
 
-If you prefer to start with a minimal example instead of the detailed scenarios above, create **index.php** in an empty folder, copy the following snippet, install dependencies with `composer require lingodotdev/sdk`, set `LINGODOTDEV_API_KEY` and `LINGODOTDEV_ENGINE_ID`, and run `php index.php`.
+If you prefer to start with a minimal example instead of the detailed scenarios above, create **index.php** in an empty folder, copy the following snippet, install dependencies with `composer require lingodotdev/sdk`, set `LINGODOTDEV_API_KEY` (and optionally `LINGODOTDEV_ENGINE_ID`), and run `php index.php`.
 
 Want to see everything in action?
 
 1. Clone this repository or copy the `index.php` from the **demo** below into an empty directory.
 2. Run `composer install` to pull in the SDK.
-3. Populate the `LINGODOTDEV_API_KEY` and `LINGODOTDEV_ENGINE_ID` environment variables.
+3. Populate the `LINGODOTDEV_API_KEY` environment variable (and optionally `LINGODOTDEV_ENGINE_ID`).
 4. Execute the script with `php index.php` and observe the output.
 
 `index.php` demo:
@@ -246,10 +235,13 @@ require 'vendor/autoload.php';
 
 use LingoDotDev\Sdk\LingoDotDevEngine;
 
-$engine = new LingoDotDevEngine([
+$config = [
     'apiKey' => getenv('LINGODOTDEV_API_KEY'),
-    'engineId' => getenv('LINGODOTDEV_ENGINE_ID'),
-]);
+];
+if (getenv('LINGODOTDEV_ENGINE_ID')) {
+    $config['engineId'] = getenv('LINGODOTDEV_ENGINE_ID');
+}
+$engine = new LingoDotDevEngine($config);
 
 // 1. Text
 $helloEs = $engine->localizeText('Hello world!', [
diff --git a/src/LingoDotDevEngine.php b/src/LingoDotDevEngine.php
@@ -67,10 +67,6 @@ public function __construct(array $config = [])
             throw new \InvalidArgumentException('API key is required');
         }
 
-        if (empty($this->config['engineId'])) {
-            throw new \InvalidArgumentException('Engine ID is required');
-        }
-
         if (!filter_var($this->config['apiUrl'], FILTER_VALIDATE_URL)) {
             throw new \InvalidArgumentException('API URL must be a valid URL');
         }
@@ -160,7 +156,7 @@ protected function localizeRaw(array $payload, array $params, ?callable $progres
     private function _localizeChunk(?string $sourceLocale, string $targetLocale, array $payload, bool $fast): array
     {
         try {
-            $url = '/process/' . $this->config['engineId'] . '/localize';
+            $url = '/process/localize';
             $requestBody = [
                 'params' => ['fast' => $fast],
                 'sourceLocale' => $sourceLocale,
@@ -169,6 +165,10 @@ private function _localizeChunk(?string $sourceLocale, string $targetLocale, arr
                 'sessionId' => $this->_sessionId,
             ];
 
+            if (!empty($this->config['engineId'])) {
+                $requestBody['engineId'] = $this->config['engineId'];
+            }
+
             if (isset($payload['reference']) && $payload['reference'] !== null) {
                 if (!is_array($payload['reference'])) {
                     throw new \InvalidArgumentException('Reference must be an array');
diff --git a/test-all-methods.php b/test-all-methods.php
@@ -5,7 +5,7 @@
  * This script tests all available methods in the PHP SDK with real API calls
  * to ensure they work correctly.
  *
- * Usage: php test-all-methods.php <api_key> <engine_id>
+ * Usage: php test-all-methods.php <api_key> [engine_id] [api_url]
  */
 
 require "vendor/autoload.php";
@@ -15,16 +15,23 @@
 
 $apiKey = $argv[1] ?? null;
 $engineId = $argv[2] ?? null;
+$apiUrl = $argv[3] ?? null;
 
-if (!$apiKey || !$engineId) {
-    echo "Usage: php test-all-methods.php <api_key> <engine_id>\n";
+if (!$apiKey) {
+    echo "Usage: php test-all-methods.php <api_key> [engine_id] [api_url]\n";
     exit(1);
 }
 
-$engine = new LingoDotDevEngine([
+$config = [
     "apiKey" => $apiKey,
-    "engineId" => $engineId,
-]);
+];
+if ($engineId) {
+    $config["engineId"] = $engineId;
+}
+if ($apiUrl) {
+    $config["apiUrl"] = $apiUrl;
+}
+$engine = new LingoDotDevEngine($config);
 
 $passed = 0;
 $failed = 0;
@@ -60,16 +67,7 @@ function runTest($name, $callback) {
     ]);
 });
 
-// 2. localizeText with fast mode
-runTest("localizeText (fast mode)", function() use ($engine) {
-    return $engine->localizeText("The quick brown fox jumps over the lazy dog.", [
-        "sourceLocale" => "en",
-        "targetLocale" => "fr",
-        "fast" => true,
-    ]);
-});
-
-// 3. localizeObject
+// 2. localizeObject
 runTest("localizeObject", function() use ($engine) {
     return $engine->localizeObject([
         "greeting" => "Hello",
@@ -84,7 +82,7 @@ function runTest($name, $callback) {
     ]);
 });
 
-// 4. localizeChat
+// 3. localizeChat
 runTest("localizeChat", function() use ($engine) {
     return $engine->localizeChat([
         ["name" => "Alice", "text" => "Hello, how are you?"],
@@ -96,20 +94,20 @@ function runTest($name, $callback) {
     ]);
 });
 
-// 5. batchLocalizeText
+// 4. batchLocalizeText
 runTest("batchLocalizeText", function() use ($engine) {
     return $engine->batchLocalizeText("Hello, world!", [
         "sourceLocale" => "en",
         "targetLocales" => ["es", "fr", "de"],
     ]);
 });
 
-// 6. recognizeLocale
+// 5. recognizeLocale
 runTest("recognizeLocale", function() use ($engine) {
     return $engine->recognizeLocale("Bonjour le monde");
 });
 
-// 7. localizeObject with reference
+// 6. localizeObject with reference
 runTest("localizeObject with reference", function() use ($engine) {
     return $engine->localizeObject([
         "greeting" => "Hello",
@@ -126,7 +124,7 @@ function runTest($name, $callback) {
     ]);
 });
 
-// 8. Progress callback
+// 7. Progress callback
 runTest("Progress Callback", function() use ($engine) {
     $progressCalled = false;
     $progressValue = 0;
diff --git a/tests/LingoDotDevEngineTest.php b/tests/LingoDotDevEngineTest.php
@@ -114,15 +114,16 @@ public function testConstructorWithValidConfig()
     }
 
     /**
-     * Tests constructor requires engineId
+     * Tests constructor works without engineId
      *
      * @return void
      */
-    public function testConstructorRequiresEngineId()
+    public function testConstructorWithoutEngineId()
     {
-        $this->expectException(\InvalidArgumentException::class);
-        $this->expectExceptionMessage('Engine ID is required');
-        new LingoDotDevEngine(['apiKey' => 'test-api-key']);
+        $engine = new LingoDotDevEngine([
+            'apiKey' => 'test-api-key',
+        ]);
+        $this->assertInstanceOf(LingoDotDevEngine::class, $engine);
     }
 
     /**
@@ -497,7 +498,8 @@ public function testLocalizeChunkUrlAndBody()
         $request = $history[0]['request'];
 
         // Check URL
-        $this->assertStringContainsString('/process/my-engine/localize', $request->getUri()->getPath());
+        $this->assertStringContainsString('/process/localize', $request->getUri()->getPath());
+        $this->assertStringNotContainsString('/process/my-engine/localize', $request->getUri()->getPath());
 
         // Check body format
         $body = json_decode($request->getBody()->getContents(), true);
@@ -507,12 +509,62 @@ public function testLocalizeChunkUrlAndBody()
         $this->assertEquals(['text' => 'Hello'], $body['data']);
         $this->assertArrayHasKey('sessionId', $body);
         $this->assertNotEmpty($body['sessionId']);
+        $this->assertEquals('my-engine', $body['engineId']);
 
         // vNext should NOT have workflowId or locale object
         $this->assertArrayNotHasKey('workflowId', $body['params']);
         $this->assertArrayNotHasKey('locale', $body);
     }
 
+    /**
+     * Tests localize chunk URL and body format without engineId
+     *
+     * @return void
+     */
+    public function testLocalizeChunkUrlAndBodyWithoutEngineId()
+    {
+        $history = [];
+        $mock = new MockHandler([
+            new Response(200, [], json_encode(['data' => ['text' => 'Hola']]))
+        ]);
+        $handlerStack = HandlerStack::create($mock);
+        $handlerStack->push(\GuzzleHttp\Middleware::history($history));
+
+        $engine = new LingoDotDevEngine([
+            'apiKey' => 'test-api-key',
+        ]);
+
+        $client = new Client([
+            'handler' => $handlerStack,
+            'headers' => [
+                'Content-Type' => 'application/json; charset=utf-8',
+                'X-API-Key' => 'test-api-key'
+            ]
+        ]);
+
+        $reflection = new ReflectionClass($engine);
+        $property = $reflection->getProperty('_httpClient');
+        $property->setAccessible(true);
+        $property->setValue($engine, $client);
+
+        $engine->localizeText('Hello', [
+            'sourceLocale' => 'en',
+            'targetLocale' => 'es',
+        ]);
+
+        $this->assertCount(1, $history);
+        $request = $history[0]['request'];
+
+        // Check URL is /process/localize
+        $this->assertStringContainsString('/process/localize', $request->getUri()->getPath());
+
+        // Check body omits engineId
+        $body = json_decode($request->getBody()->getContents(), true);
+        $this->assertArrayNotHasKey('engineId', $body);
+        $this->assertEquals('en', $body['sourceLocale']);
+        $this->assertEquals('es', $body['targetLocale']);
+    }
+
     /**
      * Tests that sessionId is consistent across multiple requests
      *
