[Share] Translate PDF using pdf2zh and attach

[liszt01]

Description

Translate PDF using pdf2zh and attach the translated versions to the parent item.

Requirements

• pdf2zh must be installed

Usage

1. When saving PDF via Zotero Connector, the script will run automatically.

2. Alternatively, you can run it manually:

   1. Select one or more items or PDF attachments in Zotero.

   2. Trigger this script from the item menu.

   3. Wait for the translation to complete (this may take several minutes).

Event

Create Item

Operation

Script

Data

/**
 * Translate PDF using pdf2zh and attach the translated versions to the parent item
 * @author liszt01
 * @usage Select one or more items or PDF attachments, then trigger this script
 * @link https://github.com/windingwind/zotero-actions-tags/discussions/491
 * @see https://github.com/windingwind/zotero-actions-tags/discussions/491
 */

// ---------- Configuration Section Start ----------
const pdf2zhPath = "/Users/alice/.local/bin/pdf2zh";  // For Windows: "C:\\Users\\alice\\.local\\bin\\pdf2zh.exe"

const config = {
	li: "en",
	lo: "zh",
	s: "google",
	t: "4",
};
// ---------- Configuration Section End ----------

const sleep = (time) => new Promise((resolve) => setTimeout(resolve, time));

async function getPDFAttachment(item) {
	let pdfAttachment;

	if (item.isPDFAttachment()) {
		pdfAttachment = item;
	} else if (item.isRegularItem()) {
		const maxTries = 12;
		let attempts = 0;

		// Wait for Zotero Connector to save the PDF
		while (attempts < maxTries) {
			const pdfs = item.getAttachments()
				.map(id => Zotero.Items.get(id))
				.filter(att => att.isPDFAttachment());
			
			if (pdfs.length > 0) {
				if (attempts == 0) {
					pdfAttachment = pdfs[0];
				} else {
					// Wait for attachment manager (e.g., Attanger, ZotMoov, etc.) to move the PDF
					await sleep(10000);
					pdfAttachment = item.getBestAttachment();
				}
				break;
			}

			await sleep(5000);
			attempts++;
		}
	}
	
	if (!pdfAttachment) {
		throw new Error("[pdf2zh] PDF attachment not found within timeout.");
	}
	return pdfAttachment;
}

function buildOutputPaths(srcPDFPath) {
	const dir = PathUtils.parent(srcPDFPath);
	const baseName = PathUtils.filename(srcPDFPath).replace(/\.pdf$/i, "");

	return {
		mono: PathUtils.join(dir, `${baseName}-mono.pdf`),
		dual: PathUtils.join(dir, `${baseName}-dual.pdf`),
		dir,
	};
}

async function runPDF2zh(srcPDFPath, outputDir) {
	config.o = outputDir;
	const args = [srcPDFPath, ...Object.entries(config).flatMap(([k, v]) => [`-${k}`, v])];
	await Zotero.Utilities.Internal.exec(pdf2zhPath, args);
}

async function attachTranslatedPDF(parentItemID, dstPDFPath) {
	const zoteroPane = Zotero.getActiveZoteroPane();
	const addedItems = await zoteroPane.addAttachmentFromDialog(true, parentItemID, [dstPDFPath]);
	Zotero.debug(`[pdf2zh] Translated PDF attached: ${addedItems[0].getField("title")}`);
}

