DEV Community: Equalang

Read Foreign Websites: Put Translations Under the Original

Equalang — Sun, 11 Oct 2026 12:42:39 +0000

When researching technical topics, documentation, or international news, you often land on foreign webpages. While the title might make sense, reading paragraphs of unfamiliar text usually requires some translation help. You want to understand the content, but you also want to see the original terms and phrasing.

Reading is much smoother when the translation sits directly below the source sentence. You can grasp the meaning first, then glance up to check the original words.

The Equalang browser extension does exactly this. Let’s walk through it with a Spanish Wikipedia article.

1. Set up side-by-side reading

To read bilingually on the original page, install the Equalang extension.

Choose the installation guide for your browser: Chrome, Edge, or Firefox. Safari currently offers temporary installation on Mac; see its guide for the limitations. The App Store version is not yet available.

We’ll use Chrome for this example. After installing and logging into your Equalang account, click the extension icon in the toolbar. Set your target language to English, and change the display mode to "Side by side".

With these settings, just click the floating ball on the webpage, and Equalang will translate the page.

2. Understand the meaning, check the original words

Once active, the translation appears right below its corresponding original sentence. You can scroll down the page and read paragraph by paragraph without breaking your flow.

In the opening paragraph, cielo nocturno becomes “night sky” and luminiscencia becomes “luminescence”. You can follow the description in English, then look up to see the Spanish words behind it.

Perhaps “night sky” is a phrase you want to remember. There it is: cielo nocturno, still in its sentence. You don’t need to switch the whole page back to Spanish and hunt for the same spot. When you are unsure about an expression, you can easily compare it against the original.

The blue links in this example keep their original destinations, too. The translated “night sky” link still leads to the Spanish Cielo nocturno page, so you can follow the source when your curiosity takes you further.

3. Return to the original text

If you have finished reading the translated parts, simply click the floating ball on the page again. The English translations will disappear, and the webpage will return to its original Spanish text so you can focus on the reading itself.

4. Just a few new words? Select to translate

If you can read most of the article and only stumble over a few unfamiliar words, you don't need to translate the whole page.

Turn on "Selection translation" in the extension panel. Then, select the tricky word on the webpage and click the Equalang icon that appears next to it. A pop-up window will show you the translation.

For example, selecting luminiscencia and clicking the icon gives you "luminescence" right there in the pop-up.

Read for the meaning first with side-by-side paragraphs, or just look up a specific term on the fly. The Equalang extension saves you from jumping between tabs to translate foreign webpages, keeping your attention on the content itself.

Sources

Spanish Wikipedia contributors. Aurora polar (accessed 2026-10-09; excerpts and translations: CC BY-SA 4.0).

Add Bilingual Subtitles to Your Course Recordings

Equalang — Sun, 11 Oct 2026 12:35:59 +0000

Whether it's an online lecture, a recorded meeting, or unedited interview footage, we often find ourselves stuck with a bare media file. Listening to a foreign language is demanding enough; add specialized terminology, and it becomes a real challenge to keep up.

Imagine being able to read the original phrasing alongside your native language. With a bilingual subtitle track, you can listen, read, pause, and rewind whenever you need.

You can use Equalang to process these audio and video files and output standalone subtitle files (SRT or VTT). You simply get a clean subtitle file ready to be dropped into your media player to accompany the original media.

See it in action

We tested this using a Spanish photography tutorial sample created by our team, translating it into English. Here's what it looks like when played with the dual-language subtitles:

The resulting bilingual SRT file looks like this (original language on top, translation below):

1
00:00:00,000 --> 00:00:03,680
Hoy vamos a aprender cómo la luz cambia la apariencia de 1 objeto en 1 foto.
Today, we’ll learn how light changes the look of an object in a photo.

2
00:00:04,120 --> 00:00:07,840
Para empezar, toma 1 foto de 1 objeto fijo desde donde estás parado.
First, take a photo of a stationary object from where you’re standing.

You can download the sample video course-es.mp4 and the bilingual subtitle file course-es-dual-equalang-en.srt to drop them into your local player and see how it feels. Keep in mind that if the speech recognition misidentifies a word, it will affect the translation. This is why having the original words right above the translation is so useful for reviewing and double-checking.

Simply Ask Your Assistant

The Equalang translation skill can now be integrated into various AI assistants like Claude Code and Codex.

For this practical example, we will use WorkBuddy, an AI desktop client, to demonstrate the workflow. With it, you don't need to know Python or run terminal commands; you can simply use natural language to have the assistant automatically process your local media files.

1. One-Time Setup

