Translators are at the core of one of Zotero’s most popular features: its ability to add items from across the web using the Connector, and to import and export item metadata in 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 supports four different types of translators:
A single translator can have multiple types. For example, many import translators are also export translators (like RIS). Most web translators should just be web translators, but some translators for sites with widely-used identifier formats, like arXiv, are also search translators.
During development, you should fork the Zotero Translators GitHub repository and clone it to disk (see Contributing Translators). Scaffold will prompt you for the folder you cloned it into.
Zotero automatically keeps the “translators” subdirectory of the Zotero data directory up to date with the central repository. You generally should not touch the files in that directory.
Zotero translators are stored as individual JavaScript files. On disk, they have three sections:
var testCases =
, followed by a JSON array containing test casesScaffold manages the metadata object and test case array for you, and provides a template for a web translator body. Even if you don't use Scaffold all the time when editing, you should still use it whenever you want to create a new translator, edit metadata, or add/run/update test cases.
The roles of the different metadata fields are:
translatorID
) label
) creator
) target
) ^https?://(www\.)?example.com/
.detectWeb
function is run. If this function finds item metadata, the Zotero translator icon appears or becomes active in the browser. When multiple translators have a matching target, the translator with the lowest priority number is selected. Web translators with an empty target
string (e.g. the DOI translator) match every webpage, but normally have a high priority number and are only used when no other translator matches.configOptions
) RIS.js
and Note HTML.js
. Supported options include:Zotero.RDF
object. If “xml/dom”, Zotero will expose the data through the function Zotero.getXML()
. Zotero does not natively support importing N3 representations of RDF.true
or false
. If true
, an export translator will have access to the collection names and can recreate them in the exported file.displayOptions
) RIS.js
and BibTeX.js
. Supported options include:true
, and unchecked if the property is set to false
.minVersion
) priority
) translatorType
) translatorType
is 2 for an export translator, and 13 for a search/web/import translator, because 13=8+4+1.lastUpdated
Depending on the translator type, each Zotero translator must include certain top-level JavaScript functions:
detectWeb
is run to determine whether item metadata can indeed be retrieved from the webpage. Should return the detected item type (e.g. “journalArticle”, see the overview of Zotero item types), or, if multiple items are found, “multiple”. If detectWeb
returns false, the translator with the next-highest priority is selected, until all translators with a matching target have been exhausted.true
if it can, and false
if it cannot.true
if it can, and false
if it cannot.See Translator Coding for a detailed description on how these functions can be coded.
The following tools can make coding Zotero translators easier:
attr
, text
, and innerText
) to extract content from web pages. Your browser likely provides an inspector tool to help you understand pages' structure. You can access it by right-clicking and selecting Inspect (Firefox) or Inspect Element (Chrome).It's generally easiest to develop and test-run your translators within Scaffold, using the Browser tab (web translators), Test Input tab (import/search translators), or selecting an item in Zotero's main window (export translators) to provide input. You can also add automated tests for web, import, and search translators in the corresponding input tabs. Adding tests is highly recommended: real-world translator input is highly complex, and it's easy to break one thing in the process of trying to fix another.
If you want to run your translator outside of Scaffold using real items, click Save to Zotero in the Scaffold toolbar. For web translator development, you'll also need to sync your changes to the Connector: open Connector settings, go to Advanced, and click “Reset 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 repo, commit your changes (i.e., adding or modifying translator files), and create a pull request. You can use your Git client of choice. Most editors should have some built-in support for making Git commits and pushing branches.
If you have the GitHub CLI installed, simply run gh repo fork zotero/translators --clone
to fork and clone the repository in a single step.
When you submit a 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.
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. (Scaffold handles this automatically when you add the web translator template.)
While there are no strict coding guidelines for translators, there are some general recommendations:
detectWeb
functions that are run for each page.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.request
utility.npm ci
within your clone of the zotero/translators
repository. Scaffold runs ESLint continuously. To manually lint a translator, run npm run lint -- "Translator Filename.js"
.Continue to Coding for more information on translator development.