Grants:Project/Rapid/SD0001/Twinkle localisation/Report

Report accepted

This report for a Rapid Grant approved in FY 2020-21 has been reviewed and accepted by the Wikimedia Foundation.

To read the approved grant submission describing the plan for this project, please visit Grants:Project/Rapid/SD0001/Twinkle localisation.
You may still comment on this report on its discussion page, or visit the discussion page to read the discussion about this report.
You are welcome to Email rapidgrants at wikimedia dot org at any time if you have questions or concerns about this report.

Goals

Did you meet your goals? Are you happy with how the project went? I feel that I met my goals and am happy with how the project went. To achieve localisation of Twinkle, as part of this project, the following work was done:

The twinkle-core repository was created. This repository is intended to be used as a library and is published on npm. API documentation is available on Toolforge. A proof of concept en-wp localisation which closely replicates the existing enwiki twinkle was created at twinkle-enwiki. It is deployed on the testwiki:. It improves upon the existing enwiki twinkle in many subtle ways, particularly maintainability, and I hope that we deploy and use it on enwiki some day.
The twinkle-starter repository has been created which serves as a template for creating Twinkle versions for different wikis. Detailed instructions for doing this are on the README page.
One of the goals of the project was to improve testing. The mock-mediawiki repository has been created for providing a set of mocks for the MediaWiki interface to be used in unit testing gadgets. Until now, gadgets have generally used partial adhoc mocking. Writing code using ES modules with a module bundler to pack the assets also makes it easier than ever before to do live testing on production sites (using webpack-dev-server).
Twinkle-core now uses a modern JS toolchain (unlike the earlier version) which I believe would be crucial to attracting new contributors now and in the future. This doesn't compromise on browser support. Even IE 11 is still supported.
Another of the goals of the project was to have the project ready and deploy it on a production wiki. This unfortunately has not happened yet. In hindsight, I think this was a rather lofty ambition given the timeframe (originally 2 months was requested; though total project duration came to be 4-5 months, I was active only for about 2-3 months). The scale of the project was immense for a Rapid Grant – over 26000 lines of code (not counting the code from open PRs which also had to be taken into account). To put that into perspective, a previous Rapid Grant was on improving ProveIt gadget – which is a single file with 1500 lines of code.

Also getting it deployed outside En-WP naturally requires significant time and commitment from a community member of the wiki – which is not reasonable to expect from someone within the grant period. I do intend to continue working on twinkle-core to smooth out the few remaining places that are still using hardcoded messages or are specific to en-wp, as well as fix bugs as and when discovered.

Outcome

Please report on your original project targets. Please be sure to review and provide metrics required for Rapid Grants.

Target outcome	Achieved outcome	Explanation
Establishing a robust setup for localising Twinkle to wikis that follow widely different workflows for deletion/tagging etc	Done.	Twinkle-core uses a class for each module. Methods whose functionality is expected to be same across wikis are implemented in the core itself. But just in case that still need to be tweaked, that can be done by overriding the method from an inherited class. Wiki-specific functionality is left for localisers to provide - again by implementing methods (runtime polymorphism) or overriding existing sample implementations.
Adding i18n for messages (strings) used in Twinkle	Done.	i18n libraries on the MediaWiki landscape generally all use the user language, whereas Twinkle needs to use content language messages in many places. So localising strings was its own challenge. MediaWiki modules like mw.msg, mediawiki.jQueryMsg and jquery.i18n were all unsuitable for use because they're intended for use with user language. In the end, I used a lightly customised fork of the banana-i18n library. A project on Transatewiki.net is on track to be set up for Twinkle-core (phab:T278627).
Documenting the process for creating per-project localisations	Done.	Twinkle-starter repo has a detailed README that provides the overview. Twinkle-core library has HTML documentation automatically generated from tsdoc comments in the source code. This provides guidance on configuring individual modules.
Building a modern replacement for Morebits (core library used for API actions)	Not done directly.	Lots of changes were made to Morebits by another contributor due to which any attempt to change Morebits in a significant way would have been disrupted. Nevertheless, the key components of the library have been modernised with respect to their external interface in twinkle-core (see the Api, Page and User classes – they wrap over the corresponding Morebits classes).
Exploring techniques for setting up tests for Twinkle	Done.	The mock-mediawiki package was created and used for mocking on-site interfaces like mw.config, mw.util and mw.Title in unit tests. A basic framework for writing end-to-end tests has also been implemented. This uses Docker to create a MediaWiki instance locally (or on the CI), and playwright library for browser automation. Jest is used as the test runner, with jest-playwright npm package providing the glue for linking playwright with jest.

Learning

Projects do not always go according to plan. Sharing what you learned can help you and others plan similar projects in the future. Help the movement learn from your experience by answering the following questions:

What worked well?
- Despite not having a concrete plan at the time of proposing the grant. I was able to figure out a well-rounded strategy along the way – with a bit of help from fellow editors.
What did not work so well?
- I initiated discussions on the twinkle github issue tracker for most of the major design aspects. But most of these ended up with me talking to myself with little participation from others. When there was participation it would be by just one person and there would often be no follow-up on my responses, which was infuriating.
- The usual rate of contributions to the existing twinkle repo increased during the period, which was all the more uncomfortable as it meant the goal of migrating the enwiki twinkle installation was continuously being made more and more difficult. Frequently I had to rework parts of the code to take into account new improvements merged to the existing code.
What would you do differently next time?
- Although unconventional for software-related grants, I would prefer to take up a grant in a group of 2. This ensures that even if there is no external participation in discussions, there is at least one person with whom you can run down your ideas.

Finances

Grant funds spent

Please describe how much grant money you spent for approved expenses, and tell us what you spent it on.

$2000 was spent on my own software development time.

Remaining funds

Do you have any remaining grant funds?

There are no remaining grant funds.

Anything else

Anything else you want to share about your project?

Twinkle core is hosted on the wikimedia-gadgets organisation on GitHub, which I created during the course of this project. It currently has 12 members and 15 code repositories. There is also a Discord server associated with it. I feel that this new organisation has brought the community of script/gadget developers closer.
Twinkle core is among the first gadgets written in TypeScript. I created the types-mediawiki package to serve as a resource providing MW type definitions for all gadgets (and maybe even MediaWiki extensions). It is currently being used by RedWarn as well – another project being rewritten in TypeScript.