If you haven't already, first search for the "Equalang" skill in WorkBuddy's marketplace (under Skills/Connectors) and turn it on.

Next, grab your API Key from the API Keys page and follow the skill's instructions to configure it on your local machine. This authorizes the deduction of Equalang translation credits (which are billed separately from WorkBuddy's own chat usage).

2. State Your Request and Let It Run

Processing media uses Equalang credits. To avoid surprises, you can instruct the assistant to estimate the cost and automatically proceed only if it's within your budget:

Next, please use the Equalang skill to translate ~/Equalang-Demo/course-es.mp4 into English. Create bilingual SRT subtitles with Spanish above English, plus the plain-text transcripts. Estimate first; if the Equalang charge is at most 4 credits, you may proceed. Keep the files next to the video and give me links to open them. Do not read or display the configured API key. Reply in English.

The assistant will invoke the skill and check the file. Since the estimated cost is well within our 4-credit limit, it will seamlessly proceed with the processing without requiring further confirmation.

3. Get the Results and Watch

When the job finishes, the subtitle and transcript files will be saved right next to your original video. You will receive:

Bilingual Subtitles: In the dual-language format shown above.
Original Subtitles and Transcripts: Allowing you to review the raw words.

(Tip: A translation job automatically returns the original transcription. Unless you only want the raw text and no translation at all, there's no need to run a separate job just to transcribe—this saves you credits.)

Once you have the subtitles, open your media in a player that supports external subtitle tracks (like VLC or IINA), manually load the SRT file, and hit play to follow along in both languages.

Sources

Equalang LLMs API Reference: https://equalang.com/llms-full.txt
API Keys: https://equalang.com/api-keys
Equalang Skill Repository: https://github.com/equalang/equalang-skill

Translate Whole Files with Your AI Assistant Using Equalang

Equalang — Sat, 10 Oct 2026 09:21:41 +0000

If you regularly use AI tools like Claude Code, Codex, Cursor, or WorkBuddy, you might have run into a common barrier: translating a foreign language file. When you try to translate a 20-page research PDF or a detailed supplier contract by copying and pasting, it is often tedious and the original formatting gets disrupted.

By giving your assistant the Equalang skill, you can simply ask it to translate the file directly. The assistant will handle the document and return a fully translated file, trying to preserve the layout where supported.

Getting Started: The Easiest Way to Install

You don't need to run complex scripts or install dependencies yourself. Just copy and paste this exact sentence into your AI assistant's chat:

Install the Equalang skill by following the instructions at https://equalang.com/install/skill-install.md

The assistant will read the instructions, download what it needs, and guide you through the setup. It will ask you for an Equalang API key to process files. You can create one at https://equalang.com/api-keys and securely prepare the key according to the assistant's prompts, or save it locally as the official documentation describes.

(Note: This works in CLI and desktop agent environments like Claude Code, Codex, or Cursor, rather than standard web-based chat interfaces. Additionally, if your workflow prefers the Model Context Protocol, Equalang offers an MCP server at @equalang/mcp.)

Ask for Files Like You Ask for Text

Once installed, your assistant can process PDFs, Word documents, Excel spreadsheets, PowerPoint presentations, EPUB books, images, and audio/video files. Here is how you can use it for different tasks:

Reading Research Papers

When you find a foreign language research paper, you can ask your assistant to translate it so you can read it naturally without jumping between a translation tab and the document.

"Translate ~/Downloads/paper.pdf into English"

The assistant will return a translated PDF, trying to keep the charts and text in their original places so you can continue your research smoothly.

Working with International Documents

If a client or supplier sends you a contract or a slide deck in another language, translating it manually slide-by-slide can be a tedious process.

"Translate ~/Documents/supply-confirmation.zh-CN.docx into English"
"Translate pitch-deck.pptx into Spanish"

You will get an editable Word or PowerPoint file back. The translated version can be shared directly with your team for review.

Transcribing and Translating Media

For interviews, lectures, or foreign language videos, you can extract the spoken content directly into text or subtitles.

"Transcribe interview.mp3 as subtitles"
"Transcribe lecture.m4a into a text transcript"

Depending on what you ask for, the assistant will generate standard .srt or .vtt subtitles for your video player, or a plain text file of the transcription to help you study the content.

When you request a file translation, the assistant will spend Equalang credits. If you're unsure about a large file, you can always ask the assistant to estimate the cost first: "How much would it cost to translate thesis.docx into English?" It will check the maximum cost and wait for your approval before starting the job.

Giving your AI assistant the ability to output whole translated documents removes the friction of manual copying and reformatting, letting you focus directly on your research and work.

References / Sources

Equalang Skill Installation Instructions: https://equalang.com/install/skill-install.md
Equalang Agent Skill on GitHub: https://github.com/equalang/equalang-skill
Equalang API Keys: https://equalang.com/api-keys

Equalang API Reference & Quickstart

Equalang — Sat, 10 Oct 2026 09:18:36 +0000

When integrating Equalang into your management backend or workflow, you can translate text instantly or process entire files—such as documents, audio, and video—while keeping their original layout where supported.

This guide provides a quickstart for the file translation workflow using cURL and Python, followed by a complete reference for all 10 public API endpoints.

Authentication & Standard Response

The Equalang API is served at https://equalang.com/v1. Authenticate every request by providing your API key in the Authorization HTTP header:

Authorization: Bearer el_your_api_key_here

Your API key must have the correct scopes (e.g., translations:document for jobs, translations:text for text, files:read for direct file downloads).

Standard Response Envelope: All successful JSON responses use a standard top-level structure. For brevity, the structural examples below omit some non-essential fields but remain fully valid JSON objects. The IDs, URLs, and balance numbers shown are purely illustrative—ensure you use the actual values returned in your own responses.

{
  "code": "OK",
  "message": "ok",
  "data": {},
  "request_id": "req_example_id"
}

Quickstart: Asynchronous File Translation

Processing a whole document requires an asynchronous workflow: upload the file to start a job, poll its status, and download the result. You can use your own file, or download our sample file supply-confirmation.zh-CN.docx for testing.

Method 1: Using cURL

First, export your API key (you can create one at https://equalang.com/api-keys):

export EQUALANG_API_KEY="el_your_api_key_here"

1. Upload and Start Job

Submit the file directly. The API reserves the necessary credits and returns a job_id. Include a unique Idempotency-Key (such as a UUID) to prevent duplicate jobs if a timeout occurs. Reuse this key if you need to retry the same submission, and generate a new one for new tasks. (Make sure you have a local file named report.docx before running, or change the name in the code).

curl --fail-with-body -X POST "https://equalang.com/v1/jobs/translate" \
  -H "Authorization: Bearer $EQUALANG_API_KEY" \
  -H "Idempotency-Key: a-unique-uuid-here" \
  -F "file=@report.docx" \
  -F "target_language=en"

Extract the job_id from the response data object to use in the next step. Do not copy historical IDs from examples.

2. Poll Job Status

Use your job_id to poll progress. Wait for the duration recommended by the Retry-After header between requests. Stop polling when finished is true.

curl --fail-with-body "https://equalang.com/v1/jobs/your_actual_job_id" \
  -H "Authorization: Bearer $EQUALANG_API_KEY"

3. Download the Result

Once the status is SUCCEEDED, the response includes a temporary download_url. This URL uses a temporary signature authorization, so you do not need to (and should not) send your API Bearer token when downloading from it. Use a flag like -f to fail silently on HTTP errors so you don't save error HTML as your file.

curl -f -o report_translated.docx "https://example.com/download/your_temporary_signature_url"

Method 2: Using Python (requests)

Note: Requires the requests library (pip install requests).

import os
import time
import requests

API_KEY = os.environ.get("EQUALANG_API_KEY")
# Provide a stable key for the same request, change it for new tasks
IDEMPOTENCY_KEY = os.environ.get("IDEMPOTENCY_KEY", "your-unique-uuid-here")

HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Idempotency-Key": IDEMPOTENCY_KEY
}
BASE_URL = "https://equalang.com/v1"

# 1. Create Job
# Ensure you have a local file named report.docx before running
with open("report.docx", "rb") as f:
    files = {"file": f}
    data = {"target_language": "en"}
    response = requests.post(
        f"{BASE_URL}/jobs/translate",
        headers=HEADERS,
        files=files,
        data=data,
        timeout=30
    )
    response.raise_for_status()
    job_id = response.json()["data"]["job_id"]
    print(f"Job created: {job_id}")

# 2. Poll Job
while True:
    res = requests.get(f"{BASE_URL}/jobs/{job_id}", headers={"Authorization": f"Bearer {API_KEY}"}, timeout=30)
    res.raise_for_status()
    job_data = res.json()["data"]

    if job_data["finished"]:
        if job_data["status"] == "SUCCEEDED":
            download_url = job_data["download_url"]
            print(f"Success! Downloading result...")

            # 3. Download Result (No API key needed for the temporary URL)
            dl_res = requests.get(download_url, timeout=30)
            dl_res.raise_for_status()
            with open("report_translated.docx", "wb") as out:
                out.write(dl_res.content)
            print("Download complete.")
        else:
            print(f"Job ended with status: {job_data['status']}")
        break

    retry_after = int(res.headers.get("Retry-After", 5))
    time.sleep(retry_after)

For advanced use cases (like checking quotes first or recovering lost polling states), you can download our advanced script translate_file.py.

Endpoint Reference

Here are the details and payload structure examples for all 10 public endpoints.

Please note that document and text endpoints support different languages. Refer to the DocumentLanguage and TextLanguage enumerations in the OpenAPI schema or the Developers guide for the exact codes (e.g., zh-CN, en). The auto code is exclusively for source_language.

1. Translate Text

POST /v1/text/translate

Translate text strings synchronously. Texts are billed only if successfully translated. detected_source_language is null if a specific language wasn't automatically detected.

curl --fail-with-body -X POST "https://equalang.com/v1/text/translate" \
  -H "Authorization: Bearer $EQUALANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"texts": ["您的订单已发货。"], "target_language": "en"}'

{
  "code": "OK",
  "message": "ok",
  "data": {
    "translations": [
      {
        "translated_text": "Your order has been shipped.",
        "detected_source_language": null,
        "error": null
      }
    ],
    "usage": {
      "credits_charged": 0.07
    }
  },
  "request_id": "dd0b35ce1b52474faad670a33a9fc62d"
}

2. Upload File for Quotation

POST /v1/files

If you need to display the maximum potential cost before translating, upload the file here. It returns a file_id and a quote (credits required).

curl --fail-with-body -X POST "https://equalang.com/v1/files" \
  -H "Authorization: Bearer $EQUALANG_API_KEY" \
  -F "file=@report.docx"

{
  "code": "OK",
  "message": "ok",
  "data": {
    "file_id": "a132cf83-e641-41a3-9220-dfefb0e3d2a6",
    "quote": {
      "translate": 0.59,
      "transcribe": null
    }
  },
  "request_id": "e81b9f386ace4a82b63dc292c9cff669"
}

3. Create Document Translation Job

POST /v1/jobs/translate

Creates an asynchronous translation job. Accepts file (multipart), file_url, or file_id.

# Using a previously uploaded file_id
curl --fail-with-body -X POST "https://equalang.com/v1/jobs/translate" \
  -H "Authorization: Bearer $EQUALANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_id": "a132cf83-e641-41a3-9220-dfefb0e3d2a6", "target_language": "en"}'

