Created: 2011-07-12 07:11
Updated: 2018-08-31 05:48

Zotero Translation Server v1

This version of translation-server has been discontinued. Use the current version instead.

Server-side Zotero translation

Currently supports import, export, and web translation


The recommended version of translation-server for production use is available from Docker Hub:

docker run --rm -p 1969:1969 zotero/translation-server

To bind to a different port, change the first 1969 (e.g., -p 8080:1969).


Docker (recommended)

First, check out the source code and build an image:

  1. git clone --recursive translation-server-v1

  2. cd translation-server-v1

  3. docker build -t translation-server .

You can run the server right away with docker run -p 1969:1969 -ti --rm translation-server.

To make changes, you’ll need to edit files in the translation-server, Zotero, or Zotero Connector repositories. By default, the build script will use the included Zotero and Zotero Connector submodules in modules/zotero and modules/zotero-connector, but if you already have those repositories on your computer, you can point the build script to those directories instead. In either case, you’ll need to change to the Zotero client repository and run npm i and npm run build. (If making changes to the client repository, use npm start instead of npm run build to keep the client’s build subdirectory up to date while you work.)

Then, after each change, stop the server and re-run the following command:

Using the embedded submodules:

./ -k && docker run -p 1969:1969 -ti --rm -v `pwd`/build/app/:/opt/translation-server/app/ translation-server

Using external repositories:

./ -d ~/zotero-client/build -c ~/zotero-connectors -k && docker run -p 1969:1969 -ti --rm -v `pwd`/build/app/:/opt/translation-server/app/ translation-server

This will copy files from src and the client and connector repositories into build and mount that directory in the container in place of the directory created during the docker build step above.

To inspect the container before running the server, include --entrypoint /bin/bash in the docker run command.

To run translator tests, add -test /tmp/results.json to the end of the docker run line. You can specify individual tests to run by adding translator labels (e.g., "ACM Digital Library") to the includeTranslators array in chrome/content/zotero/tools/testTranslators/translatorTester.js in the main Zotero repo.

When you’re done, ensure your changes are applied to modules/zotero and modules/zotero-connector (either manually or by updating the submodule to point to your own fork of those repos) and rebuild the translation-server image to incorporate your changes.

Manually (unsupported)

  1. Install required libraries (e.g., by installing Firefox)

  2. git clone --recursive translation-server-v1

  3. cd translation-server-v1/modules/zotero/translators

  4. git pull origin master

  5. cd ..

  6. npm install && npm run build

  7. cd ../..

  8. ./fetch_sdk

  9. ./

  10. Run the server:

    $ build/ 
    zotero(3)(+0000000): HTTP server listening on *:1969

Try a query

$ curl -d '{"url":"","sessionid":"abc123"}' \
       --header "Content-Type: application/json" \


Supported endpoints are: /web, /import, /export, /search, and /refresh.

Read server_translation.js for more information.

Web Translators

Translates a web page

  • endpoint: /web
  • request method: POST
  • request body: JSON object containing a url and a random sessionid
  • example:
curl -X POST --header 'Content-Type: application/json' -d '{
  "url": "",
  "sessionid": "abc123"

Import Translators

Converts input in any format Zotero can import (RIS, BibTeX, etc.) to items in Zotero API JSON format

  • endpoint: /import
  • request method: POST
  • request body: item data in a supported format
  • example:
curl -X POST -d 'TY  - JOUR
TI  - Die Grundlage der allgemeinen Relativitätstheorie
AU  - Einstein, Albert
PY  - 1916
SP  - 769
EP  - 822
JO  - Annalen der Physik
VL  - 49
ER  -'

Export Translators

Converts items in Zotero API JSON format to a supported export format (RIS, BibTeX, etc.)

  • endpoint: /export
  • request method: POST
  • query parameter: format, which must be a supported export format
  • request body: An array of items in Zotero API JSON format
Cookies help us deliver our services. By using our services, you agree to our use of cookies Learn more