User:Dudemanfellabra/AddCommonsCatLinks

This script is used to add images from Wikimedia Commons and/or links to Commons categories to certain lists of monuments. A full list of monument registers supported by the script can be found below.

How to use it
Anyone can use this script by adding or on other language versions by adding

to the bottom of their personal JavaScript page. The script generates a button at the top of supported monument lists which reads "Check Commons for images and categories" (or the corresponding phrase in other supported languages). When clicked, the script extracts the unique IDs of the sites in the list and checks Commons for categories and images that have been identified with that same ID. If a match is found, the script prompts the user to choose to add the matched images and/or categories or elect not to add anything. Upon reaching the bottom of the list, the script automatically edits the list to include the chosen images/categories if the user chose to add any.

How it works
Every time the user visits a new page, the script queries the wikitext of that page and determines if a supported row template (see below) is transcluded therein. If one of these row templates is found, the button is placed at the top of the page; if not, the script exits itself. When the user clicks the button, the wikitext is parsed to extract all the rows and then cycles through them, querying Commons for matches to the unique ID specified in each row template one by one.

Row templates
For each of the supported registers listed below, there is a row template used to create the tables found in the list-articles on which this button is added. For example, lists of sites on the US National Register of Historic Places use the NRHP row template to create each row in the tables. In the coding of this template, a parameter for a unique alphanumeric ID that identifies the site on that row is included (for the US NRHP, it is ########). This ID is used to add the site to the monuments database on Commons, allowing this script to recognize it. A good place to look for these row templates is Category:Monument list templates, although not all of the members of this category are supported by the script, and some supported templates may not be in this category.

Besides the unique identifier, it is also necessary that the row template adds the CSS  to the row so that the script can recognize it. If this class is not present, the script will throw an error and exit itself.

Commons templates
The row templates identify the sites on the English Wikipedia, but other templates are needed to identify the images and categories on Commons. These templates can be found in commons:Category:Monument templates, though, again, not all of these templates are supported and some that are supported may not be in this category. These templates can be added to categories and files on Commons to mark them as being related to sites on their respective monument register. This is done by adding them to a category with the sortkey equal to the unique ID for that site. This script then queries the members of that category to find matches here. For example, any file or category on which commons:Template:NRHP is transcluded (along with a unique ID) is added to commons:Category:National Register of Historic Places with known IDs, in which this script then looks for matches. If the ID of a file/category on Commons matches the ID of a row template on a page here, the script suggests that file/category for inclusion here. It's that simple!

Other suggested matches
In addition to strict matches, i.e. when the ID of a file/category matches the ID of a row template, the script also makes suggestions in situations where files may not actually be tagged with a Commons template. If, for instance, a row in a list has a commons category specified when the script encounters it but does not include an image, the script will suggest that the user add an image that is in the pre-existing category. This is also the case if a row template has neither an image nor a Commons category when the script encounters it and the script finds a matching category but no matching images. In this case, the script suggests the images in the newly matched category for addition to the template. Of course, these are just suggestions and may not be actual matches since they have not been tagged on Commons definitively stating that they are images of this site, but the suggestions are often times accurate. If the suggested images (or even the strict matches) are not of the site in question or are not in the user's opinion of sufficient quality, there is always the option to forego adding an image or category to a row.

Bot output
Though this script can be run on any supported list, User:ErfgoedBot is instrumental in keeping up the Commons monuments database mentioned above and has some very helpful output that can be used to pinpoint where images and categories that have been identified on Commons need to be added here. An example output is WikiProject National Register of Historic Places/Missing commons category links, which lists articles on which this script can be used to add links to Commons categories related to sites on the US NRHP. When there is a bot output available for a given register, it is linked in the supported registers table below.

Supported registers
The following table shows an extensive list of the monument registers on the English Wikipedia supported by this template, along with the relevant templates and categories this script uses. See below for monument registers supported on other language Wikipedias.

Other language Wikipedias
This script also supports lists on other language Wikipedias and is constantly expanding that support. While it may be possible to edit a list on a non-English Wikipedia, the GUI may or may not be displayed in that language. If the GUI has not yet been translated, the script will default to English, as will the edit summary (though the parameters added to the wikitext will be in the native language). If you can help translate the GUI into another language, please leave me a message at my talk page with the section title "I can help translate the CommonsCat script into LANGUAGE!"

A full list of supported registers on non-English Wikipedias is included below, sorted by the ISO 639 language code for that language (e.g. German's code is "de"). Click [show] next to the relevant language to display the list.

GUI has  been translated.

GUI has  been translated.

GUI has  been translated.

GUI has  been translated.

GUI  been translated.

GUI has  been translated.

GUI  been translated.

GUI  been translated.

GUI has  been translated.

GUI has  been translated.

GUI has  been translated.

GUI has  been translated.

GUI has  been translated.

GUI has  been translated.

GUI has  been translated.

GUI has  been translated.

GUI has  been translated.

GUI has  been translated.

GUI has  been translated.

GUI has  been translated.

GUI has  been translated.

GUI has  been translated.

GUI has  been translated.

GUI has  been translated.

GUI has  been translated.

GUI has  been translated.

GUI has  been translated.

Adding support for new registers/languages
In order to add support for new registers, the entire framework–row template, Commons template, and ID category–must be set up for the register. In addition to making this script more useful, converting existing lists of sites on heritage registers around the world into this format will improve the database on Commons as well and will be very useful for Wiki Loves Monuments, an annual international photo drive in which thousands of images of monuments are added to Commons. Support for any new registers which have been converted to this format can easily be added to the script by contacting User:Dudemanfellabra.

Support for registers on other language Wikipedias does not require anything more than registers on the English Wikipedia; however, if you want the GUI/edit summary to be displayed in the local language, it must first be translated from English. There are several strings that are displayed by the GUI, all of which must be translated before the language can be supported. The strings are shown below with their English versions and notes on when they are used when necessary as guidance for translation. If you are inclined to do so, translate the strings below and copy them to my talk page. I will add support for them as soon as possible.

 // The strings "ROWTEMPLATE", "NAME", "CATNAME", etc. should not be translated but can be moved around for better grammar. // These strings will be replaced by the relevant items during output.

// text to be displayed in the button you click to start the script "ButtonText":"Check Commons for images and categories", "ImageOnlyText":"Check Commons for images only", // Error at the beginning of the script to catch templates that don't include the correct CSS class "RowMismatch":"Row mismatch! This is probably due to an incorrectly formatted row template. All row templates must include class='vcard' in order for this script to identify them. If does include class='vcard', please let me know at en:User_talk:Dudemanfellabra, and I will try to resolve the problem. The script will now exit itself. Sorry!", // Similar error but for templates verified to have class='vcard' "MalformedRow":"Row mismatch! This is probably due to an incorrectly formatted row template in the wikicode, e.g. a missing }} or a misplaced HTML comment. If you cannot find the error on this page or believe it is due to something else, please let me know at :en:User_talk:Dudemanfellabra, and I will try to resolve the problem. The script will now exit itself. Sorry!", // self-explanatory "CheckingMatches":"Checking for matches...", "EditSummary":"Semi-automated addition of image(s) and/or commonscat link(s) to monument list", "NoneFound":"No matches found or selected. Script exited.", "Found":"Matches found!", "Invalid":"The existing image and/or category cannot be found on Commons. Selecting a match here will replace the existing one(s). If you do not want to replace anything, choose Do not add any category/image.", "FollowingImages":"NAME matches the following images:", // asking to select either a matched image or a category; shouldn't include the words for "image" or "category" "SelectOne":"Select one to add:", "DontAddImage":"Do not add any image", "OtherSuggested":"Other suggested images for NAME from matched or existing categories:", "Suggested":"Suggested images for NAME from matched or existing categories:", // included with each suggested image showing which category it is a member of       "From":"from CATNAME", "FollowingCats":"NAME matches the following categories:", "DontAddCat":"Do not add any category", // shown on the buttons "SelectButton":"Continue", "SaveButton":"Save progress and exit", "Done":"Done! Editing page...", "SuccessfulEdit":"Done! Refresh the page to see the result!", "FailedEdit":"The edit query returned an error.", "LeavePage":"Are you sure you want to leave the page? All categories/files that you have added will not be saved!"

Troubleshooting
The following are known issues with the script that have not yet been addressed or are not technically feasible due to limitations of Wikimedia software:
 * If a single Commons template is transcluded multiple times on the same category/image because, e.g., multiple parts of the site in question are designated independently, the script can only detect the last one transcluded on the page. This is due to the limitation that a page in a category cannot have more than one sortkey (explained above), so each successive template simply overwrites the existing sortkey, making it invisible to this script. Note: This only applies to sites where a single template is transcluded multiple times; if a site is designated on two different registers marked by two different templates which include the category/image in two different categories, the script should detect each designation individually.


 * Sometimes the script will suggest an image/category when there is already one there, falsely claiming that the existing image/category does not in fact exist. For images, this is usually because the image itself is not stored on Commons but on the local language's Wikipedia. Choosing to add a matched/suggested image in this case will replace the existing image with the one on Commons. For categories, this means that the commonscat previously specified in the template cannot be found on Commons (likely a typo in the row template?). Choosing a matched/suggested category will replace the existing one. This also can happen if there is a linebreak in front of the file or category name, in which case adding the suggested image will break the template output.


 * The code tries hard to preserve the original formatting of the wikicode for the row template. If the row template is found to have each parameter on its own newline, the script will add a new line for the image/commonscat parameter; if the wikicode does not include newlines but rather just one big block of code, the script will add the parameter inline without forcing a linebreak. That said, the script is not so good at preserving spacing and other aesthetic formatting. Many times editors like to include spaces between parameter names and the equals sign (=) or pipes (|) for other parameters so the wikicode is more readable. This script is not intelligent enough (yet) to known how many spaces are needed to preserve this formatting, but small improvements are always being made. For now, it may be in the user's best interest to manually review the wikicode after using the script to preserve any spacing and avoid angering other editors.

If any errors or undesired behaviors apart from those listed above are encountered while using this script, please direct questions to User:Dudemanfellabra, the script's creator.