{
  "code": "OK",
  "message": "ok",
  "data": {
    "job_id": "e861014d-72a1-4e2a-bfa3-36fa10d9978e",
    "status": "INIT",
    "credits_reserved": 0.59
  },
  "request_id": "36c7dc43855b4e9eae553e7fd656788c"
}

4. Create Transcription Job

POST /v1/jobs/transcribe

Extracts and returns the spoken text from an audio or video file as timed subtitles, without translating it.

curl --fail-with-body -X POST "https://equalang.com/v1/jobs/transcribe" \
  -H "Authorization: Bearer $EQUALANG_API_KEY" \
  -F "file=@interview.mp3" \
  -F 'options={"output_formats": ["srt", "txt"]}'

{
  "code": "OK",
  "message": "ok",
  "data": {
    "job_id": "b1a23c45-1234-5678-90ab-cdef12345678",
    "status": "INIT",
    "credits_reserved": 1.848
  },
  "request_id": "req_12345"
}

5. Query Job Status

GET /v1/jobs/{job_id}

Retrieves the progress and download links for an active or completed job. Replace {job_id} in the path with your actual UUID.

curl --fail-with-body "https://equalang.com/v1/jobs/e861014d-72a1-4e2a-bfa3-36fa10d9978e" \
  -H "Authorization: Bearer $EQUALANG_API_KEY"

