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.

===== Overview ===== In Zotero >= 2.0, translators are just [[wp>Javascript|javascript]] files. While [[http://bitbucket.org/rmzelle/scaffold/downloads|Scaffold 2.0]] can [[how_to_write_a_zotero_translator_plusplus|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 [[http://support.mozilla.com/en-US/kb/profiles|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 [[http://kb.mozillazine.org/Profile_Manager|Profile Manager]] to [[http://support.mozilla.com/en-US/kb/managing+profiles|create a Firefox profile]]. (Remember below to [[http://kb.mozillazine.org/Starting_Firefox_or_Thunderbird_with_a_specified_profile|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 * [[/support/installation|the latest Zotero release]] * [[/support/dev_builds|a development XPI]] * [[dev/source_code#running_svngit_builds|from the Zotero code repository]] ===== 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 [[translators_reference_guide#translator_metadata|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 [[https://www.zotero.org/trac/browser/extension/branches/2.0/chrome/locale/en-US/zotero/zotero.properties#L240|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 ===== One can generate a completely new translator file using Scaffold 2.0. - Start Scaffold. - In tab=Metadata, take the generated ''translatorID'', but give some values for the ''label'', ''creator'', and ''target'' fields. (Note your filename will be based on the value of the ''label'' field: e.g. if you set that to ''foo'', your file will be named ''foo.js'') - In tab=Code, enter a ''detectWeb'' stub, e.g.

function detectWeb () {
return "book";
}

- Click on icon=Save (second from upper left). - Check your translator filespace: you should have a new file with name based on field=''label''. - Close Scaffold. You may do all subsequent work directly on the new file. However it is usually easier to create a new translator by copy/modify-ing an existing one. This can be done in one of several ways, including - working directly on an existing translator file (e.g. to fix a bug or add an feature) without modifying the ''translatorID''. Note that any Zotero update to the profile containing that file will overwrite your work. - "clearing out" your copy/modified file. Open it in your editor, and - in the metadata block, * create a new ''translatorID'' for your copy/modified file. Edit the old field randomly, or (better) generate a new value using Scaffold 2.0. * make the value of the ''label'' field match your new filename. - in the code section, clear out any undesired contents from the ''detectWeb'' and ''doWeb'' functions. - somewhat "between" the previous two: - Find an existing translator with functionality that resembles what you want. - Copy that to a new file in your translator filespace. - Open the new file and - change the metadata field=''label'' to match your filename (minus the ''.js'' extension) - assign a new value to field=''translatorID'', preferably after generating a new value using Scaffold 2.0. - change the ''detectWeb'' and ''doWeb'' functions as needed. ===== Edit, run, test, debug ===== ==== Enable debugging output ==== One must * configure Firefox to write Zotero debugging output to a [[wp>Terminal_emulator|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 [[http://www.zotero.org/support/debug_output#linux|linux]], [[http://www.zotero.org/support/debug_output#mac_os_x|mac]], and [[http://www.zotero.org/support/debug_output#windows_xp|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 [[translator_overview#step_5contribute_your_translator|contribute your translator]] to the community.