Translate PDF: Verify language code

- Add `AfterValidator` on language string
- Use new dependency `langcodes` to validate language codes

Assisted-by: Codex

Author: datalogics-cgreen

pyproject.toml

@@ -10,6 +10,7 @@ requires-python = ">=3.10"
 dependencies = [
     "exceptiongroup>=1.3.0",
     "httpx>=0.28.1",
+    "langcodes>=3.4.0",
     "pydantic>=2.12.0",
 ]
 

src/pdfrest/models/_internal.py

@@ -6,6 +6,7 @@
 from pathlib import PurePath
 from typing import Annotated, Any, Generic, Literal, TypeVar
 
+from langcodes import tag_is_valid
 from pydantic import (
     AfterValidator,
     AliasChoices,
@@ -175,6 +176,45 @@ def _int_to_string(value: Any) -> Any:
     return value
 
 
+_OUTPUT_LANGUAGE_ERROR = (
+    "The provided 'output_language' language tag is invalid. Format 'output_language' as "
+    "a valid 2-3 character ISO 639 language code (e.g., 'en', 'es', 'fra'), optionally "
+    "with a script, alphabetic region, or numeric region (e.g., 'zh-Hant', 'eng-US', "
+    "'es-419'). See documentation for recommended formats."
+)
+
+
+def _validate_output_language(value: str) -> str:
+    if not value:
+        raise ValueError(_OUTPUT_LANGUAGE_ERROR)
+
+    trimmed = value.strip()
+    if not trimmed:
+        raise ValueError(_OUTPUT_LANGUAGE_ERROR)
+
+    segments = trimmed.split("-")
+    if len(segments) > 2:
+        raise ValueError(_OUTPUT_LANGUAGE_ERROR)
+
+    language = segments[0]
+    if not re.fullmatch(r"[A-Za-z]{2,3}", language):
+        raise ValueError(_OUTPUT_LANGUAGE_ERROR)
+
+    if len(segments) == 2:
+        subtag = segments[1]
+        if not (
+            re.fullmatch(r"[A-Za-z]{4}", subtag)
+            or re.fullmatch(r"[A-Za-z]{2}", subtag)
+            or re.fullmatch(r"[0-9]{3}", subtag)
+        ):
+            raise ValueError(_OUTPUT_LANGUAGE_ERROR)
+
+    if not tag_is_valid(trimmed):
+        raise ValueError(_OUTPUT_LANGUAGE_ERROR)
+
+    return trimmed
+
+
 class UploadURLs(BaseModel):
     url: Annotated[
         list[HttpUrl] | HttpUrl,
@@ -464,7 +504,8 @@ class TranslatePdfTextPayload(BaseModel):
     ]
     output_language: Annotated[
         str,
-        Field(serialization_alias="output_language", min_length=1),
+        Field(serialization_alias="output_language"),
+        AfterValidator(_validate_output_language),
     ]
     pages: Annotated[
         list[AscendingPageRange] | None,

tests/test_translate_pdf_text.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import json
+import re
 
 import httpx
 import pytest
@@ -17,6 +18,13 @@
 
 from .graphics_test_helpers import ASYNC_API_KEY, VALID_API_KEY, make_pdf_file
 
+OUTPUT_LANGUAGE_ERROR = (
+    "The provided 'output_language' language tag is invalid. Format 'output_language' "
+    "as a valid 2-3 character ISO 639 language code (e.g., 'en', 'es', 'fra'), "
+    "optionally with a script, alphabetic region, or numeric region (e.g., 'zh-Hant', "
+    "'eng-US', 'es-419'). See documentation for recommended formats."
+)
+
 
 def _make_markdown_file(file_id: str) -> PdfRestFile:
     return PdfRestFile.model_validate(
@@ -54,6 +62,51 @@ def test_translate_payload_rejects_invalid_mime() -> None:
         )
 
 
+@pytest.mark.parametrize(
+    "output_language",
+    [
+        pytest.param("en", id="language-2-letter"),
+        pytest.param("fra", id="language-3-letter"),
+        pytest.param("zh-Hant", id="script"),
+        pytest.param("eng-US", id="alpha-region"),
+        pytest.param("es-419", id="numeric-region"),
+    ],
+)
+def test_translate_payload_accepts_valid_output_language(
+    output_language: str,
+) -> None:
+    file_repr = make_pdf_file(PdfRestFileID.generate(1))
+    payload = TranslatePdfTextPayload.model_validate(
+        {"files": [file_repr], "output_language": output_language}
+    )
+
+    assert payload.output_language == output_language
+
+
+@pytest.mark.parametrize(
+    "output_language",
+    [
+        pytest.param("", id="empty"),
+        pytest.param("e", id="too-short"),
+        pytest.param("english", id="not-a-code"),
+        pytest.param("eng-USA", id="long-subtag"),
+        pytest.param("en-1234", id="long-numeric-region"),
+        pytest.param("en-US-extra", id="too-many-subtags"),
+    ],
+)
+def test_translate_payload_rejects_invalid_output_language(
+    output_language: str,
+) -> None:
+    file_repr = make_pdf_file(PdfRestFileID.generate(1))
+    with pytest.raises(
+        ValidationError,
+        match=re.escape(OUTPUT_LANGUAGE_ERROR),
+    ):
+        TranslatePdfTextPayload.model_validate(
+            {"files": [file_repr], "output_language": output_language}
+        )
+
+
 def test_translate_payload_requires_target_language() -> None:
     file_repr = make_pdf_file(PdfRestFileID.generate(1))
     with pytest.raises(ValidationError):