DEV Community: Louis Desclous

Localizing product images for every marketplace with a Python script

Louis Desclous — Tue, 06 Oct 2026 08:19:43 +0000

Translating a product listing is mostly solved: titles, bullets and descriptions go through any translation API. The images are where localization usually stops. Infographics with dimensions and feature callouts, "what's in the box" visuals, size charts and supplier photos with Chinese labels all keep their original text, and on a marketplace the images are what shoppers read first.

This tutorial builds a script that takes a folder of product images and a list of target languages, sends each image to an image translation API, and saves the translated versions next to the originals, ready to review.

It uses TranslateMyImage, which I build. The API detects the text in the image, translates it, and returns a new image with the translation placed where the original text was.

What you need

API access, which is included from the Pro plan. Each completed translation consumes one credit.
An API key from the API Keys page of the dashboard. It is shown once, so store it right away.
Python 3.9+ and requests.

pip install requests
export TMI_API_KEY="your-key"

The endpoint takes multipart/form-data (the full reference is at translatemyimage.com/api-docs):

Field	Required	Values
`file`	yes	JPG, PNG or WEBP, up to 10 MB and 25 megapixels
`target_lang`	yes	`en`, `fr`, `es`, `de`, `it`, `pt`, `ja`, `ko`, `zh`
`source_lang`	no	a language code, or `auto` (the default)
`quality`	no	`basic` (default) or `ultra`
`business_type`	no	`default`, `marketing`, `edition`, `technical documentation`

One image

import os
from pathlib import Path

import requests

API_URL = "https://translatemyimage.com/api/translate"
HEADERS = {"X-API-Key": os.environ["TMI_API_KEY"]}


class TranslationError(Exception):
    def __init__(self, status: int, payload: dict):
        super().__init__(f"{status}: {payload.get('error')} ({payload.get('code')})")
        self.status = status
        self.code = payload.get("code")


def translate_image(path: Path, target_lang: str) -> dict:
    with path.open("rb") as f:
        r = requests.post(
            API_URL,
            headers=HEADERS,
            files={"file": (path.name, f)},
            data={
                "target_lang": target_lang,
                "source_lang": "auto",
                "business_type": "marketing",
            },
            timeout=300,
        )
    payload = r.json()
    if not r.ok or not payload.get("success"):
        raise TranslationError(r.status_code, payload)
    return payload["translation"]

A successful response looks like this:

{
  "success": true,
  "translation": {
    "id": "clxb1234567890",
    "originalUrl": "https://…/original.jpg",
    "translatedUrl": "https://…/translated.jpg",
    "sourceLang": "zh",
    "targetLang": "en",
    "status": "completed"
  }
}

business_type: "marketing" suits ad creatives and listing images. Use "technical documentation" for manuals, spec sheets and diagrams.

A folder, several languages

import time

LANGS = ["de", "fr", "es", "it"]  # e.g. the EU Amazon marketplaces


def translate_with_retry(path: Path, lang: str, attempts: int = 4) -> dict:
    for attempt in range(attempts):
        try:
            return translate_image(path, lang)
        except TranslationError as error:
            transient = error.status == 429 or error.code == "service_unavailable"
            if not transient or attempt == attempts - 1:
                raise
            time.sleep(2 ** attempt * 5)


def localize_folder(src: str = "images", out: str = "localized") -> None:
    for path in sorted(Path(src).glob("*")):
        if path.suffix.lower() not in {".jpg", ".jpeg", ".png", ".webp"}:
            continue
        for lang in LANGS:
            target = Path(out) / lang / path.name
            if target.exists():
                continue  # already done: re-running the script costs nothing
            result = translate_with_retry(path, lang)
            target.parent.mkdir(parents=True, exist_ok=True)
            target.write_bytes(requests.get(result["translatedUrl"], timeout=60).content)
            print(f"{path.name} → {lang}: {target}")


if __name__ == "__main__":
    localize_folder()

You end up with localized/de/…, localized/fr/… and so on, mirroring the source folder. Ten images into four languages is 40 credits.

Errors worth handling

Error responses are JSON with success: false and a message in error. Once the request is authenticated they also carry a stable code, so you can branch without parsing English:

plan_required: the key's account does not include API access (Pro and above) or the option you asked for.
insufficient_credits: top up or wait for the monthly reset. Stop the loop instead of retrying.
invalid_image / invalid_request: wrong format, over 10 MB or 25 megapixels, or a bad language code.
content_blocked: the image was refused by the safety check. Skip it.
429 or service_unavailable: transient, retry with a backoff as above.

Review before you publish

Treat the output as a strong first draft. Check numbers, units and brand names on every image, and have a native speaker glance at anything legal or safety related. The script's folder layout makes that review easy: open localized/de and images side by side.

If you only need a handful of images, the same thing works without code at translatemyimage.com: drop an image, pick a language, download the result.

What kind of images do you need localized? Product photos, comics, UI screenshots? I would like to hear which cases break.

From a folder of CVs to a ranked shortlist in about 80 lines of Python

Louis Desclous — Tue, 06 Oct 2026 08:18:58 +0000

Screening is the part of hiring that scales worst. Ten CVs for one role is an afternoon; a hundred is a week. This tutorial builds a small Python script that takes a folder of resumes and a job description, and prints a ranked shortlist with a reason for each position.

It uses the HireLayer recruiting APIs, which I build. Everything below runs on the free plan (50 credits a month, no card), and each successful call costs one credit.

What we are building

cvs/                     job.txt
 ├─ alice.pdf               │
 ├─ bob.docx                ▼
 └─ chloe.png        extract criteria ──┐
      │                                  │
      ▼                                  ▼
 parse each CV ──► resume text ──► match each candidate  ──► per-criterion evidence
                          │
                          └──────► rank all candidates  ──► ordered shortlist

