# 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.

- Skill name: `develop-import-translator`
- Category: [Development](https://www.openparable.com/skill/development/1)
- Source: https://github.com/zotero/translators/blob/HEAD/.agent/skills/develop-import-translator/SKILL.md
- Repository: zotero/translators (1,650 GitHub stars when collected)

## SKILL.md

## Prerequisites

Fetch and read the Zotero translator documentation:
- https://www.zotero.org/support/_export/raw/dev/translators
- https://www.zotero.org/support/_export/raw/dev/translators/coding

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.

```js
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.

```js
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"
```

---

Source: https://www.openparable.com/skill/development/develop-import-translator (OpenParable). Cite the canonical URL above.
