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

1. find or create a Zotero development environment
2. find or create a translator development environment
3. create or modify a translator file
4. edit, run, test, debug
5. contribute your translator

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,

1. 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.)
2. install the desired version of Zotero into your Firefox profile. One can install either
   • the latest Zotero release
   • a development XPI
   • from the Zotero code repository

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

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?

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.

TODO:

• Zotero-enabled tools
• Zotero API guides
• Javascript-enabled tools
• XPath tools

One can

• create a new translator file by copy/modify-ing an existing one. This may involve
• work directly on an existing translator file (e.g. to fix a bug or add an feature) without modifying the translatorID.

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.

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.

If you have made changes to the metadata block of your translator, you must restart the Firefox profile containing your modified translator.

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.

Once your translator works on a subset of the sites on which you believe it should work, please contribute your translator to the community.