L10n:Pontoon/API

Description

Exposing Pontoon's data through an API will enable external consumers to build tools, extensions and reports about translations. In the future, the API will serve as the backend for Pontoon.NEXT's SPA front-end. We chose an iterative approach to exposing the data. We start small with a small number of clear-focused use-cases in mind and expand the scope in subsequent iterations. The API is based on GraphQL (see discussion).

The tracking bug for all work related to the API for Pontoon is bug pontoon-api.

Overview

Milestone	Theme	Date	Status
M1	Projects and Locales	September 2017	✓
M2	Translations (Read-Only)	November 2017
M3	Translations (Write)	January 2018
M4	User Notifications	March 2018
M5	Contributors	May 2018

Roadmap

Milestone 1

Complete, deployed on October 2, 2017.

In the first iteration we'd like to make some data stored in Pontoon openly available for third-parties. The goals is to create an API endpoint supporting queries related to aggregate statistics per locale and per project. The main driver is the use case from bug 1302053:

• Stats for a locale: supported projects, status of each project.
• Stats for a project: supported locales, incomplete locales, complete locales.

Full Query

ID	Summary	Status	Resolution	Assigned to	Depends on	Blocks
1302053	Expose project status and information through API	RESOLVED	FIXED	Staś Małolepszy :stas		1395273
1403861	[API] Hide aggregate statistics about Suggested strings	RESOLVED	FIXED	Staś Małolepszy :stas	1377969	1395273
1407192	[API] Enable GraphiQL IDE on production	RESOLVED	MOVED			1395273
1409704	[tracking] Pontoon API Milestone 2	RESOLVED	WONTFIX		1408625, 1409711, 1409723, 1409724	1395273
1410387	[API] Expose aggregate statistics about Suggestions	RESOLVED	MOVED		1377969	1395273

5 Total; 0 Open (0%); 5 Resolved (100%); 0 Verified (0%);

Milestone 2

Main theme: read-only translations and pagination.

Use-cases:

• Report translation status of a single page on mozilla.org
• Read-only data required by Pontoon.Next's Translate app

Queries:

• Establish a good practice for paginating results.
• List all Resources for a Project.
• List all Entities for a Resource.
• List all Translations into a given Locale for an Entity.
  • Include status: approved, suggested, fuzzy.
  • Allow filtering on status via params?
  • List all Translations for an Entity
• List all TranslatedResources for a ProjectLocale
  • Include aggregate statistics.
  • List all TranslatedResources for a Resource.
  • List all TranslatedResources for a Locale.

Milestone 3

Main theme: authenticated mutations.

Use-cases:

• Editing translations via Pontoon.Next's Translate app

Queries:

• Add a translation for an Entity
  • "approved" if the permissions are high enough
  • "suggested" otherwise
• Approve/reject a suggestion.

Milestone 4

Main theme: user notifications.

Use-cases:

• Michal's Pontoon Tools extension

Queries:

• List unread notifications for a logged-in user.

Milestone 5

Main theme: contributors.

• Query a single contributor (by email? unique key?)
  • List recent activity: date, project, action, number of affected strings
  • Aggregate counts of: translated, suggested, fuzzy strings across all projects
  • List of projects they contribute to
    • Aggregate counts of: translated, suggested, fuzzy strings for each project
• List all contributors on Pontoon
• List all contributors for a locale
• List all contributors for a project
• List all contributors for a localization (ProjectLocale)

Milestone X

Main theme: statistics over time.

• Use case and Early rumblings.

Contact

Role	Name	IRC
Feature Owner	Staś Małolepszy	stas
Product Owner	Matjaž Horvat	mathjazz
Reviewer	Adrian Gaudebert	adrian

Mailing list

tools-l10n

IRC

#pontoon