Zotero Translation Server

The Zotero translation server lets you use Zotero translators without the Zotero client.

Installation

Running via Docker

The easiest way to run a local instance of translation-server is via Docker.

docker pull zotero/translation-server
docker run -d -p 1969:1969 --rm --name translation-server zotero/translation-server

This will pull the latest image from Docker Hub and run it as a background process on port 1969. Use docker kill translation-server to stop it.

Running from source

First, fetch the source code and install Node dependencies:

1. git clone --recurse-submodules https://github.com/zotero/translation-server

2. cd translation-server

3. npm install

Once you've set up a local copy of the repo, you can run the server in various ways:

Node.js

npm start

Docker (development)

Build from the local repo and run in foreground:

docker build -t translation-server .
docker run -ti -p 1969:1969 --rm translation-server

AWS Lambda

translation-server can also run on AWS Lambda and be accessed through API Gateway. You will need the AWS SAM CLI to deploy the server.

Copy and configure config file:

cp lambda_config.env-sample lambda_config.env

Test locally:

./lambda_local_test lambda_config.env

Deploy:

./lambda_deploy lambda_config.env

You can view the API Gateway endpoint in the Outputs section of the console output.

User-Agent

By default, translation-server uses a standard Chrome User-Agent string to maximize compatibility, plus a ZoteroTranslationServer/WMF signifier. This is fine for personal usage, but for a deployed service, it’s polite to customize User-Agent so that sites can identify requests and contact you in case of abuse.

You can do this by setting the USER_AGENT environment variable:

USER_AGENT='my-custom-translation-server/2.0 (me@example.com)' npm start

If you find that regular requests are being blocked with a fully custom user-agent string, you can also add an identifier and contact information to the end of a standard browser UA string:

export USER_AGENT='Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/110.0.0.0 Safari/537.36 my-custom-translation-server/2.0 (me@example.com)'
npm start

Proxy Support

You can configure translation-server to use a proxy server by setting the HTTP_PROXY and HTTPS_PROXY environment variables:

HTTP_PROXY=http://proxy.example.com:8080 HTTPS_PROXY=http://proxy.example.com:8080 npm start

If your proxy server uses a self-signed certificate, you can set NODE_TLS_REJECT_UNAUTHORIZED=0 to force Node to ignore certificate errors.

It’s also possible to opt out of proxying for specific hosts by using the NO_PROXY variable. See the Node request library documentation for more details.

Running tests

npm test

Endpoints

Documentation

Swagger documentation is available at http://127.0.0.1:1969/?doc

Web Translation

Retrieve metadata for a webpage:

$ curl -d 'https://www.nytimes.com/2018/06/11/technology/net-neutrality-repeal.html' \
   -H 'Content-Type: text/plain' http://127.0.0.1:1969/web

Returns an array of translated items in Zotero API JSON format

Retrieve metadata for a webpage with multiple results:

$ curl -d 'https://www.ncbi.nlm.nih.gov/pubmed/?term=crispr' \
   -H 'Content-Type: text/plain' http://127.0.0.1:1969/web

Returns 300 Multiple Choices with a JSON object:

{
	"url": "https://www.ncbi.nlm.nih.gov/pubmed/?term=crispr",
	"session": "9y5s0EW6m5GgLm0",
	"items": {
		"u30044970": {
			"title": "RNA Binding and HEPN-Nuclease Activation Are Decoupled in CRISPR-Cas13a."
		},
		"u30044923": {
			"title": "Knockout of tnni1b in zebrafish causes defects in atrioventricular valve development via the inhibition of the myocardial wnt signaling pathway."
		},
		// more results
	}
}

To make a selection, delete unwanted results from the items object and POST the returned data back to the server as application/json.

Search Translation

Retrieve metadata from an identifier (DOI, ISBN, PMID, arXiv ID):

$ curl -d 10.2307/4486062 -H 'Content-Type: text/plain' http://127.0.0.1:1969/search

Export Translation

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

$ curl -d @items.json -H 'Content-Type: application/json' 'http://127.0.0.1:1969/export?format=bibtex'

Import Translation

Convert items in any import format to the Zotero API JSON format:

$ curl --data-binary @data.bib -H 'Content-Type: text/plain' http://127.0.0.1:1969/import