Translation UX/Development plan

This is the development plan for the translation user interface project. It's published on this wiki for the sake of transparency; its audience are the project team members, so it's assumed that the reader has read the design documents and specifications.

Introduction
After the Universal Language Selector, Translate UX is the second major development project of the Wikimedia Language Engineering team which involves design and user testing efforts. Pau Giner and Arun Ganesh have come up with a new designs for three parts of the translator’s workflow: signup, translation and search. I will call those tracks from now on. Each track will be described in their section below.

The three tracks are to some extent independent, but there are dependencies. For example the simplified translation editor for new translators should not be deployed before we have the full version of the editor ready. Also, removing the display of message keys from the message list might affect some uses cases, which could be covered by the search track. For this reason it makes sense to start with the translation track and start doing the other tracks alongside when there is time and need for them.

For each of those tracks we need to develop new features and adapt existing code. Unlike the search, signup and translation workflows already exist and hundreds of users are already using them.

In principle each track could be developed in parallel. Each milestone should fit in a two-week sprint.

The Translate UX development does not lack challenges and they are mostly different from those in the Universal Language Selector project.

Challenges

 * Existing codebase. Translate, where the developments will concentrate, is a mature extension. It’s been developed for many years and contains many lines of code, mostly in PHP. Unlike in the ULS, we are not starting from scratch and there are many limitations set by the existing design. Some of them we can fix, some of them not. This will stress-test the internal interfaces.
 * Release often, release good. Translate extension code is used by WMF, which will take a snapshot of Translate every two weeks. The language support extension bundle will take snapshots every month once it starts. We have to be extra careful and ensure nothing breaks while we refactor and add new code. This makes it important to have tests (PHPUnit for PHP, QUnit for JavaScript and possibly Selenium for workflows).
 * Existing users. We have a lot of existing users. While the feedback in user testing has been positive, we need to maintain old and new feature sets simultaneously, temporarily complicating the codebase. Only once features are solid enough to launch standalone, we can drop support for old code – this should be done as quickly as possible, though. Using dark launches or AB-testing may be necessary to gather feedback during development. A gradual deployment can consist on several of these stages: dogfooding (internal use), ask for invitation (feature is announced and users can request to test it getting immediate access), show the new with revert option (users can switch to the old), and just the new.
 * Backwards compatibility. We should strive to maintain backwards compatibility when changing existing Translate interfaces or APIs. This requirement can be relaxed on a case-by-case basis.
 * MediaWiki. We might hit limitations of the MediaWiki platform. For example customizing the signup process is extremely inconvenient and may necessitate complicated core changes and also complicate compatibility requirements with stable MediaWiki releases.
 * Do not melt the schedule. Each one of the three parts matches the ULS project in size, which has taken months to develop. It is likely that we need to prioritize heavily and make some hard choices of what to drop.
 * Complexity. The workflows in Translate are much broader than in ULS, which can lead to very high implementation complexity, which again is major source of bugs. Where possible, different screens with fewer features can be used to reduce complexity and optimize particular workflows.
 * Sprinting up Niagara Falls. Use the "just enough" agile directive, "release early, release often" and "incremental improvements". We are not a big team and we must seamlessly work together. We cannot wait until the water stops flowing, but deliver something every two weeks and release something not ready, but usable, many times during the project.

Sign-up track
The new design has multiple goals:


 * Start early. Translate as soon as possible.
 * Start easy. Guide and simplify first translations.

There are some technical risks in the implementation and limitations of reusability:


 * Design is not easily adaptable to other sites
 * Sign-up process in MediaWiki is not easily customizable
 * Sign-up process needs spam protection and other security measures
 * Need to implement sandboxing for unconfirmed translators

Milestone SG1: poking with a stick
The first step is to figure out what is it exactly that we are going to do. What data and features do we need? What issues there are that might prevent implementing the original design? What help do we need outside of our team? How do we split the work into manageable pieces? This document is all about that, so continue reading.

User stories: (2 points)
 * As a product manager I have a technical plan, so that I can start including stories in our sprints.

Acceptance criteria:
 * 1) This document

Milestone SG2: new frontpage
… … ...

User stories:
 * As a translator I immediately get the idea what I can do on this website.

Acceptance criteria:
 * 1) TBD

Milestone SG3: sandbox

 * ”tule tule hyvä kakku, älä tule paha kakku”

We can drop many spam protection measures from the user signup process by implementing a sandbox. While in a sandbox users don’t have write access to anything (let’s call this closed sandbox). All the sandbox user’s actions are recorded in a dedicated place, so that we can easily get rid of spam accounts.

