Web2Cit/Docs/Editing

Web2Cit translation is based on a series of per-website configuration files. These files are collaboratively maintained by the Web2Cit community.

The currently recommended method to edit these files is via the JSON editor, which provides a user-friendly form interface to edit each of these files individually.

An improved unified editor, integrating the editing workflow into a single sidebar interface, has been proposed.

Manually editing configuration files is also possible but discouraged. You may read more about this in the Storage documentation page.

JSON editor

Using the JSON editor is the currently recommended way to edit Web2Cit configuration files. This editor provides a user-friendly form interface that guides Web2Cit collaborators with editing individual configuration files.

How to use

Using the JSON editor usually comprises three steps:

1. opening the configuration file with the editor,
2. using the editor to edit the file, and
3. saving the file back to the storage.

Open

Click any of the "edit" links on a translation summary page to open the corresponding configuration file on the JSON editor.

The easiest way to open one of Web2Cit configuration files with the JSON editor is via one of Web2Cit server's translation summary pages. Remember you can access these pages by either entering a target URL on the server's homepage, or by clicking the "Web2Cit" link on the "Add a citation" dialog on Wikipedia.

From one of these translation summary pages:

• Click the "edit" link next to a "translation subgroup" heading to edit the patterns configuration file, defining URL path patterns.
• Click the "edit" link next to a "translation output" heading to edit the templates configuration file, defining translation templates.
• Click the "edit" link next to a "expected output" heading to edit the tests configuration file, defining translation tests.

This will pull the latest version of the corresponding configuration file from the Web2Cit storage on Meta-Wiki, and open it on the JSON editor.

Edit

A screenshot of the JSON editor's form-like interface being used to edit a sample templates configuration file.

The JSON editor provides a form-like interface to guide you through the process of editing Web2Cit configuration files. The form will differ depending on the type of configuration file you are editing (i.e., templates, tests or patterns configuration file).

Check the corresponding Tests, Templates and Patterns documentation if you need further information about each of these configurations.

Remember that other Web2Cit collaborators may have edited these files before you! Use the JSON editor form to check what they have done before making your changes.

Save

To save your changes back to the Web2Cit storage:

1. On the JSON editor, scroll down to the "Save as" section and click on "Review changes and save". This will open your changes on the Meta-Wiki editor.
2. On the Meta-Wiki editor, scroll down to the bottom, enter an "Edit summary" and click on "Publish changes", as you would normally do with other wiki pages. This will make your changes public and available to Web2Cit.

Sandbox storage

By default, your changes will be saved to the file pulled from the Web2Cit storage initially. Alternatively, you may save changes to a personal sandbox storage to try configurations without affecting all Web2Cit users. To do so, prepend User:<YourUserName>/ at the beginning of the save-to path on the "Save as" section of the JSON editor (replace <YourUserName> with your Wikimedia username). Read the Web2Cit server documentation to find out how to indicate the Web2Cit server to use configuration files from your personal sandbox storage instead.

Need help?

If you need help with using the JSON editor to edit Web2Cit configuration files, you may ask on the discussion page, or open an issue on Wikimedia's Phabricator under the web2cit-json-editor tag.

Technical information

Read the JSON editor page for technical documentation.

Integrated editor

Integrated editor proposal

The integrated editor has not been fully developed yet. The currently available pre-alpha version is very premature and has been published solely to provide an idea of what it could look like in the future.

The Web2Cit integrated editor is a proposed editor integrating the whole Web2Cit editing workflow into a single interface, while providing real-time translation result previews before saving changes to all Web2Cit users.

This integrated editor would be injected as a sidebar on the webpages from the domain one would like to tweak configurations for, via a bookmarklet or browser extension. It may also be available as a standalone editor on a separate website.

A preliminary mockup was made available at the beginning of the Web2Cit project, and a walk through it is available on YouTube here.

Bookmarklet

A screenshot of a very early pre-alpha version of the integrated editor injected as a sidebar on a sample webpage.

You can try a very early pre-alpha version of the integrated editor by injecting it as a sidebar using a bookmarklet. Just create a bookmark on your browser's bookmark bar with the following URL:

javascript:(function(){var d=document,s=d.createElement('script');s.src='https://tools-static.wmflabs.org/web2cit/embed.js';d.body.appendChild(s);})();

To use it, just click on the bookmarklet while visiting the webpage you would like the editor to be injected on. Note that some sites with strict CSP policies may prevent you from injecting the sidebar.

This very early pre-alpha version does not support editing configuration files yet; just showing translation results.

Technical documentation

Technical documentation may be found at the Integrated editor page.

Domain aliases

From Web2Cit server v1.1, configuration file redirections are supported. These are useful for domain aliases; for example, if www.example.com is an alias of example.com, configuration files of the former can be redirected to those of the latter so the Web2Cit community does not have to maintain multiple copies of the same files.

Creating redirections from the JSON editor is not currently supported (see T320771).

To manually set a redirection:

1. On Meta-Wiki, open the configuration file that you would like to redirect elsewhere. For example, Web2Cit/data/com/example/www/templates.json. To avoid naming errors, you may use the JSON editor, following the steps under the How to use section above, skipping the Edit step.
2. Edit the configuration file manually, adding the following redirect code at the top of the page: #REDIRECT [[target]], where target is the redirection target. For example, Web2Cit/data/com/example/templates.json.