This is an old revision of the document!
Overview
In Zotero >= 2.0, translators are just javascript files. While Scaffold 2.0 can ease translator development, some prefer to work directly on the filesystem. To do this, one should
- find or create a Zotero development environment
- find or create a translator development environment
- create or modify a translator file
- edit, run, test, debug
- contribute your translator
Find or create a Zotero development environment
One develops a translator to run on/against a given version of Zotero, which runs on/against a given version of Firefox. The easiest way to do this is just to use the current version of Zotero that is running in your current Firefox profile. One can identify the path to one's current Zotero directory using the Zotero UI: select the gear icon to dropdown its menu, and choose Preferences>Advanced>Show Data Directory.
While convenient, using one's current Zotero
- runs the risk of corrupting one's current Zotero data, i.e. one's saved citations.
- does not allow one to develop against another version of Firefox or Zotero.
To create a separate Zotero development environment,
- Use Firefox's Profile Manager to create a Firefox profile. (Remember below to start Firefox using that profile.) (Note that, by default, only one Firefox profile can run at any given time.)
- install the desired version of Zotero into your Firefox profile. One can install either
Find or create a translator development environment
When developing directly against the filesystem, one's translator development environment is
- one's collection of one or more translator files
- the tools one uses to work on them
Translator files
Translator file location
Zotero installs its translators and related code as files in the subdirectory translators. I.e.
- if the path to your Firefox profile=
${FIREFOX_PROFILE}
then the path to your Zotero is
${FIREFOX_PROFILE}/zotero
- if the path to your Zotero=
${FIREFOX_PROFILE}/zotero
then the path to your translators, and hence to your translator development environment, is
${FIREFOX_PROFILE}/zotero/translators
(See above regarding using Zotero UI to identify the path to your current Zotero.)
TODO: how to get alternate/uplevel versions of translators?
Translator file structure
At the highest level, a Zotero translator (for versions >= 2.0) consists of
- a single metadata block, usually at the beginning of the file. The most important of its fields is the translatorID, which is the global identifier for the translator.
- non-metadata code, consisting of
- a detectWeb function. This must return a string corresponding to a defined Zotero type. For a list of Zotero type names, see the values of the itemTypes.* properties in this Zotero property list (or a newer one).
- a doWeb function. This actually writes an item corresponding to your web resource to your Zotero repository.
Translator development tools
TODO:
- Zotero-enabled tools
- Zotero API guides
- Javascript-enabled tools
- XPath tools
Create or modify a translator file
Edit, run, test, debug
Enable debugging output
One must
- configure Firefox to write Zotero debugging output to a terminal emulator (e.g.
xterm
,terminal
,cmd
) - start Firefox via command-line from a terminal emulator (i.e. not via an icon)
before one can see output from, e.g., Zotero.debug() calls. See detailed instructions for linux, mac, and windows.
Running a modified translator
Zotero does not currently sense changes to a translator file after it has been loaded. The actions required to reload a modified translator depend on what has been modified: metadata or other code.
Running a translator after modifying metadata
If you have made changes to the metadata block of your translator, you must restart the Firefox profile containing your modified translator.
Running a translator after modifying non-metadata code
If you have made changes to code outside the metadata block of your translator, you need only restart the page on which you want to run the translator.
Contribute your translator
Once your translator works on a subset of the sites on which you believe it should work, please contribute your translator to the community.