The plan is to register users in the users table and add them to special user group sandboxed. We will implement hooks that prevent any write actions by these users. User acceptance is just a removal of the user from the special user group and adding the translator group.

We can use this special group to send reminder emails for translators and do automatic purging of unaccepted accounts based on age.

User stories:
 * Prerequisite for later milestones.

Acceptance criteria:
 * 1) Users in the special group cannot do any write actions
 * 2) Documented, tested and reviewed utility class and WebAPI module:
 * 3) Creating sandboxed users
 * 4) Removing sandboxed users
 * 5) Maintenance script to purge by age
 * 6) Maintenance script to send reminders
 * 7) Drafted reminder emails for i18n

Milestone SG4: signup dialog
Widget is needed to get the signup process started. I believe we can do this purely in JavaScript to simplify the implementation.
 * The interaction with backend happens through API module written in previous milestone.
 * I’m not saying that it is necessary easier to do it via JavaScript, but this should avoid problems keeping backend HMTL generation and frontend JavaScript in sync and nice-and-tidy. It may introduce problems with placing the stuff in the page, but should allow smoother continuation to the next dialog.

User stories:
 * As a to-be translator I only need to fill as little information as possible to get into business.

Acceptance criteria:
 * 1) Language skill selection with suggestions
 * 2) Mandatory info fields: username (with availability checking), email and password
 * 3) Interacts with the backend to create sandboxed users

Milestone SG5: collection of simple messages for signup
We need a list of simplified messages, which have good documentation and suggestions. It should be decided whether we need to collect list of suggestions as well, for example if we want to add some bad suggestions to check whether they mindlessly use them.

User stories:
 * Requirement for the simplified translation dialog

Acceptance criteria:
 * 1) List of about 100 messages (should be based on messages available in twn)
 * 2) Different kind of messages (short, a bit longer)
 * 3) Messages should have message documentation (can be fetched from live data)
 * 4) With good and bad translation suggestions (existing translations are assumed to be good, but we don’t want to always present them, nor are they always available)

Milestone SG6: simplified translation dialog
Gentle introduction to translators. Contains explanatory texts and some elements are not included.

User stories:
 * As a new translator, I can learn the translation editor (and process) step by step so that I don’t get overwhelmed and run away.

Acceptance criteria:
 * 1) Layout as proposed.Image/Link to mockup
 * 2) Use data from the previous milestone
 * 3) Only closed sandbox is in scope (translation of arbitrary messages not included)
 * 4) Limit reached notification Image/Link to mockup
 * 5) Emails and screens related to being approved

Milestone SG7: translator approval page
The admins need an easy way to approve new translators. A dedicated page seems to be the path of least resistance.

User stories:
 * As a translation administrator I can easily accept new translators, because I can inspect their contributions.

Acceptance criteria:
 * 1) List users ordered by importance (for example number of translations made or signup date)
 * 2) Allow to compare their translations to existing translations
 * 3) Flag if bad suggestions were used
 * 4) Show whether email is confirmed
 * 5) Few click promotion or decline
 * 6) (Way to send reminder)

Milestone SG8: tracking
We want to know how well the new signup process works. Specific metrics to be defined. We need to observe:
 * Information about how the process is followed (e.g., number of new users failing the example translation, reaching the limit, discarded as spammers)
 * Overall impact (number of new users, users that remain active translators after a time).
 * Metrics of group 2 should be observed before and after deploying, to compare current and new system effects.

User stories:
 * As a designer I can see how well the implementation works so that I can point out issues and suggest enhancements.

Acceptance criteria:
 * 1) Came up with the wanted metrics
 * 2) Implemented the metrics

Translation track
The new design has multiple goals:
 * Fluency of translation. Support the common flow.
 * Clarity of information. Show the needed information.
 * Gradual conversion. Support evolution in expertise level.

This track has lots of components which can be tested simultaneously with the old implementation: message list, message editor, proofreading view.

Risks, limitations and special notes:
 * Large existing code base and feature set. Users are passionate of every single intended and unintended feature.
 * Need to collect more information to implement some features.
 * Tailored user experience based on collected information.
 * Need to care about performance in backend. We need to ensure our data collection and retrieval is fast enough.
 * Need to care about performance in the frontend.
 * Some possible high-hanging fruits that are likely to get dropped: threaded discussion and vertical diffs.

Milestone TR1: poking with a stick
The first step is to figure out what is it exactly that we are going to do. What data and features we need? What issues there are that might prevent implementing the original design? What help do we need outside of our team? How do we split the work into manageable pieces?

