feat: make engine_id optional and use single /process/localize endpoint

Author: AndreyHirsa

README.md

@@ -8,7 +8,6 @@ A powerful async-first localization engine that supports various content types i
 - 🔀 **Concurrent processing** for dramatically faster bulk translations
 - 🎯 **Multiple content types**: text, objects, chat messages, and more
 - 🌐 **Auto-detection** of source languages
-- ⚡ **Fast mode** for quick translations
 - 🔧 **Flexible configuration** with progress callbacks
 - 📦 **Context manager** support for proper resource management
 
@@ -56,7 +55,7 @@ from lingodotdev import LingoDotDevEngine
 async def main():
     config = {
         "api_key": "your-api-key",
-        "engine_id": "your-engine-id",
+        "engine_id": "your-engine-id",  # Optional
     }
 
     async with LingoDotDevEngine(config) as engine:
@@ -164,7 +163,7 @@ async def detection_example():
 ```python
 config = {
     "api_key": "your-api-key",              # Required: Your API key
-    "engine_id": "your-engine-id",          # Required: Your engine ID
+    "engine_id": "your-engine-id",          # Optional: Your engine ID
     "api_url": "https://api.lingo.dev",     # Optional: API endpoint
     "batch_size": 25,                       # Optional: Items per batch (1-250)
     "ideal_batch_item_size": 250            # Optional: Target words per batch (1-2500)
@@ -176,7 +175,6 @@ config = {
 ### Translation Parameters
 - **source_locale**: Source language code (auto-detected if None)
 - **target_locale**: Target language code (required)
-- **fast**: Enable fast mode for quicker translations
 - **reference**: Reference translations for context
 - **concurrent**: Process chunks concurrently (faster, but no progress callbacks)
 

src/lingodotdev/engine.py

@@ -17,17 +17,20 @@ class EngineConfig(BaseModel):
     """Configuration for the LingoDotDevEngine"""
 
     api_key: str
-    engine_id: str
+    engine_id: Optional[str] = None
     api_url: str = "https://api.lingo.dev"
     batch_size: int = Field(default=25, ge=1, le=250)
     ideal_batch_item_size: int = Field(default=250, ge=1, le=2500)
 
-    @validator("engine_id")
+    @validator("engine_id", pre=True, always=True)
     @classmethod
-    def validate_engine_id(cls, v: str) -> str:
-        if not v.strip():
-            raise ValueError("engine_id is required and cannot be empty")
-        return v.strip()
+    def validate_engine_id(cls, v: Optional[str]) -> Optional[str]:
+        if v is None:
+            return None
+        stripped = v.strip()
+        if not stripped:
+            return None
+        return stripped
 
     @validator("api_url")
     @classmethod
@@ -204,14 +207,16 @@ async def _localize_chunk(
         await self._ensure_client()
         assert self._client is not None  # Type guard for mypy
 
-        url = f"{self.config.api_url}/process/{self.config.engine_id}/localize"
+        url = f"{self.config.api_url}/process/localize"
         request_data: Dict[str, Any] = {
             "params": {"fast": fast},
             "sourceLocale": source_locale,
             "targetLocale": target_locale,
             "data": payload["data"],
             "sessionId": self._session_id,
         }
+        if self.config.engine_id:
+            request_data["engineId"] = self.config.engine_id
         if payload.get("reference"):
             request_data["reference"] = payload["reference"]
 
@@ -543,9 +548,9 @@ async def quick_translate(
         cls,
         content: Any,
         api_key: str,
-        engine_id: str,
         target_locale: str,
         source_locale: Optional[str] = None,
+        engine_id: Optional[str] = None,
         api_url: str = "https://api.lingo.dev",
         fast: bool = True,
     ) -> Any:
@@ -556,9 +561,9 @@ async def quick_translate(
         Args:
             content: Text string or dict to translate
             api_key: Your Lingo.dev API key
-            engine_id: Engine ID for the API
             target_locale: Target language code (e.g., 'es', 'fr')
             source_locale: Source language code (optional, auto-detected if None)
+            engine_id: Optional engine ID for the API
             api_url: API endpoint URL
             fast: Enable fast mode for quicker translations
 
@@ -582,11 +587,12 @@ async def quick_translate(
                 "es"
             )
         """
-        config = {
+        config: Dict[str, Any] = {
             "api_key": api_key,
-            "engine_id": engine_id,
             "api_url": api_url,
         }
+        if engine_id:
+            config["engine_id"] = engine_id
 
         async with cls(config) as engine:
             params = {
@@ -607,9 +613,9 @@ async def quick_batch_translate(
         cls,
         content: Any,
         api_key: str,
-        engine_id: str,
         target_locales: List[str],
         source_locale: Optional[str] = None,
+        engine_id: Optional[str] = None,
         api_url: str = "https://api.lingo.dev",
         fast: bool = True,
     ) -> List[Any]:
@@ -620,9 +626,9 @@ async def quick_batch_translate(
         Args:
             content: Text string or dict to translate
             api_key: Your Lingo.dev API key
-            engine_id: Engine ID for the API
             target_locales: List of target language codes (e.g., ['es', 'fr', 'de'])
             source_locale: Source language code (optional, auto-detected if None)
+            engine_id: Optional engine ID for the API
             api_url: API endpoint URL
             fast: Enable fast mode for quicker translations
 
@@ -633,16 +639,16 @@ async def quick_batch_translate(
             results = await LingoDotDevEngine.quick_batch_translate(
                 "Hello world",
                 "your-api-key",
-                "your-engine-id",
                 ["es", "fr", "de"]
             )
             # Results: ["Hola mundo", "Bonjour le monde", "Hallo Welt"]
         """
-        config = {
+        config: Dict[str, Any] = {
             "api_key": api_key,
-            "engine_id": engine_id,
             "api_url": api_url,
         }
+        if engine_id:
+            config["engine_id"] = engine_id
 
         async with cls(config) as engine:
             if isinstance(content, str):

tests/test_engine.py

@@ -37,20 +37,20 @@ def test_default_values(self):
         assert config.batch_size == 25
         assert config.ideal_batch_item_size == 250
 
-    def test_engine_id_required(self):
-        """Test that engine_id is required"""
-        with pytest.raises(Exception, match="engine_id"):
-            EngineConfig(api_key="test_key")
+    def test_engine_id_optional(self):
+        """Test that engine_id is optional and defaults to None"""
+        config = EngineConfig(api_key="test_key")
+        assert config.engine_id is None
 
-    def test_engine_id_empty_string_rejected(self):
-        """Test that empty engine_id is rejected"""
-        with pytest.raises(ValueError, match="engine_id is required"):
-            EngineConfig(api_key="test_key", engine_id="")
+    def test_engine_id_empty_string_becomes_none(self):
+        """Test that empty engine_id becomes None"""
+        config = EngineConfig(api_key="test_key", engine_id="")
+        assert config.engine_id is None
 
-    def test_engine_id_whitespace_rejected(self):
-        """Test that whitespace-only engine_id is rejected"""
-        with pytest.raises(ValueError, match="engine_id is required"):
-            EngineConfig(api_key="test_key", engine_id="  ")
+    def test_engine_id_whitespace_becomes_none(self):
+        """Test that whitespace-only engine_id becomes None"""
+        config = EngineConfig(api_key="test_key", engine_id="  ")
+        assert config.engine_id is None
 
     def test_engine_id_stripped(self):
         """Test that engine_id is stripped of whitespace"""
@@ -702,14 +702,15 @@ async def test_localize_chunk_url_and_body(self, mock_post):
 
         call_args = mock_post.call_args
         url = call_args[0][0]
-        assert url == "https://api.lingo.dev/process/my-engine-id/localize"
+        assert url == "https://api.lingo.dev/process/localize"
 
         body = call_args[1]["json"]
         assert body["sourceLocale"] == "en"
         assert body["targetLocale"] == "es"
         assert body["params"] == {"fast": True}
         assert body["data"] == {"key": "value"}
         assert body["sessionId"] == self.engine._session_id
+        assert body["engineId"] == "my-engine-id"
         assert body["reference"] == {"es": {"key": "ref"}}
 
     @patch("lingodotdev.engine.httpx.AsyncClient.post")
@@ -756,9 +757,34 @@ async def test_full_localization_workflow(self, mock_post):
 
         call_args = mock_post.call_args
         url = call_args[0][0]
-        assert url == "https://api.lingo.dev/process/my-engine-id/localize"
+        assert url == "https://api.lingo.dev/process/localize"
 
         body = call_args[1]["json"]
         assert body["sourceLocale"] == "en"
         assert body["targetLocale"] == "es"
+        assert body["engineId"] == "my-engine-id"
         assert "sessionId" in body
+
+    @patch("lingodotdev.engine.httpx.AsyncClient.post")
+    async def test_localize_without_engine_id(self, mock_post):
+        """Test localization without engine_id omits engineId from body"""
+        engine = LingoDotDevEngine({"api_key": "test_api_key"})
+
+        mock_response = Mock()
+        mock_response.is_success = True
+        mock_response.json.return_value = {"data": {"greeting": "hola"}}
+        mock_post.return_value = mock_response
+
+        result = await engine.localize_object(
+            {"greeting": "hello"},
+            {"source_locale": "en", "target_locale": "es", "fast": True},
+        )
+
+        assert result == {"greeting": "hola"}
+
+        call_args = mock_post.call_args
+        url = call_args[0][0]
+        assert url == "https://api.lingo.dev/process/localize"
+
+        body = call_args[1]["json"]
+        assert "engineId" not in body

tests/test_integration.py

@@ -34,19 +34,18 @@ class TestRealAPIIntegration:
     def setup_method(self):
         """Set up test fixtures"""
         api_key = os.getenv("LINGODOTDEV_API_KEY")
-        engine_id = os.getenv("LINGODOTDEV_ENGINE_ID")
         if not api_key:
             pytest.skip("No API key provided")
-        if not engine_id:
-            pytest.skip("No engine ID provided")
 
-        self.engine = LingoDotDevEngine(
-            {
-                "api_key": api_key,
-                "engine_id": engine_id,
-                "api_url": os.getenv("LINGODOTDEV_API_URL", "https://api.lingo.dev"),
-            }
-        )
+        config = {
+            "api_key": api_key,
+            "api_url": os.getenv("LINGODOTDEV_API_URL", "https://api.lingo.dev"),
+        }
+        engine_id = os.getenv("LINGODOTDEV_ENGINE_ID")
+        if engine_id:
+            config["engine_id"] = engine_id
+
+        self.engine = LingoDotDevEngine(config)
 
     async def test_localize_text_real_api(self):
         """Test text localization against real API"""