User:Wenzel/Jetpack:L10n Webapp Specs

	THIS PAGE IS A WORKING DRAFT
	The page may be difficult to navigate, and some information on its subject might be incomplete and/or evolving rapidly. If you have any questions or ideas, please add them as a new topic on the discussion page.

These are the specs for the server-side web application part of JEP 113.

Goals

The server side service of Jetpack L10n has two parts:

1. A localization interface for jetpacks, offering strings to the user for translation
2. A backend API allowing installed jetpacks to retrieve translations

The service is going to allow for:

• extracting entities from jetpacks and collecting them in a database (possibly via JSHydra)
• allowing for localization of the entities
• allowing for overwriting localizations for specific jetpacks/uses of the entity in jetpack
• covering jetpack-to-server communication and entity synchronization between the local cache of the pool and the server (via JSON)
• it'll provide statistics, history view and some management capabilities for locale owners (like, remove all contributions by selected user)
• should provide info to translator like: similar entities translations or translations of this entity into similar locales

The primary UI is the localization view which should allow for easy entity localization with ability to look at where the entity is used (i.e., in what Jetpacks and in what locations therein) and how other locales localized it.

Project Outline, 1st iteration

General Points

L10n will eventually live inside Flightdeck or AMO, therefore:

• Django project
• Use or allow for virtualenv and pip, and deployment through mod_wsgi (cf. AMO docs)
• Use a MySQL database. When evolving the database, use migrations (you may use South if you prefer, but schematic is much simpler).
• Track the code in a public repository that allows for easy code review (git, hg, or SVN).

String Extraction

• Extract gettext-like strings from jetpacks, track them in the database, including which jetpack they come from and what lines they are used in.

User registration/rights

• Allow user signup/login, but keep things simple (there is django-registration, for example)
  • Use Django's admin pages for admin-only actions
• Distinguish between:
  • anonymous users (read only)
  • unknown contributors (suggestions only)
  • registered localizers (can translate by themselves, or approve/deny suggestions)
  • admins
• may borrow from AMO's ACL app (docs) for that

Translation UI

• Present user interface for translation of the extracted strings
• Allow for reasonable filtering (by add-on, untranslated strings only, etc.), sorting by popularity (frequency of use in all jetpacks)
• Add translated strings to common translation pool
• When not-yet-translated jetpacks use strings that exist in the pool, assume the translations in the pool are the right translations for these strings
• Allow exceptions from this rule, i.e.:
  • By default, a new jetpack uses the translation from the pool
  • User can change that string's translation for the whole jetpack (all occurrences)
  • or just for a single occurrence in that jetpack (i.e., "only hello.js:20")
  • User can return to the default.

API

No elaborate API yet in this iteration, but a simple view exporting the current strings for a jetpack to JSON would be handy.

• Client will contact the server with the list of jetpacks in use
• Server should return a list of entities and their translations matching that provide the best possible localization of the jetpack to the given language
• In case client has a jetpack not known to the server it may fire additional API usage in which the client provides a list of entities and server responds with translation of the entities

Language fallback

In case a given jetpack has no full localization into requested language one of two things may happen:

• If the user wants to use partially localized jetpacks, provide partial localization
• If the user does not want to use partially localized jetpacks (default), provide localization using fallback mechanism (es-BO-ost -> es-BO -> es-AR -> es -> en-US)

Proof of Concept

Gandalf made a simple POC of the server (source) that can give some ideas.

Later Iterations

APIs, JEP, and L20n capabilities.