OpenParable
Skip to content
← Back to skills

Develop Search Translator

Development
develop-search-translator

Develop Search Translator is an Agent Skill for development published in the zotero/translators repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Develop a search translator that looks up items by identifier (DOI, ISBN, PMID, arXiv ID, etc.) via an external API. NOT for websites with search pages — use develop-web-translator for those.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/zotero/translators/blob/HEAD/.agent/skills/develop-search-translator/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/develop-search-translator, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

What is a search translator?

A search translator takes a structured identifier (DOI, ISBN, PMID, arXiv ID, etc.) and looks up metadata from an external API. It does NOT receive a web page or document.

Common confusion: if the user wants to translate items from a website that has a search page, that's a web translator, not a search translator. Use develop-web-translator for that. Search translators are for identifier-based lookup services (like Crossref, OpenAlex, Library of Congress, etc.).

Prerequisites

Fetch and read the Zotero translator documentation:

Also read index.d.ts for type definitions.

Step 1: Gather information

  1. Label: The service name (e.g. "OpenAlex")
  2. Creator: The author's name
  3. Identifier types: What identifiers does this service accept? (DOI, ISBN, PMID, arXiv, etc.)
  4. API documentation: URL of the service's API docs

Look for existing search translators for patterns:

grep -l "detectSearch\|doSearch" *.js

Step 2: Initialize

node .bin/init-translator.mjs --label "<Label>" --creator "<Creator>" --type search

This scaffolds the file from the search translator template at .bin/templates/search.js. That file is the canonical structure a search translator should follow — read it when you need to know the expected shape of detectSearch/doSearch, or when a task asks you to make an existing translator better conform to the template.

Search translators have no target regex. They're triggered by identifier lookups in Zotero.

Step 3: Write the code

detectSearch(items)

Return true if the input contains identifiers this translator handles. The items parameter is an object (or array of objects) with identifier fields.

function detectSearch(items) {
    if (Array.isArray(items)) {
        return items.some(item => item.DOI || item.ISBN);
    }
    return !!(items.DOI || items.ISBN);
}

Valid search fields: DOI, ISBN, PMID, arXiv, identifiers, contextObject, adsBibcode, ericNumber, openAlex.

doSearch(item)

Look up the identifier via the service's API and create Zotero items.

async function doSearch(item) {
    let doi = item.DOI;
    if (!doi) return;

    let url = `https://api.example.com/works/${encodeURIComponent(doi)}`;
    let data = await requestJSON(url);

    let newItem = new Zotero.Item('journalArticle');
    newItem.title = data.title;
    newItem.date = data.published_date;
    newItem.DOI = doi;
    for (let author of data.authors) {
        newItem.creators.push({
            firstName: author.given,
            lastName: author.family,
            creatorType: 'author',
        });
    }
    // ... map other fields ...
    newItem.complete();
}

Key APIs:

  • requestJSON(url), requestText(url), request(url) — make HTTP requests to the external API.
  • new Zotero.Item(itemType) — create an item, set fields, call .complete().
  • ZU.cleanDOI(), ZU.cleanISBN(), ZU.cleanISSN() — normalize identifiers.
  • ZU.cleanAuthor(name, creatorType) — parse author name strings.

Step 4: Create tests

node .bin/create-test.mjs "<Label>.js" --search '{"DOI":"10.1234/example"}'

Test with multiple identifier types if supported.

Step 5: Verify and submit

Update lastUpdated every time you modify translator code.

node .bin/update-metadata.mjs "<Label>.js"
npm run lint -- "<Label>.js"
node .bin/run-tests.mjs "<Label>.js"