Translations of this page:

This is an old revision of the document!

We’re in the process of updating the documentation for Zotero 5.0. Some documentation may be outdated in the meantime. Thanks for your understanding.


An overview of translation documentation can be found here.

What is a translator?

(Rintze, Debbie) Migrate Adam's docs (relevant portions) and update

Contrary to what the name may imply, “translator” in this context does not mean Zotero will translate a web page from one language into another (like English into Spanish for example.) A translator is, simply put, that folder, book, newspaper or moviereel icon that pops up in the URL when you're on a page that Zotero can recognize. Programming-wise, a translator is some code bundled into your Zotero translator library which enables Zotero to recognize a particular web page, pull citation data off of it, and convert that data into a form ingest-able by the Zotero client. If no translator script exists in the Zotero translator library for a Web site that you're on, Zotero will not be able to “recognize” the site (and so no cute little icon will appear by the URL.) This section will explain how translators work, how to build and debug a translator, and how to choose the type of translator that's best for the web site in question.

How does a translator work?

Here is a textual explanation of how a translator works, as well as a diagram.

Before You Begin

Depending on what you what you want to do with translators, the difficulty level varies. For instance, if you want to just tweak a simple, already-created translator, there are quickie methods for doing that and you don't necessarily have to know JavaScript (TODO: link to video/text). However, if you want to create something from scratch, more knowledge will likely be required. Also affecting your decision will be whether or not you have control over the guts of the web page you want to make a translator for (are you a site admin? the designer? Or just a fan?)

Translator Types, Skills, Tools, and a Basic Question

What are the types of translators?

What skills are required to build one?

What tools are required to build one?

Does the translator I want to build already exist?
Sometimes, Zotero will not recognize a page for which it has a translator already; in other words, no little icon appears next to the URL when it should. A frequent reason is that the Web site the translator is trying to parse has changed, and the translator needs to be tweaked to accommodate those changes. So that you don't reinvent the wheel and try to re-create a translator Zotero already has, consult the current list of Zotero translators.

(ask Avram)

A web site I use and like does not currently support Zotero. What are the steps I should take to make Zotero recognize it?

Creating Translators

Two guides are provided here for creating translators: a beginner's guide to creating “scrapers” and an advanced guide. JavaScript Beginners and people who'd prefer using tools to help them interface with Zotero may prefer Adam Crymble's guide for creating translators. Seasoned JavaScript programmers may find using tools like Scaffold tedious, and so may prefer the advanced guide, which omits usage of such tools.

How to Write a Zotero Translator, 2nd Edition Language tutorials provided Required tools
Adam Crymble's web based guide for building a “scraper”, updated and wiki-fied. It's a work in progress but is the best place to find up-to-date information on how to create translators. It is recommended for people who have not programmed with Javascript before as it provides introductions to various web languages, as well as pointers to tools which can make creating a translator a bit simpler for beginners. Because not all information has been migrated from Adam's site to the wiki version, you will find yourself toggling between the chapters on his site and here. (We're working on fixing that.) Javascript, Xpath, DOM, Regular Expressions Scaffold, Firebug, DOM inspector, Zotero

This tutorial is an adaptation of 'How to Write a Zotero Translator' (2009) by Adam Crymble. The 2nd Edition has been created to bring the tutorial up-to-date with Zotero 2.x translator development.

Erik's Translator framework
This template code simplifies scraper development and can be used in conjunction with Scaffold (that is, along with Adam's guide) or without.
Translator structure
Documentation on the structure and metadata of translators
Translator coding
Documentation on the techniques and available functions for translators

More Resources

  • How to Build a Translator Videos
dev/translators/tutorial.1510534411.txt.gz · Last modified: 2017/11/22 11:13 (external edit)