Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
dev:translators [2022/03/04 19:02] – Modernize instructions abejellinekdev:translators [2023/08/18 09:15] (current) – [Recommendations for Translator Authors] Add one advice about not modifying the live document. zoe
Line 102: Line 102:
 To submit a pull request, fork the [[https://github.com/zotero/translators|Zotero Translator GitHub repository]], commit your changes (i.e., adding or modifying translator files), and create a [[http://help.github.com/pull-requests/|pull request]]. You can use your Git client of choice, but for new users we recommend [[http://www.syntevo.com/smartgit/index.html|SmartGit]], which is free for non-commercial purposes. To submit a pull request, fork the [[https://github.com/zotero/translators|Zotero Translator GitHub repository]], commit your changes (i.e., adding or modifying translator files), and create a [[http://help.github.com/pull-requests/|pull request]]. You can use your Git client of choice, but for new users we recommend [[http://www.syntevo.com/smartgit/index.html|SmartGit]], which is free for non-commercial purposes.
  
-When you submit pull request on GitHub, your translator code will be reviewed, and you will receive comments from the Zotero developers or experienced volunteers. Once you've made any necessary changes, your translator will be added to the Zotero translator repository. +When you submit a pull request on GitHub, your translator code will be reviewed, and you will receive comments from the Zotero developers or experienced volunteers. Once you've made any necessary changes, your translator will be added to the Zotero translator repository. 
  
 ==== Licensing ==== ==== Licensing ====
Line 112: Line 112:
   - ''detectWeb'', ''detectImport'' and ''detectSearch'' should be coded to minimize the likelihood of the corresponding ''doWeb'', etc. function failing. Do your minimum required input checking the detect functions -- a failing ''do'' function will cause user-visible errors.   - ''detectWeb'', ''detectImport'' and ''detectSearch'' should be coded to minimize the likelihood of the corresponding ''doWeb'', etc. function failing. Do your minimum required input checking the detect functions -- a failing ''do'' function will cause user-visible errors.
   - Make detect functions lightweight-- they may be run on pages that a user is not even considering saving. Detect functions should not need to make additional HTTP requests. This obviously runs counter to the preceding point-- find a happy medium.   - Make detect functions lightweight-- they may be run on pages that a user is not even considering saving. Detect functions should not need to make additional HTTP requests. This obviously runs counter to the preceding point-- find a happy medium.
-  - Minimize HTTP requests. More HTTP requests slow down the user, cause undue load on servers, risk getting users rate-limited or blocked, and in general are bad.+  - When translating the web page in the browser, do not modify any part of its DOM. 
 +  - Minimize HTTP requests. More HTTP requests slow down the user, cause undue load on servers, risk getting the user rate-limited or blocked, and in general are bad.
   - Don't leak user data. HTTP requests should in general not be directed to 3rd-party hosts.   - Don't leak user data. HTTP requests should in general not be directed to 3rd-party hosts.
   - Document your code. If there are input data deficiencies and the translator is working around them, document the deficiencies. If there are specific types of pages that a web translator is for, provide example URLs and expected output.   - Document your code. If there are input data deficiencies and the translator is working around them, document the deficiencies. If there are specific types of pages that a web translator is for, provide example URLs and expected output.
   - Produce [[dev:translators:testing|translator tests]] when possible, covering the basic page types that the translator is designed to support.   - Produce [[dev:translators:testing|translator tests]] when possible, covering the basic page types that the translator is designed to support.
   - Run ESLint on your code before submitting it. Zotero provides an ESLint plugin for translator development. You can run it on your translator within a clone of the ''zotero/translators'' repository: <code>npm ci && npm run lint -- "Your Translator.js"</code>   - Run ESLint on your code before submitting it. Zotero provides an ESLint plugin for translator development. You can run it on your translator within a clone of the ''zotero/translators'' repository: <code>npm ci && npm run lint -- "Your Translator.js"</code>
dev/translators.1646438555.txt.gz · Last modified: 2022/03/04 19:02 by abejellinek