{
  "code": "OK",
  "message": "ok",
  "data": {
    "job_id": "e861014d-72a1-4e2a-bfa3-36fa10d9978e",
    "status": "SUCCEEDED",
    "finished": true,
    "progress_percent": 100,
    "download_url": "https://example.com/download/download_url",
    "outputs": [
      {
        "kind": "translation",
        "format": "docx",
        "filename": "supply-terms.zh-cn-equalang-en.docx",
        "download_url": "https://example.com/download/download_url"
      }
    ]
  },
  "request_id": "7c7621312ab04f3da3492db98945e597"
}

6. Download File Bytes

GET /v1/files/{file_id}

Unlike the temporary download_url (which requires no API key), this endpoint allows you to download the raw bytes of any source or translated file stored on your account directly using its file_id. It requires an API key with the files:read scope.

curl -f "https://equalang.com/v1/files/2282396e-2b5e-43d9-853a-072c48b4d860" \
  -H "Authorization: Bearer $EQUALANG_API_KEY" \
  -o translated_result.docx

(Returns binary data directly, no JSON envelope)

7. Cancel Job

POST /v1/jobs/{job_id}/cancel

Cancels a job. If the job is INIT or QUEUED, it immediately becomes CANCELLED. If it is RUNNING, it enters a CANCELLING state until fully stopped.

