feat: add AbortController/signal support to cancel in-flight translation requests

[Copilot]

Adds AbortSignal support to the Options interface so callers can cancel in-flight translation requests via the standard AbortController API, which axios already supports natively.

Changes

• src/googletrans.ts — Added signal?: AbortSignal to Options; forwarded it to the axios request config
• README.md — Documented the signal option with a usage example
• src/__tests__/test.ts — Added a test asserting that aborting before resolution rejects with a cancellation error

Usage

const controller = new AbortController();

const promise = tr("Hello world", { to: "zh-CN", signal: controller.signal });
controller.abort();

try {
  await promise;
} catch (err) {
  if (axios.isCancel(err)) {
    console.log("Request was cancelled");
  }
}

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• registry.npmmirror.com
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/_temp/ghcca-node/node/bin/npm install (dns block)
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/_temp/ghcca-node/node/bin/npm ci (dns block)
• translate.google.com
  • Triggering command: /opt/hostedtoolcache/node/24.14.0/x64/bin/node /opt/hostedtoolcache/node/24.14.0/x64/bin/node /home/REDACTED/work/googletrans/googletrans/node_modules/jest-worker/build/workers/processChild.js (dns block)
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node node_modules/jest/bin/jest.js --config jestconfig.json --testPathPattern=test.ts --testNamePattern=(AbortController|getCode|getToken|random|getUserAgent|getReslut|Security|Additional Branch|test-helpers) (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

Feature Request

Implements issue #148: Add the ability to abort/cancel/terminate a translation request mid-way using the standard AbortController / AbortSignal API, which axios natively supports.

---

Changes Required

1. src/googletrans.ts

Extend the Options interface to include an optional signal field:

interface Options {
  from?: string;
  to?: string;
  tld?: string;
  client?: string;
  signal?: AbortSignal; // NEW
}

Pass signal to the axios call inside the translate() function (around line 154):

const res = await axios({
  url: URL,
  params: PARAMS,
  headers: HEADERS,
  timeout: 3 * 1000,
  signal: _opts.signal, // NEW
  paramsSerializer: (params) => {
    return qs.stringify(params, { arrayFormat: "repeat" });
  },
});

Make sure signal is extracted and handled properly from _opts so it doesn't interfere with other option processing (e.g., it should not be passed to getCode, getSafeTld, etc.).

2. README.md

Add a documentation section explaining how to use the new signal option with AbortController. Example:

const controller = new AbortController();

// Start a translation
const promise = googletrans("Hello world", { to: "zh-CN", signal: controller.signal });

// Cancel the request at any time
controller.abort();

try {
  const result = await promise;
} catch (err) {
  if (axios.isCancel(err) || err.name === "CanceledError" || err.name === "AbortError") {
    console.log("Request was cancelled");
  }
}

3. Tests (optional but encouraged)

If there are existing test files in src/__tests__/, add a test case that:

• Creates an AbortController
• Calls googletrans() with the signal
• Immediately calls controller.abort()
• Asserts that the returned promise rejects with a cancellation error

---

Acceptance Criteria

• Options interface includes signal?: AbortSignal
• The signal is passed to the axios request config
• Aborting via controller.abort() causes the in-flight request to be cancelled
• README documents the new signal option with a usage example
• Existing tests continue to pass

The following is the prior conversation context from the user's chat exploration (may be truncated):

User: can you do it？

Assistant: I can see you're referencing this GitHub issue: #148

Let me fetch the details of that issue first!

Assistant: Here's a summary of the issue:

[Feature request] Add ability to abort/cancel/terminate the request mid-way
DarinRowe/googletrans#148

• Opened by: @FightFarewellFearless (~18 hours ago)
• Status: Open
• Request: Add support for AbortController in the options parameter, so users can cancel/terminate an in-flight translation request mid-way — similar to how axios natively supports it.

---

Would you like me to create a pull request to implement this feature (i.e., add AbortController / signal support to the googletrans options)? If so, I can get started on that right away!

User: 可以实现吗

Assistant: Let me look at the repository code to understand the current implementation before determining feasibility.

Assistant: 完全可以实现！✅

我仔细查看了源代码，以下是分析：

---

可行性分析

现有代码结构

• 核心文件：src/googletrans.ts
• 使用 axios 发起 HTTP 请求（第 154-163 行）
• 当前 Options 接口只有 from、to、tld、client 四个字段

实现方案

axios 原生支持 cancelToken 和 signal（AbortController），只需做以下修改：

1. 扩展 Options 接口，添加 signal 字段：

interface Options {
  from?: string;
  to?: string;
  tld?: string;
  client?: string;
  signal?: AbortSignal; // 新增
}

2. 在 axios 调用时传入 signal：

const res = await axios({
  url: URL,
  params: PARAMS,
  headers: HEADERS,
  timeout: 3 * 1000,
  signal: _opts.signal, // 新增
  paramsSerializer: (params) => {
    return qs.stringify(params, { arrayFormat: "repeat" });
  },
});

3. 用户使用示例：

const controller = new AbortController();

googletrans("Hello", { to: "zh-CN", signal: controller.signal });

// 任意时刻取消请求
controller.abort();

---

改动量

改动点	复杂度
扩展 Options 接口	极简单
translate() 函数传入 signal	极简单
googletrans() 入口函数兼容	简单
更新 README 文档	中等
补充单元测试	中等

---

是否要我直接创建一个 Pull Request 来实现这个功能？🚀

User: do it

Assistant: We're waiting for your response to the tool call dialog to continue — please accept or reject it to proceed!

This pull request was created from Copilot chat.

---

💬 Send tasks to Copilot coding agent from Slack and Teams to turn conversations into code. Copilot posts an update in your thread when it's finished.

[Copilot]

Pull request overview

Adds first-class request cancellation support by threading an AbortSignal through the library’s translation request path (axios), plus documentation and a test to validate cancellation behavior.

Changes:

• Extended the public Options interface with signal?: AbortSignal.
• Forwarded signal into the axios request config so callers can cancel in-flight requests via AbortController.
• Documented the new option in the README and added a Jest test covering abort/cancel behavior.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
src/googletrans.ts	Adds signal to Options and passes it to axios to enable cancellation.
src/__tests__/test.ts	Adds an abort/cancel test for the new signal option.
README.md	Documents signal and provides a cancellation usage example.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.