async function translatePDFAttachment(item) {
	try {
		if (!item) return;
		if (!item.isRegularItem() && !item.isPDFAttachment()) {
			throw new Error("[pdf2zh] Please select a regular item or PDF attachment.");
		}

		if (!await IOUtils.exists(pdf2zhPath)) {
			throw new Error(`[pdf2zh] Could not find pdf2zh at ${pdf2zhPath}.`);
		}

		const pdfAttachment = await getPDFAttachment(item);
		const srcPDFPath = await pdfAttachment.getFilePathAsync();
		const { mono, dual, dir } = buildOutputPaths(srcPDFPath);

                await sleep(60000);
		await runPDF2zh(srcPDFPath, dir);

		if (!await IOUtils.exists(mono)) {
			throw new Error(`[pdf2zh] mono PDF not found at ${mono}`);
		}
		if (!await IOUtils.exists(dual)) {
			throw new Error(`[pdf2zh] dual PDF not found at ${dual}`);
		}

		await attachTranslatedPDF(pdfAttachment.parentItemID, mono);
		await attachTranslatedPDF(pdfAttachment.parentItemID, dual);

		return `[pdf2zh] Translation and attachment complete: ${pdfAttachment.getField("title")}`;
	} catch (err) {
		Zotero.debug(err);
		return `[pdf2zh] Error: ${err.message}`;
	}
}

return await translatePDFAttachment(item);

Anything else

No response

[YJ-He]

WIn10上尝试了一下，但是提示无法打开pdf文件，不知道是不是因为文件名太长。

[liszt01]

Thanks for the info!

I don’t think the error is due to the file name being too long — it seems more likely that the translated PDF simply isn’t being generated.

I tested this on my Windows 11 setup, and it looks like Zotero.Utilities.Internal.subprocess() isn’t working as expected. When I run the pdf2zh executable directly from the terminal, it works fine. But when I try running it through Zotero (using the script), no translated PDF is created.

To narrow it down, I also tried executing some basic commands like cmd.exe and whoami.exe via subprocess() from within Zotero, but none of them seemed to work. It appears that the subprocess function isn’t launching anything at all on my system.

[YJ-He]

I tried again. If you just use Zotero.Utilities.Internal.exec to replace Zotero.Utilities.Internal.subprocess, then everything will be okay. Thanks anyway!

[Haolius]

在win11上使用了一下，但是无事发生，已经安装了pdf2zh这是我的pdf2zh的安装路径:pdf2zhPath = "D:\pdf2zh\build\pdf2zh.exe"

[Haolius]

pdf2zh桌面版需要使用管理员权限才可以运行，是因为这个吗

[Haolius]

I used it on win11, but nothing happened. I have installed pdf2zh. This is the installation path of my pdf2zh: pdf2zhPath = "D:\pdf2zh\build\pdf2zh.exe

[liszt01]

Thank you for your feedback. First, please make sure that the backslashes in your path are escaped properly in the code — for example, it should be:

pdf2zhPath = "D:\\pdf2zh\\build\\pdf2zh.exe"

Also, the translation process may take a few minutes and it might appear that nothing is happening.
You can confirm that the translation is running by checking whether the pdf2zh process is active in Task Manager.

Let me know if you continue to experience issues!

[whubao]

pdf2zh is too slow to start, how to solve this problem?

[whubao]

使用google或者bing翻译出的文字不通顺，如何使用deepseek等大模型翻译或者本地ollama翻译？是不是必须在本地使用docker安装服务器server才能使用大模型翻译服务呢？

[liszt01]

The delayed startup of pdf2zh is intentional.
It waits for 60 seconds to avoid putting too much load on the translation server:

await sleep(60000);
await runPDF2zh(srcPDFPath, dir);

If you want faster execution, you can comment out the await sleep(60000); line.

To use DeepSeek or Ollama with pdf2zh, you need to update the s field in config.

const config = {
    li: "en",
    lo: "zh",
    s: "google",  // "deepseek" or "ollama"
    t: "4",
};

You’ll also need to set the appropriate environment variables like DEEPSEEK_API_KEY, DEEPSEEK_MODEL, or OLLAMA_HOST, OLLAMA_MODEL.

For more details, please check the documentation here:
https://github.com/Byaidu/PDFMathTranslate/blob/main/docs/ADVANCED.md#services

You don't necessarily need Docker to use Ollama — see their guide here:
https://ollama.com/

[whubao]

Thank you very much, I have find the solution according to your suggestions.
We should add the json file to add the API key.

[whubao]

And provide the path of the config.json in the config.

[whubao]

如何不翻译参考文献？