Pootle API

Motivation

  1. Mozilla wants to be able to get status and contribution information from Pootle; what needs to be done, what has someone contributed.
  2. We want Solas to be able to interact with Pootle and initiate and publish translatable jobs to Pootle so that it can provide a web based translation environment to Solas translation projects.
  3. Users and system administrations want to be able to interact with Pootle without needing shell access.

Use Cases

  • Barry has a project hosted on pootle.locamotion.org and wants to automate pushing and updating strings. At the moment he can’t since he has no command line access but with an API and CLI tool he can automate this in bash scripts or in other programming languages.

Mozilla related

  • Mozilla wants to be able to retrieve the contributions from a given translator to display them in its telephone directory.
  • Mozilla wants to be able to report work that still needs to be done.

Solas related

  • Solas has a new project that it wants to initiate on Pootle. When initiating it wants to supply the languages, files, descriptions and translators assigned to the project.
  • Solas wants to update descriptions on Pootle to match those in the upstream project.
  • Solas wants to update files following a refresh of the source document.
  • Solas wants an information about the progress being made on Pootle to report to its users.
  • When a project is complete Solas wants to remove it from Pootle.

Implementation

Projects should be defined in a .pootle configuration folder for the command line tool or in the API.

Abilities required

  • <LANG> is the language PK (not the code)
  • <USER> is the user PK (not the username)
  • <PROJ> is the project PK (not the code)
  • <TRAP> is the translation project PK
  • <STOR> is the store PK
  • <UNIT> is the unit PK
  • <SUGG> is the suggestion PK

Warning

Warning

TODO: Need to look at caching. But this will be left for the future.

Note

  • Q: Review all command names because might be inconsistent. Also need to talk about the commands, because this is not an API thing but something used in pootle-cli perhaps.
  • A: Makes sense to split off the CLI implementation beyond a basic tool for now. The tool will have a very different interaction with the server I think. I think we should at least align the command names. E.g. to create a new <LANG> we had add, while a <USER> we have create.

Warning

  • Q: Need to make clear at which levels translations can be pushed or retrieved. I assume that the original idea was to push files.

    Perhaps we should start with a low level API and then add that ability at upper levels. By that I mean pushing single units and then add the ability for sending/retrieving files (stores), and after that perhaps add at upper levels (TP, project or subsets of those two).

  • A: Yes, the original idea in ttk-get and ttk-put is to push and pull files. Also for Solas it would be that ability.

    I’m not sure what the lowest level should be, I guess unit for live interaction e.g. Virtaal translating live against Pootle DB. Or a live website wanting to see flow of translations.

    But for most project related I would see this as a store, while a store is a collection of units it is what Pootle is using. Unit level allows clearer abstraction of searching and checks I would guess.

    Some discussion needed here I think.

Note

DB: Should we call get and put, push and pull to match DVCS semantics? I’m leaning to pull and push.

  • get (pull) – retrieve translations from Pootle [2] [4]
  • put (push) – publish translations to Pootle [2] [4]

Django side

We’ll use tastypie to handle the RESTful API.

  • Authentication – Will use BasicHTTPAuth. More methods can be added in the future.

Zero stage

Initial tastypie implementation that puts in all the infrastructure for the API. Including updates to requirements/, documentation, etc.

API version will be 0.9 until stabilised.

Basic API implementation for list_languages and a command line tool that could call it.

First stage

Provide stats for Mozilla in terms of translations contributed. Provide a linkable badge for users to brag about translations that makes use of this API.

Second stage

We’ll address the command line approach as a test implementation. Thus allowing all actions from a pootle-cli tool. This will allow us to iron out issues and easily test error reporting and failures. When it passes that would mean that we can safely expose this to external tools.

Third stage

Actual Pootle <–> Solas interaction. So expose the API and give feedback to the team on collaboration.

Fourth stage

Using Virtaal. Some ideas:

  • Ability to list public Pootle servers
  • Ability to drill into projects
  • Request a language
  • See list of files and completion like a catalog manager
  • Perform translations

API stability

  • There are no plans for a stable API until v1.0
  • Once we declare v1.0 we’ll keep a stable API for that until deprecated by v2.0