User stories:
 * As a product manager I have a technical plan, so that I can start including stories in our sprints.

Acceptance criteria:
 * 1) This document

Milestone TR2: new face for message list
Let’s begin by changing the current message list display. We will update the color scheme, remove message key names, add an edit link and add a label for fuzzy messages. This should work alongside with the old table and be accessible by user preference or request parameter.

User stories:
 * As an user I can experiment and try a feature rich and attractive translation interface, where the translation strings are listed for easy translation and navigation.

Acceptance criteria:
 * 1) One message per line with truncation
 * 2) Fuzzy indicator
 * 3) Edit button
 * 4) Color scheme as proposed
 * 5) No message key displayed in the list
 * 6) Way to beta-test this new layout for users
 * 7) I18ned,  works in RTL

Milestone TR3: progressbar
This little bar we will be needed in multiple places: group lists, message lists, different full-page views etc. It makes sense to make it as a reusable component.

User stories:
 * As a developer I can easily add a progressbar to my layout, so that I can do more other stuff.

Acceptance criteria:
 * 1) Flexible, documented and tested PHP class
 * 2) Style configurable via CSS or images
 * 3) Possibility to choose which states to include (untranslated, outdated, translated, proofread)
 * 4) Used by the message list implemented in TR2

Milestone TR4: project selector
The message list needs a new project selector. In this milestone we implement a widget to select project(s). It does not include integration to the message list. The project list works similar to language selector: keep track of recent or favorite projects, have search and have full list of projects. We need to start storing project icons in a machine accessible way.

User stories:
 * As a user I can quickly switch between projects.
 * As a developer I can integrate this widget to my layouts.

Acceptance criteria:
 * 1) Flexible, documented and tested widget with PHP/JS APIs
 * 2) I18ned, works in RTL
 * 3) Has search
 * 4) Can show favorite or recent projects
 * 5) Data collection of last used  projects
 * 6) Project icons

Milestone TR5: selector integration
Now that we have group selector, we can integrate it to message list. Let’s also add a language selector, which is expected to come from the Universal Language Selector. Also any work needed to make the task related selectors as per design.

User stories:
 * As a user I can finally change easily between projects and languages.

Acceptance criteria:
 * 1) Multi-level project selector
 * 2) Language selector
 * 3) Restyle of other selectors

Milestone TR6: message list tracking
Now that we have mostly completed the new message list implementation, it’s about time we integrate user tracking for it. We need to use clicktracking (or alternative) to record user actions. It might make sense to also add tracking for the old interface for comparison.

User stories:
 * As a designer I can insight how the implementation works and can point out issues and enhancements.
 * As a user I can get better interface by using it.

Acceptance criteria:
 * 1) List of trackable actions and user metadata
 * 2) Trackpoints in the code

Milestone TR7: the new message editor is born
After the message list, the message editor is the next big task. It doesn’t contain major changes in the contents, mostly just a restyling and rearranging of the information. The new editor version should be testable alongside with the old editor. There should be a user preference or another way to activate it.

The restyling of the translation helper boxes is not part of this story, though the relevant CSS styles and HTML layouts should be available.

User stories:

Acceptance criteria:
 * 1) Collapsible split view
 * 2) Most message helpers move to right hand side
 * 3) Use the proposed layout and colors where possible
 * 4) Message key
 * 5) Button styling
 * 6) Ask question

Milestone TR8: message editor in puberty
Now that we have the basic layout with stuff approximately in the correct place, we can start implementing the more detailed changes.

User stories:

Acceptance criteria:
 * 1) New shortcuts for actions (ctrl+s, ctrl+d etc...)
 * 2) “This message needs translation in language X” in the message list
 * 3) Display of message definition
 * 4) Display of warnings (outdated, checkers)
 * 5) Display of diffs
 * 6) Unsaved translation shown in message table
 * 7) Collection of skipped translations

Milestone TR9: message editor with reformatted suggestions
The remaining task is to change the display of various suggestions. This also needs some code changes. To make shortcuts discoverable it was suggested to highlight the numbers (or letters) when Ctrl key is pressed.

User stories:

Acceptance criteria:
 * 1) Display of message documentation with edit link as per design
 * 2) Translation memory and machine translation suggestions (collapsing the dots and with link to show them)
 * 3) Display of In other languages
 * 4) Shortcuts and links for suggestions to use them in translation
 * 5) Any other tweaks needed to make the layout work for varying amount of content

Milestone TR10: tracking
As with the message list, we probably want to see how the new editor fares against the current editor. Use clicktracking or other relevant methods to do this. …

