| Next revision | Previous revision |
| dev:translators:tutorial [2011/04/19 10:41] – created rmzelle | dev:translators:tutorial [2017/11/22 11:13] (current) – Remove outdated translator info bwiernik |
|---|
| ====== Translators ====== | **Note:** This page used to hold an updated version of Adam Crymble's [[http://niche-canada.org/member-projects/zotero-guide/chapter1.html|How to Write a Zotero Translator]]. The guidance included in both Adam's original guide and this update is too outdated to be useful and translators based on it are no longer accepted. We instead recommend the following resources: |
| \\ \\ | |
| |
| An overview of translation documentation can be found [[dev/Creating Translators for Sites|here]]. | * The template code included in [[https://www.zotero.org/support/dev/translators/scaffold|Scaffold]], |
| ==== What is a translator? ==== | * The code of [[https://github.com/zotero/translators/pulls|recently updated translators]], |
| //(Rintze, Debbie) Migrate Adam's docs (relevant portions) and update// | * The documentation for writing Zotero translators by [[https://www.mediawiki.org/wiki/Citoid/Creating_Zotero_translators|Wikimedia]], the most comprehensive and up-to-date resource for writing "scrapers" as of November 2017, |
| | * The [[https://www.zotero.org/support/dev/translators/coding|translator coding documentation]], |
| | * Search for answers in the [[https://forums.zotero.org/discussions|Zotero Forums]] and [[https://github.com/zotero/translators/issues|on GitHub]]. |
| |
| 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?// \\ | |
| * If you [[have control over internal site content]], click here. | |
| * If [[you do not have control over internal site content]], click here. | |
| \\ \\ | |
| |
| ===== 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. | |
| |
| |
| \\ | |
| |
| ^ [[http://www.zotero.org/support/dev/how_to_write_a_zotero_translator_2nd_edition|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 || | |
| | |
| |
| *Table of Contents | |
| * [[dev/How to Write a Zotero Translator, 2nd Edition/Chapter 1|Chapter 1: Introduction]] | |
| * [[dev/How to Write a Zotero Translator, 2nd Edition/Chapter 2|Chapter 2: General Troubleshooting Guidelines]] | |
| * [[dev/How to Write a Zotero Translator, 2nd Edition/Chapter 3|Chapter 3: Required Software (all free)]] | |
| * [[dev/How to Write a Zotero Translator, 2nd Edition/Chapter 4|Chapter 4: The DOM & HTML]] | |
| * [[dev/How to Write a Zotero Translator, 2nd Edition/Chapter 5|Chapter 5: XPaths (Directions)]] | |
| * [[dev/How to Write a Zotero Translator, 2nd Edition/Chapter 6|Chapter 6: JavaScript Basics & Variables]] | |
| * [[dev/How to Write a Zotero Translator, 2nd Edition/Chapter 7|Chapter 7: JavaScript Methods & Math]] | |
| * [[dev/How to Write a Zotero Translator, 2nd Edition/Chapter 8|Chapter 8: JavaScript If Statements]] | |
| * [[dev/How to Write a Zotero Translator, 2nd Edition/Chapter 9|Chapter 9: JavaScript Loops]] | |
| * [[dev/How to Write a Zotero Translator, 2nd Edition/Chapter 10|Chapter 10: JavaScript Functions]] | |
| * [[dev/How to Write a Zotero Translator, 2nd Edition/Chapter 11|Chapter 11: XPath Objects (Containers)]] | |
| * [[dev/How to Write a Zotero Translator, 2nd Edition/Chapter 12|Chapter 12: Regular Expressions]] | |
| * [[dev/How to Write a Zotero Translator, 2nd Edition/Chapter 13|Chapter 13: Scaffold Metadata Tab]] | |
| * [[dev/How to Write a Zotero Translator, 2nd Edition/Chapter 14|Chapter 14: Scaffold DetectWeb Tab]] | |
| * [[dev/How to Write a Zotero Translator, 2nd Edition/Chapter 15|Chapter 15: Scraping the Search Results Page: doWeb Function]] | |
| * [[dev/How to Write a Zotero Translator, 2nd Edition/Chapter 16|Chapter 16: Scraping the Individual Entry Page: Scrape Function]] | |
| * [[dev/How to Write a Zotero Translator, 2nd Edition/Chapter 17|Chapter 17: Common Problems when Scraping an Individual Entry Page]] | |
| |
| \\ This tutorial is an adaptation of '[[http://niche-canada.org/zotero-guide|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. | |
| |
| \\ | |
| |
| |
| ^ [[dev/translator_framework|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. || | |
| |
| ^ [[dev/translators|Translator structure]] ^^ | |
| | Documentation on the structure and metadata of translators || | |
| |
| ^ [[dev/translators|Translator coding]] ^^ | |
| | Documentation on the techniques and available functions for translators || | |
| |
| ==== More Resources ==== | |
| |
| * How to Build a Translator Videos | |
Upgrade Storage