OpenParable
Skip to content
← Back to skills

Develop Import Translator

Development
develop-import-translator

Develop Import 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 an import translator that parses a file format (JSON, XML, RIS, BibTeX, CSV, etc.) into Zotero items.

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-import-translator/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/develop-import-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.

Prerequisites

Fetch and read the Zotero translator documentation:

Also read index.d.ts for type definitions.

Step 1: Gather information

  1. Label: The format name (e.g. "My Custom JSON")
  2. Creator: The author's name
  3. Example data: A sample of the format to import

Look for existing import translators that handle similar formats:

grep -l "detectImport\|doImport" *.js

Step 2: Initialize

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

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

If the translator should also export the same format, use --type import,export and implement doExport() as described in the develop-export-translator skill.

Import translators have no target regex — they match on content via detectImport().

Step 3: Write the code

detectImport()

Read the first few lines with Zotero.read() and return true if the format matches. Be specific to avoid false positives with other formats.

function detectImport() {
    let start = '';
    for (let i = 0; i < 10; i++) {
        let line = Zotero.read();
        if (line === false) break;
        start += line;
    }
    // Check for a distinctive marker in the format
    return start.includes('"my_format_version"');
}

doImport()

Read the full input, parse it, and create items.

async function doImport() {
    // Read all input
    let text = '';
    let line;
    while ((line = Zotero.read()) !== false) {
        text += line;
    }

    let data = JSON.parse(text);
    for (let record of data.records) {
        let item = new Zotero.Item('journalArticle');
        item.title = record.title;
        item.date = record.date;
        for (let author of record.authors) {
            item.creators.push({
                firstName: author.first,
                lastName: author.last,
                creatorType: 'author',
            });
        }
        // ... map other fields ...
        item.complete();
    }
}

Key APIs:

  • Zotero.read(length) — read characters from input. Returns false at EOF. With no argument, reads one line.
  • new Zotero.Item(itemType) — create an item. Set fields as properties, then call .complete().
  • For XML: (new DOMParser()).parseFromString(text, 'text/xml')
  • For line-based formats (RIS, BibTeX): read and parse line by line.

Step 4: Create tests

node .bin/create-test.mjs "<Label>.js" --input '<paste example data here>'

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"