Diff for "Translations/Specs/ReportingAPI"

Not logged in - Log In / Register

Differences between revisions 4 and 5
Revision 4 as of 2010-02-22 15:25:09
Size: 3469
Editor: dpm
Comment:
Revision 5 as of 2010-02-22 16:30:12
Size: 7199
Editor: dpm
Comment:
Deletions are marked like this. Additions are marked like this.
Line 5: Line 5:
Development of a Launchpad Translations API.

This Launchpad enhancement proposal discusses extending the functionality of Launchpad Translations by allowing read and write access to translations-related data from Launchpad through launchpadlib.
This Launchpad enhancement proposal discusses extending the functionality of Launchpad Translations by developing an API which will expose the necessary interfaces to allow read and write access to translations-related data from Launchpad through launchpadlib.
Line 11: Line 9:
'''As the ''' $PERSON<<BR>>
'''I want ''' $FEATURE<<BR>>
'''so that ''' $BENEFIT<<BR>>

''Consider clarifying the feature by describing what it is not?''
'''As the ''' [[https://launchpad.net/~dpm|Ubuntu Translations Coordinator]]<<BR>>
'''I'd like to propose ''' the development of a Translations API<<BR>>
'''so that ''' the Ubuntu Translations community and other customers can benefit from accessing the Launchpad Translations data in alternative ways which will help them assessing the status of translations at the distro level, track progress and set translation goals which will improve the translation coverage of Ubuntu. In addition to that, other functionality provided by the API can assist the Ubuntu translations coordinators in managing the Ubuntu Translations import queue and automate the currently manual processes<<BR>>
Line 19: Line 15:
''Why are we doing this now?'' Due to other higher priority development work, the Translations component has been lacking a full API for quite some time now.
Line 21: Line 17:
''What value does this give our users? Which users?'' The main benefit accessing data through launchpadlib can provide to Ubuntu is on the statistics reporting side: currently the main access point to translating Ubuntu is at http://translations.launchpad.net/ubuntu. This view offers statistics to ''all'' translatable packages in the `main` and `restricted` repositories, regardless of distribution. While complete, it does not provide information on how well translated Ubuntu is as a distribution. This information can be very useful to Ubuntu translators in assessing what needs to be translated and on which packages they should concentrate their work. This can also be used to track progress, set up goals, and in short, as an aid to building community around translations. In the same way, this can be useful for commercial customers to assess translation coverage when evaluating to ship Ubuntu in a given language.

As the current focus of Launchpad development is on upstream integration, and as there is no planned UI work in that area, an API appears to be the most adequate way to allow accessing the Launchpad Translations data and present it in alternative ways to suit the stakeholders' needs.

This is only one of the uses the API would enable (reporting), but there are other functionalities (import queue management, translation) which would not only greatly reducing the amount of work in managing Ubuntu translations, but also open up the Translations component to many interesting uses.
Line 41: Line 41:
This part of the API focuses on exposing read-only data for the purpose of reporting on the status of translations. Each subsection treats a separate aspect of reporting, with '''DATA''' lists as the proposals for the data to be exposed.
Line 43: Line 45:
Retrieve the list of all languages available in Launchpad. Retrieving the list of all languages available in Launchpad. For each language the following data would be required:
Line 46: Line 48:
  * Language code
 
* Language name in English
  * Language state (visible or not)
  * Plural forms (optional, for checking language support)
 
* Text direction (optional)
 * Language code
* Language name in English
 * Language state (visible or not)
 * Plural forms [optional, for checking language support]
* Text direction [optional]
 * The rest of the data at https://translations.launchpad.net/+languages/$LANG [optional]
Line 52: Line 55:
It would be nice to some other data presented on language page https://translations.launchpad.net/+languages/ro , but this is a good start

It would be nice to be able to query just a specific language.
It would be also desirable to have the ability of querying a single language as well.
Line 57: Line 58:
Retrieve the list of all templates available for a series in Launchpad.
Retrieving the list of all templates available for a series in Launchpad. For each template the following data would be required:
Line 69: Line 71:
 * in how many languages it is translates (nice to have)  * in which languages there is a translation available [optional]
Line 71: Line 73:
It would be nice to be able to query a template from a series, based on the Launchpad template name. It would also be required to be able to query a

It would also
be nice to be able to query a template from a series, based on the Launchpad template name.
Line 74: Line 78:
Line 91: Line 96:
''What are the workflows for this feature?''
''Provide mockups for each workflow.''
 * [[../ApiDevelopment|Previous discussion on the API development]]
 * Danilo's thoughts on structuring the work:
''
First, I'd do API for single PO file statistics: you'd have to worry about exporting a shared interface IRosettaStats through API, so all the other objects which are based on it will get the same API as well.
Line 94: Line 101:
'''''You do not have to get the mockups and workflows right at this point. In fact, it is better to have several alternatives, delaying deciding on the final set of workflows until the last responsible moment.''''' Next step would be to figure out a good API for a single potemplate and work on that. Other than the simple properties, the most interesting bit here is how do you get statistics for a bunch of attached PO files. If you don't do anything but just export a single method to list out all the PO files, you'll be doing one API call for each of the languages for a PO template and that's going to be very slow. Eg. to get full status export for Ubuntu out of LP you'd need to do some ~400k API calls.

So, a much better solution to that is to provide a method which gives you all related PO file statistics: "getPOFilesWithStatistics()" which returns tuples of form (POFile, translated_count, changed_count, unreviewed_count, untranslated_count) directly. FWIW, I'd keep this a separate step as well, so this would be bug/branch 3 already :)

And only then, as the final step, I'd do an export of IPOTemplateS(ubs)et APIs for all the different objects that have them. As another part of this step, you'd probably want to do the similar to above and provide a getPOFilesWithStatistics(language) method on them.

If you don't divide the work in this manner, you are going to end up with a gigantic branch that'll be hard to get right and get landed, and everybody will easily get lost about what exactly should be the next step.
''
Line 104: Line 118:
 * [[../ApiDevelopment|Previous discussion on the API development]]

Launchpad Translations API

This Launchpad enhancement proposal discusses extending the functionality of Launchpad Translations by developing an API which will expose the necessary interfaces to allow read and write access to translations-related data from Launchpad through launchpadlib.

On Launchpad: https://blueprints.launchpad.net/rosetta/+spec/api

As the Ubuntu Translations Coordinator
I'd like to propose the development of a Translations API
so that the Ubuntu Translations community and other customers can benefit from accessing the Launchpad Translations data in alternative ways which will help them assessing the status of translations at the distro level, track progress and set translation goals which will improve the translation coverage of Ubuntu. In addition to that, other functionality provided by the API can assist the Ubuntu translations coordinators in managing the Ubuntu Translations import queue and automate the currently manual processes

Rationale

Due to other higher priority development work, the Translations component has been lacking a full API for quite some time now.

The main benefit accessing data through launchpadlib can provide to Ubuntu is on the statistics reporting side: currently the main access point to translating Ubuntu is at http://translations.launchpad.net/ubuntu. This view offers statistics to all translatable packages in the main and restricted repositories, regardless of distribution. While complete, it does not provide information on how well translated Ubuntu is as a distribution. This information can be very useful to Ubuntu translators in assessing what needs to be translated and on which packages they should concentrate their work. This can also be used to track progress, set up goals, and in short, as an aid to building community around translations. In the same way, this can be useful for commercial customers to assess translation coverage when evaluating to ship Ubuntu in a given language.

As the current focus of Launchpad development is on upstream integration, and as there is no planned UI work in that area, an API appears to be the most adequate way to allow accessing the Launchpad Translations data and present it in alternative ways to suit the stakeholders' needs.

This is only one of the uses the API would enable (reporting), but there are other functionalities (import queue management, translation) which would not only greatly reducing the amount of work in managing Ubuntu translations, but also open up the Translations component to many interesting uses.

Stakeholders

Constraints

The new behaviour must provide a way to access translations data from Launchpad, either in read (or depending on the value) or write mode through launchpadlib, without the need for an admin to query the database.

It must not provide a way to circumvent any security privileges built in the layers above (e.g. Launchpad UI)

Subfeatures

The API can be initially subdivided in several areas, which will be exposed separately below.

Reporting

This part of the API focuses on exposing read-only data for the purpose of reporting on the status of translations. Each subsection treats a separate aspect of reporting, with DATA lists as the proposals for the data to be exposed.

Languages

Retrieving the list of all languages available in Launchpad. For each language the following data would be required:

DATA:

It would be also desirable to have the ability of querying a single language as well.

PO Templates

Retrieving the list of all templates available for a series in Launchpad. For each template the following data would be required:

DATA:

  • template name in Launchpad
  • priority
  • length
  • date last updated
  • domain name
  • iscurrent (active or not)
  • source package
  • is in lang pack
  • the list of POFiles associated with this POTemplate
  • in which languages there is a translation available [optional]

It would also be required to be able to query a

It would also be nice to be able to query a template from a series, based on the Launchpad template name.

PO Files

Retrieve the list of all PO files for a template in a series.

The list should contain:

  • language code
  • when the translation was last updated
  • number of translated messages
  • number of unreviewed messages
  • number of changed messages
  • who was the last translator

Import queue

Translation

Workflows

First, I'd do API for single PO file statistics: you'd have to worry about exporting a shared interface IRosettaStats through API, so all the other objects which are based on it will get the same API as well.

Next step would be to figure out a good API for a single potemplate and work on that. Other than the simple properties, the most interesting bit here is how do you get statistics for a bunch of attached PO files. If you don't do anything but just export a single method to list out all the PO files, you'll be doing one API call for each of the languages for a PO template and that's going to be very slow. Eg. to get full status export for Ubuntu out of LP you'd need to do some ~400k API calls.

So, a much better solution to that is to provide a method which gives you all related PO file statistics: "getPOFilesWithStatistics()" which returns tuples of form (POFile, translated_count, changed_count, unreviewed_count, untranslated_count) directly. FWIW, I'd keep this a separate step as well, so this would be bug/branch 3 already :)

And only then, as the final step, I'd do an export of IPOTemplateS(ubs)et APIs for all the different objects that have them. As another part of this step, you'd probably want to do the similar to above and provide a getPOFilesWithStatistics(language) method on them.

If you don't divide the work in this manner, you are going to end up with a gigantic branch that'll be hard to get right and get landed, and everybody will easily get lost about what exactly should be the next step.

Success

How will we know when we are done?

How will we measure how well we have done?

Thoughts?

Translations/Specs/ReportingAPI (last edited 2011-02-22 15:34:23 by dpm)