Four endpoints, all synchronous JSON (the reference is at hirelayer.co/api-docs, with an OpenAPI spec if you prefer generating a client):

Step	Endpoint	Returns
Parse a CV	`POST /api/v3/parser`	Structured profile + full text in `info_resume.text`
Job criteria	`POST /api/v1/jobs/extract-criteria`	`matching_criteria[]` with a weight from 1 to 3
Match	`POST /api/v1/matching/job-candidate`	`score` from 0 to 1 + one verdict per criterion
Rank	`POST /api/v1/matching/job-candidates/rank`	Up to 10 candidates ordered by `rank`

Setup

pip install requests
export HIRELAYER_API_KEY="your-key"   # from the dashboard after signing up

1. Parse the resumes

The parser accepts PDF, DOC, DOCX, ODT, PPT, PPTX, ODP, XLS, RTF, TXT, JPG, PNG and BMP files under 4.5 MB, and detects the type from the content. do_not_store_data=true tells the API not to keep the file after parsing, which is what you want for a local script.

import os
from pathlib import Path

import requests

API = "https://hirelayer.co"
HEADERS = {"X-API-Key": os.environ["HIRELAYER_API_KEY"]}


def parse_resume(path: Path) -> dict:
    with path.open("rb") as f:
        r = requests.post(
            f"{API}/api/v3/parser",
            headers=HEADERS,
            files={"file": (path.name, f)},
            data={"do_not_store_data": "true"},
            timeout=120,
        )
    r.raise_for_status()
    return r.json()

The response has the candidate profile (info_candidate), work_experiences, educations, languages, skills and the full text, including OCR for scanned or image CVs, in info_resume.text. That text is what the matching endpoints take.

2. Turn the job description into criteria

def extract_criteria(job_text: str) -> list[dict]:
    r = requests.post(
        f"{API}/api/v1/jobs/extract-criteria",
        headers=HEADERS,
        json={"job_text": job_text},
        timeout=60,
    )
    r.raise_for_status()
    return r.json()["matching_criteria"]

A sentence like "React required. Fluent English required. Paris-based." comes back as three criteria, sorted by weight, each with id, label, weight (3 essential, 2 important, 1 nice to have), is_mandatory and a rationale. You can edit the list before matching: drop a criterion, change a weight, add your own with any id.

3. Score one candidate, criterion by criterion

def match(job_text: str, resume_text: str, criteria: list[dict]) -> dict:
    r = requests.post(
        f"{API}/api/v1/matching/job-candidate",
        headers=HEADERS,
        json={
            "job_text": job_text,
            "candidate_text": resume_text,
            "matching_criteria": criteria,
        },
        timeout=60,
    )
    r.raise_for_status()
    return r.json()

Each entry of evaluated_criteria gets a match_status (ideal, potential or not_mentioned) and a match_explanation quoting the evidence, and score is the weighted average. This is the call to use when a recruiter needs to see why, not just a number. Note that the summary and explanations are currently written in French.

4. Rank the whole batch

Ranking compares candidates against each other for the same job, up to 10 per call:

def rank(job_text: str, resumes: dict[str, str]) -> list[dict]:
    r = requests.post(
        f"{API}/api/v1/matching/job-candidates/rank",
        headers=HEADERS,
        json={
            "job_text": job_text,
            "candidates": [
                {"id": cid, "candidate_text": text} for cid, text in resumes.items()
            ],
        },
        timeout=120,
    )
    r.raise_for_status()
    return r.json()["rankings"]

Putting it together

def main(cv_dir: str = "cvs", job_file: str = "job.txt") -> None:
    job_text = Path(job_file).read_text()
    resumes = {
        p.stem: parse_resume(p)["info_resume"]["text"]
        for p in sorted(Path(cv_dir).iterdir())
        if p.is_file()
    }

    criteria = extract_criteria(job_text)
    print("Criteria:")
    for c in criteria:
        print(f"  [{c['weight']}] {c['label']}")

    rankings = rank(job_text, resumes)
    print("\nShortlist:")
    for row in rankings:
        print(f"  #{row['rank']} {row['candidate_id']}  ({row['score']:.2f})  {row['rationale']}")

    best = rankings[0]["candidate_id"]
    detail = match(job_text, resumes[best], criteria)
    print(f"\n{best}: {detail['score']:.2f}")
    for c in detail["evaluated_criteria"]:
        print(f"  {c['match_status']:>13}  {c['label']}")


if __name__ == "__main__":
    main()

For 8 CVs this costs 8 (parse) + 1 (criteria) + 1 (rank) + 1 (match) = 11 credits. In a real pipeline you would cache the parsed text so a CV is only parsed once, even if it is matched against several jobs.

Practical notes

Batches over 10. Rank takes 10 candidates per call. For larger pools, score everyone with Match first and send the top 10 to Rank.
Errors. Non-2xx responses carry a JSON error. Treat 429 as retryable with a backoff; a 401 means the X-API-Key header is missing or wrong (Authorization: Bearer is not accepted).
Skills. If you store profiles, POST /api/v1/skills/resolve maps free-text skills ("Pack Office (Word, Excel)", "React.js") to taxonomy IDs, which makes search and facets much easier than raw strings.

Using it from an AI assistant instead

If you would rather ask Claude, Cursor or VS Code to "rank the CVs in ~/candidates for this job", the same five endpoints are wrapped in an open-source MCP server: github.com/louisdesc/hirelayer-mcp.

Questions or edge cases you hit with real CVs are very welcome in the comments.