curl --fail-with-body -X POST "https://equalang.com/v1/jobs/e861014d-72a1-4e2a-bfa3-36fa10d9978e/cancel" \
  -H "Authorization: Bearer $EQUALANG_API_KEY"

{
  "code": "OK",
  "message": "ok",
  "data": {
    "job_id": "e861014d-72a1-4e2a-bfa3-36fa10d9978e",
    "status": "CANCELLED",
    "finished": true,
    "usage": {
      "credits_reserved": 0,
      "credits_charged": 0
    }
  },
  "request_id": "502c12dff71149f588620e96b07769fb"
}

8. Retry Job

POST /v1/jobs/{job_id}/retry

Retries a job. You can retry if a job is FAILED and its error.retryable is true, or if it was CANCELLED. Retrying will reserve credits again. Note that if result delivery failed (RESULT_DELIVERY_FAILED), retrying will attempt delivery again but will not charge you for translation a second time.

curl --fail-with-body -X POST "https://equalang.com/v1/jobs/e861014d-72a1-4e2a-bfa3-36fa10d9978e/retry" \
  -H "Authorization: Bearer $EQUALANG_API_KEY"

{
  "code": "OK",
  "message": "ok",
  "data": {
    "job_id": "e861014d-72a1-4e2a-bfa3-36fa10d9978e",
    "status": "INIT",
    "finished": false,
    "usage": {
      "credits_reserved": 0.59,
      "credits_charged": 0
    }
  },
  "request_id": "497c3794b0a4497e890f64cc8b7d6d27"
}

9. List Jobs

GET /v1/jobs

Returns a paginated list of your translation and transcription jobs, starting with the newest. Pass limit and cursor (or offset) as query parameters to paginate.

curl --fail-with-body "https://equalang.com/v1/jobs?limit=10" \
  -H "Authorization: Bearer $EQUALANG_API_KEY"

{
  "code": "OK",
  "message": "ok",
  "data": {
    "items": [
      {
        "job_id": "e861014d-72a1-4e2a-bfa3-36fa10d9978e",
        "status": "SUCCEEDED",
        "task": "translate"
      }
    ],
    "limit": 10,
    "offset": 0,
    "total": 39,
    "next_cursor": "MjAyNi0xMC0wOVQxOD..."
  },
  "request_id": "e79cd556afe94424a558e12ca7c2aed8"
}

10. Check Credit Balance

GET /v1/credits/balance

Returns your available and frozen account credits.

curl --fail-with-body "https://equalang.com/v1/credits/balance" \
  -H "Authorization: Bearer $EQUALANG_API_KEY"

{
  "code": "OK",
  "message": "ok",
  "data": {
    "total_credits": 125.50,
    "frozen_credits": 1.50,
    "available_credits": 124.00
  },
  "request_id": "req_bal_123"
}

Handling Errors

Failed API requests return standard HTTP error statuses accompanied by an error response payload indicating the reason and whether the operation is retryable.

{
  "code": "INVALID_JOB_ID",
  "message": "Invalid job id",
  "data": null,
  "request_id": "9e97df047da640f7b60e10cfbc571711",
  "retryable": false
}

DEV Community: Equalang

Read Foreign Websites: Put Translations Under the Original

1. Set up side-by-side reading

2. Understand the meaning, check the original words

3. Return to the original text

4. Just a few new words? Select to translate

Sources

Add Bilingual Subtitles to Your Course Recordings

See it in action

Simply Ask Your Assistant

Sources

Translate Whole Files with Your AI Assistant Using Equalang

Getting Started: The Easiest Way to Install

Ask for Files Like You Ask for Text

Reading Research Papers

Working with International Documents

Transcribing and Translating Media

References / Sources

Equalang API Reference & Quickstart

Authentication & Standard Response

Quickstart: Asynchronous File Translation

Method 1: Using cURL

Method 2: Using Python (requests)

Endpoint Reference

1. Translate Text

2. Upload File for Quotation

3. Create Document Translation Job

4. Create Transcription Job

5. Query Job Status

6. Download File Bytes

7. Cancel Job

8. Retry Job

9. List Jobs

10. Check Credit Balance

Handling Errors

参考资料 / Sources