Milestone TR11: full-page and proofreading view
For page translation. Just do it. Page translation generally has less info (suggestions, warnings, documentation) and longer texts. Less chrome and more space for seeing the context.

User stories:
 * As a translator I can see the approximate context of the messages so that I can use that information when translating.

Acceptance criteria:
 * 1) Way to activat e full-page view in message list
 * 2) Original, compare and translated tabs
 * 3) Progress bar
 * 4) Navis to jump to next message
 * 5) Task and language selector
 * 6) Compact indicators
 * 7) Proofreading mode

Milestone TR12: tracking
Is this needed?

Search track
The new design improves has multiple goals:


 * Avoid to think in advance. Avoid the need for users to understand the information structure to fix a typo.
 * Support quick connections. Quick access to actions and related information.

There are also some risks and limitations:
 * Limited by features in Solr
 * We might need to replace our existing Solr schema
 * Should solicit feedback from search experts like Oren

Milestone SR1: poking with a stick
The first step is to figure out what is it exactly that we are going to do. What data and features do we need? What issues are there that might prevent implementing the original design? What help do we need outside of our team? How do we split the work into manageable pieces?

User stories:
 * As a product manager I have a technical plan, so that I can start including stories in our sprints.

Acceptance criteria:
 * 1) This document

Milestone SR2: mapping out
We need to figure out the schema for Solr. Can we extend the existing schema or do we need to develop a new one? What are the limitations and how to work around them?

User stories:
 * As a developer I know what information I need to fetch and submit to the search system, so that I can write code for that.

Acceptance criteria:
 * 1) Draft schema which describes what data is needed and in which format
 * 2) Short description how to handle updates and deletions of data

Milestone SR3: feed it
This task entails writing the code that updates the search system with translation data. This includes initial bootstrapping and updating, and deleting based on changes in the wiki. This milestone is deployable, which enables silent data gathering and creation of real search databases for measurements.

User stories:

Acceptance criteria:
 * 1) Code is unit tested and peer reviewed
 * 2) Script that imports current wiki content to search system
 * 3) Relevant changes*FIXME:SR2 in the wiki are reflected in the search system
 * 4) Documented interfaces (PHP code) how to search and update the search system

Milestone SR4: use it
Implement a simple search interface using a new special page. It allows full-text searching with simple listing of search results with paging. This can be done with mock or real data, in latter case it depends on SR3.

User stories:
 * As a user I can use a simple search interface so that I can find problematic translations and update them easily and provide feedback for further development.

Acceptance criteria:
 * 1) Code is unit-tested and peer-reviewed to reasonable extent
 * 2) New special page: Special:TranslationSearch
 * 3) The special page has input for fulltext search
 * 4) Search will display matching results (the page content)
 * 5) Search results are limited to one page
 * 6) Translation editor is reachable by one click

Milestone SR5: facets
Time to implement some filtering. Let’s start with language and project facets, continued by translation state (pending research).

Facet in short: facet is a classification that applies to search results. For example if you search for cars, you can use facets like color, number of doors or manufacturer to narrow your search. Each facet has limited number of alternatives presented to the user. The number of results in each possible option is displayed before the user makes a choice.

User stories:
 * As a user I can narrow my search results so that I can more easily find the messages I am looking for.

Acceptance criteria:
 * 1) Language facet in the left-hand side per design mockup
 * 2) Project facet in the left-hand side per design mockup

Milestone SR6: with tracking
To get more information for open questions and further tweaks, we should be able to track search queries and the search results. For example whether we need to implement faceting of the message state (untranslated, outdated, translated). For this we can add server side logging of search queries and number of search results. If necessary and possible, we can also use clicktracking to augment our data with user actions.

User stories:
 * As a designer I can understand better how the implemented design works so that I can point out issues and enhancements.

Acceptance criteria:
 * 1) Simple logging framework
 * 2) It stores the search term, total number of results, results per facets

Milestone SR7: polish
Make the search listing nicer as in the design. Collapse repeating messages and provide links to show them.

User stories:
 * As a user I don’t need to scan long lists of repeating messages to find what I’m looking for.

Acceptance criteria:
 * 1) Collapsing of similar/identical search results
 * 2) Links to expand the hidden results

Milestone SR8: with edit button
Integrate the editor developed in the TR# milestone with the search results.

User stories:
 * As a user willing to change several similar translations/strings, I don’t need to leave the search results to update translations, so that I don’t lose track of what I’ve already handled.

Acceptance criteria:
 * 1) Way to activate editor
 * 2) Editor has all the usual features
 * 3) Translation can be updated or added