Table of Contents

Zotero Translators

Translators are at the core of one of Zotero’s most popular features: its ability to import and export item metadata from and to a variety of formats. Below we describe how translators work, and how you can write your own.

This page describes the function and structure of translators. For in-depth documentation on how to write translator code, see Coding.

Note: Before writing a translator for a site, look at the documentation on exposing metadata; website authors should try embedding the necessary metadata before attempting to write a translator.

If you're looking for a broken translator to fix, see the recent translator errors and check on one of the top reported errors. You can also check the status of many translators by reviewing the translator test overview.

Zotero translators can operate in four different ways (note that translators are not necessarily restricted to a single type):

Translator Structure

Zotero translators are stored as individual JavaScript files in the “translators” subdirectory of the Zotero data directory. Each translator contains a JSON metadata header, followed by the translator’s JavaScript code. This code must include certain top-level JavaScript functions, as determined by the translator type(s).

Metadata

An example of a JSON metadata header is shown below:

{
	"translatorID": "fcf41bed-0cbc-3704-85c7-8062a0068a7a",
	"label": "NCBI PubMed",
	"creator": "Simon Kornblith, Michael Berkowitz, Avram Lyon, and Rintze Zelle",
	"target": "https?://[^/]*(www|preview)[\\.\\-]ncbi[\\.\\-]nlm[\\.\\-]nih[\\.\\-]gov[^/]*/(?:m/)?(books|pubmed|sites/pubmed|sites/entrez|entrez/query\\.fcgi\\?.*db=PubMed|myncbi/browse/collection/|myncbi/collections/)",
	"minVersion": "2.1.9",
	"maxVersion": "",
	"priority": 100,
	"inRepository": true,
	"translatorType": 13,
	"browserSupport": "gcsbv",
	"lastUpdated": "2014-06-20 04:23:04"
}

The roles of the different metadata fields are:

Metadata Options

In addition to the required metadata fields described above, two optional fields exist, configOptions and displayOptions. Both are JavaScript objects, with several properties that control translator behavior:

An example of how these properties are set (taken from the BibTeX.js translator):

"configOptions": {"getCollections": true},
"displayOptions": {"exportCharset": "UTF-8", "exportNotes": true, "exportFileData": false, "useJournalAbbreviation": false}

Top-level Functions

Depending on the translator type, each Zotero translator must include certain top-level JavaScript functions:

See Translator Coding for a detailed description on how these functions can be coded.

Tools

The following tools can make coding Zotero translators easier:

Contributing Translators

If you created or modified a translator and wish to have it added to Zotero, or are looking for support on writing translators, please submit a pull request to the Zotero Translators GitHub repo. You can also ask questions about translator development on Zotero development mailing list.

To submit a pull request, fork the Zotero Translator GitHub repository, commit your changes (i.e., adding or modifying translator files), and create a pull request. You can use your Git client of choice, but for new users we recommend SmartGit, which is free for non-commercial purposes.

When you submit pull request on GitHub, your translator code will be reviewed, and you will receive comments from the Zotero developers or experienced volunteers. Once you've made any necessary changes, your translator will be added to the Zotero translator repository.

Licensing

Please note that contributed translators need to be licensed in a way that allows the Zotero project to distribute them and modify them. We encourage you to license new translators under the GNU Affero General Public License version 3 (or later), which is the license used for Zotero. To do so, just add a license statement to the top of the file. Take a look a recently committed translator, like “Die Zeit.js”, for an example of such a statement.

Recommendations for Translator Authors

While there are no strict coding guidelines for translators, there are some general recommendations:

  1. Web translator detect targets should be selective, to minimize the number of detectWeb functions that are run for each page.
  2. detectWeb, detectImport and detectSearch should be coded to minimize the likelihood of the corresponding doWeb, etc. function failing. Do your minimum required input checking the detect functions – a failing do function will cause user-visible errors.
  3. Make detect functions lightweight– they may be run on pages that a user is not even considering saving. Detect functions should not need to make additional HTTP requests. This obviously runs counter to the preceding point– find a happy medium.
  4. Minimize HTTP requests. More HTTP requests slow down the user, cause undue load on servers, and in general are bad.
  5. Don't leak user data. HTTP requests should in general not be directed to 3rd-party hosts.
  6. Document your code. If there are input data deficiencies and the translator is working around them, document the deficiencies. If there are specific types of pages that a web translator is for, provide example URLs and expected output.
  7. Produce translator tests when possible, covering the basic page types that the translator is designed to support.