Annotations

Let's consider how we annotate content for translation on a multilingual wiki. This example is taken from mw:Help:Extension:Translate/Page_translation_example. We start with some article content:

Fréttinga is a small municipality in MungoLand, located on the BaMungo island.
It hosts a population of about 400 people. It has some agriculture and fishing.
Tourists like to visit it in the summer time.

== Services ==

It doesn't have many services. There is a shop, and a car ferry visits the island
from the mainland once a day.

The first step is to mark the annotated regions, which we do with explicit markup in the wikitext.

The translation UI then shows the translation regions:

The translator can then translate each of them:

Of course, this is Wikipedia, so the original article will quickly get changed.

The translator can update the translation units, as well as indicate whether the change was just a copy-edit (in which case the translation doesn’t need update) or needs further attention.  This notifies translators, who can then update the translations.

But let’s look again at our wikitext.  Even though we’re not encoding /all/ of the knowledge here in the wikitext – we’re storing the actual translations of these texts somewhere else – there’s still a lot of strange stuff cluttering up our article, which is often off-putting to editors.

This example isn’t unusual.  There are a lot of examples on our projects with information which is cumbersome to include inline in the wikitext:

• Translation regions from Translate extension
• Inline discussions
• Citations (especially citation regions)
• LanguageConverter rules -{...}-
• WikiSource (proof-reading, transcription regions)
• Maintenance tags {{citation needed}}

In addition there's other information the community would like to include with an article but are currently blocked on because the extra inline information would be too disruptive to “ordinary” editors:

• WikiSpeech pronunciations
• Fine-grained translation correspondences

There's a large list of use cases collected from the community at the Annotations session of the Wikimedia Developer Summit in 2017.

We are proposing a general annotation service to allow us to record all the information which doesn’t belong in wikitext.  Here are the important properties of annotated content on our projects:

• First, the annotation is generally transformative.  It’s an independent piece of content but with a relationship to the base. Both the source and the annotated content require independent maintenance.
• We wish the annotation to be decoupled from changes to the base text. The original source author or editor doesn’t need to update the annotated content in order to write or edit, in fact is likely unable to. Similarly, the annotation can be created or updated without changing the source or imposing on the source editor.
• It is associated with a specific revision of the base content, although that revision may not remain current long. This is in contrast to some annotation systems, which need to maintain fuzzy anchors to the source material because it may change unexpectedly. In our projects articles are versioned, so we can have stable anchors to a specific location in a specific revision. Of course the revision won't remain current forever, so...
• There is an explicit migration process to the latest revision.  We don’t assume the annotation will apply after edits have been made, although we can provide good tools to make it easy to migrate where possible. As with the translate extension, there is an explicit notion of a "fuzzy" annotation, which can be explicitly re-anchored to the current revision in a manual process done by a human.
• Display the latest revision by default, even if annotation migration is incomplete. As a matter of wiki culture our project has discovered that it’s best to make it very obvious when something needs to be fixed.  When an edit is made to a wiki, we generally make it visible immediately, so that if the edit is incorrect it will be similarly quickly noticed and fixed.  In our translation example example, if an edit invalidates a translation, the translated version typically reverts to the untranslated content, to draw attention to the fact that the translation annotation needs to be migrated (translation reviewed and updated).

Annotations should be transparent: the presence of annotated content should never prevent editors from being able to easily update the base content. There are many authors, many annotations, and many annotators.

What does editing annotated content look like?  At the top of this section we showed one example with the Translate extension, which used a separate editor for the annotated content (translations). But we can also look at the InlineComments extension for an idea of a more generic interface. Viewing and refining the annotation regions is done with a special mode in Visual Editor:

Annotations are anchored to a specific revision, and they can be specified as a range in either the wikitext source or in the HTML DOM; Parsoid allows mapping back and forth between these.

Just as we’re using VisualEditor to mark regions, I expect it will probably be useful to make a generic-but-extensible mechanism to edit annotation content alongside the source text.  This is a simple example from InlineComments:

Not every annotation type will use this simple form in the sidebar – the Translate extension uses a custom editor as we saw earlier – but providing a generic functionality of this sort will probably make it easier to develop new annotation types and provide some common user interface elements to make editing new annotation types easier to learn.

Next section: Visual Templates