Weblate’s Web API¶

REST API¶

Добавлено в версии 2.6: The API is available since Weblate 2.6.

The API is accessible on the /api/ URL and it is based on Django REST framework. You can use it directly or by Weblate Client.

Authentication and generic parameters¶

The public project API is available without authentication, though unauthenticated requests are heavily throttled (by default to 100 requests per day), so it is recommended to use authentication. The authentication is using token, which you can get in your profile. Use it in the Authorization header:

ANY /¶

Generic request behaviour for the API, the headers, status codes and parameters here apply to all endpoints as well.

Query Parameters:
	format – Response format (overrides Accept). Possible values depends on REST framework setup, by default `json` and `api` are supported. The latter provides web browser interface for API.
Request Headers:
	Accept – the response content type depends on Accept header Authorization – optional token to authenticate
Response Headers:
	Content-Type – this depends on Accept header of request Allow – list of allowed HTTP methods on object
Response JSON Object:
	detail (string) – verbose description of failure (for HTTP status codes other than 200 OK) count (int) – total item count for object lists next (string) – next page URL for object lists previous (string) – previous page URL for object lists results (array) – results for object lists url (string) – URL to access this resource using API web_url (string) – URL to access this resource using web browser
Status Codes:	200 OK – when request was correctly handled 400 Bad Request – when form parameters are missing 403 Forbidden – when access is denied 429 Too Many Requests – when throttling is in place

Authentication examples¶

Example request:

GET /api/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript
Autorization: Token YOUR-TOKEN

Example response:

HTTP/1.0 200 OK
Date: Fri, 25 Mar 2016 09:46:12 GMT
Server: WSGIServer/0.1 Python/2.7.11+
Vary: Accept, Accept-Language, Cookie
X-Frame-Options: SAMEORIGIN
Content-Type: application/json
Content-Language: en
Allow: GET, HEAD, OPTIONS

{
    "projects":"http://example.com/api/projects/",
    "components":"http://example.com/api/components/",
    "translations":"http://example.com/api/translations/",
    "languages":"http://example.com/api/languages/"
}

CURL example:

curl \
    -H "Authorization: Token TOKEN" \
    https://example.com/api/

Passing Parameters Examples¶

For the POST method the parameters can be specified either as form submission (application/x-www-form-urlencoded) or as JSON (application/json).

Form request example:

POST /api/projects/hello/repository/ HTTP/1.1
Host: example.com
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Token TOKEN

operation=pull

JSON request example:

POST /api/projects/hello/repository/ HTTP/1.1
Host: example.com
Accept: application/json
Content-Type: application/json
Authorization: Token TOKEN
Content-Length: 20

{"operation":"pull"}

CURL example:

curl \
    -d operation=pull \
    -H "Authorization: Token TOKEN" \
    http://example.com/api/components/hello/weblate/repository/

CURL JSON example:

curl \
    --data-binary '{"operation":"pull"}' \
    -H "Content-Type: application/json" \
    -H "Authorization: Token TOKEN" \
    http://example.com/api/components/hello/weblate/repository/

API Entry Point¶

GET /api/¶

The API root entry point.

Example request:

GET /api/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript
Autorization: Token YOUR-TOKEN

Example response:

HTTP/1.0 200 OK
Date: Fri, 25 Mar 2016 09:46:12 GMT
Server: WSGIServer/0.1 Python/2.7.11+
Vary: Accept, Accept-Language, Cookie
X-Frame-Options: SAMEORIGIN
Content-Type: application/json
Content-Language: en
Allow: GET, HEAD, OPTIONS

{
    "projects":"http://example.com/api/projects/",
    "components":"http://example.com/api/components/",
    "translations":"http://example.com/api/translations/",
    "languages":"http://example.com/api/languages/"
}

Languages¶

GET /api/languages/¶: Returns listing of all languages.

См.также

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

Language object attributes are documented at GET /api/languages/(string:language)/.

GET /api/languages/(string: language)/¶

Returns information about language.

Response JSON Object:
Parameters:	language (string) – Language code
	code (string) – Language code direction (string) – Text direction nplurals (int) – Number of plurals pluralequation (string) – Gettext plural equation

См.также

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

Example JSON data:

{
    "code": "en",
    "direction": "ltr",
    "name": "English",
    "nplurals": 2,
    "pluralequation": "n != 1",
    "url": "http://example.com/api/languages/en/",
    "web_url": "http://example.com/languages/en/"
}

Projects¶

GET /api/projects/¶: Returns listing of projects.

См.также

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

Project object attributes are documented at GET /api/projects/(string:project)/.

GET /api/projects/(string: project)/¶

Returns information about project.

Parameters:

project (string) – Project URL slug

Response JSON Object:

name (string) – project name
slug (string) – project slug
source_language (object) – source language object, see GET /api/languages/(string:language)/
web (string) – project website
components_list_url (string) – URL to components list, see GET /api/projects/(string:project)/components/
repository_url (string) – URL to repository status, see GET /api/projects/(string:project)/repository/

См.также

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

Example JSON data:

{
    "name": "Hello",
    "slug": "hello",
    "source_language": {
        "code": "en",
        "direction": "ltr",
        "name": "English",
        "nplurals": 2,
        "pluralequation": "n != 1",
        "url": "http://example.com/api/languages/en/",
        "web_url": "http://example.com/languages/en/"
    },
    "url": "http://example.com/api/projects/hello/",
    "web": "http://weblate.org/",
    "web_url": "http://example.com/projects/hello/"
}

GET /api/projects/(string: project)/repository/¶

Returns information about VCS repository status. This endpoint contains only overall summary for all repositories for project. To get more detailed status use GET /api/components/(string:project)/(string:component)/repository/.

Response JSON Object:
Parameters:	project (string) – Project URL slug
	needs_commit (boolean) – whether there are any pending changes to commit needs_merge (boolean) – whether there are any upstream changes to merge needs_push (boolean) – whether there are any local changes to push

См.также

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

Example JSON data:

{
    "needs_commit": true,
    "needs_merge": false,
    "needs_push": true
}

POST /api/projects/(string: project)/repository/¶

Performs given operation on the VCS repository.

Request JSON Object:
Parameters:	project (string) – Project URL slug
	operation – Operation to perform, one of `push`, `pull`, `commit`, `reset`
Response JSON Object:
	result (boolean) – result of the operation

См.также

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

CURL example:

curl \
    -d operation=pull \
    -H "Authorization: Token TOKEN" \
    http://example.com/api/components/hello/weblate/repository/

JSON request example:

POST /api/projects/hello/repository/ HTTP/1.1
Host: example.com
Accept: application/json
Content-Type: application/json
Authorization: Token TOKEN
Content-Length: 20

{"operation":"pull"}

JSON response example:

HTTP/1.0 200 OK
Date: Tue, 12 Apr 2016 09:32:50 GMT
Server: WSGIServer/0.1 Python/2.7.11+
Vary: Accept, Accept-Language, Cookie
X-Frame-Options: SAMEORIGIN
Content-Type: application/json
Content-Language: en
Allow: GET, POST, HEAD, OPTIONS

{"result":true}

GET /api/projects/(string: project)/components/¶

Returns list of translation components in given project.

Response JSON Object:
Parameters:	project (string) – Project URL slug
	results (array) – array of component objects, see `GET /api/components/(string:project)/(string:component)/`

См.также

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

Components¶

GET /api/components/¶: Returns listin of translation components.

См.также

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

Component object attributes are documented at GET /api/components/(string:project)/(string:component)/.

GET /api/components/(string: project)/(string: component)/¶

Returns information about translation component.

Parameters:

project (string) – Project URL slug
component (string) – Component URL slug

Response JSON Object:

branch (string) – VCS repository branch
file_format (string) – file format of translations
filemask (string) – mask of translation files in the repository
git_export (string) – URL of the exported VCS repository with translations
license (string) – license for translations
license_url (string) – URL of license for translations
name (string) – name of component
slug (string) – slug of component
project (object) – the translation project, see GET /api/projects/(string:project)/
repo (string) – VCS repository URL
template (string) – base file for monolingual translations
new_base (string) – base file for adding new translations
vcs (string) – version control system
repository_url (string) – URL to repository status, see GET /api/components/(string:project)/(string:component)/repository/
translations_url (string) – URL to translations list, see GET /api/components/(string:project)/(string:component)/translations/
lock_url (string) – URL to lock statuc, see GET /api/components/(string:project)/(string:component)/lock/

См.также

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

Example JSON data:

{
    "branch": "master",
    "file_format": "po",
    "filemask": "po/*.po",
    "git_export": "",
    "license": "",
    "license_url": "",
    "name": "Weblate",
    "slug": "weblate",
    "project": {
        "name": "Hello",
        "slug": "hello",
        "source_language": {
            "code": "en",
            "direction": "ltr",
            "name": "English",
            "nplurals": 2,
            "pluralequation": "n != 1",
            "url": "http://example.com/api/languages/en/",
            "web_url": "http://example.com/languages/en/"
        },
        "url": "http://example.com/api/projects/hello/",
        "web": "http://weblate.org/",
        "web_url": "http://example.com/projects/hello/"
    },
    "repo": "file:///home/nijel/work/weblate-hello",
    "template": "",
    "new_base": "",
    "url": "http://example.com/api/components/hello/weblate/",
    "vcs": "git",
    "web_url": "http://example.com/projects/hello/weblate/"
}

GET /api/components/(string: project)/(string: component)/lock/¶

Returns component lock status.

Response JSON Object:
Parameters:	project (string) – Project URL slug component (string) – Component URL slug
	locked (boolean) – whether component is locked for updates

См.также

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

Example JSON data:

{
    "locked": false
}

POST /api/components/(string: project)/(string: component)/lock/¶

Sets component lock status.

Response is same as GET /api/components/(string:project)/(string:component)/lock/.

Request JSON Object:
Parameters:	project (string) – Project URL slug component (string) – Component URL slug
	lock – Boolean whether to lock or not.

См.также

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

GET /api/components/(string: project)/(string: component)/repository/¶

Returns information about VCS repository status.

The response is same as for GET /api/projects/(string:project)/repository/.

Parameters:

project (string) – Project URL slug
component (string) – Component URL slug

Response JSON Object:

needs_commit (boolean) – whether there are any pending changes to commit
needs_merge (boolean) – whether there are any upstream changes to merge
needs_push (boolean) – whether there are any local changes to push
remote_commit – Remote commit information
status – VCS repository status as reported by VCS
merge_failure – Text describing merge failure, null if there is none

См.также

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

POST /api/components/(string: project)/(string: component)/repository/¶

Performs given operation on the VCS repository.

See POST /api/projects/(string:project)/repository/ for documentation.

Request JSON Object:
Parameters:	project (string) – Project URL slug component (string) – Component URL slug
	operation – Operation to perform, one of `push`, `pull`, `commit`, `reset`
Response JSON Object:
	result (boolean) – result of the operation

См.также

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

GET /api/components/(string: project)/(string: component)/monolingual_base/¶

Downloads base file for monolingual translations.

Parameters:	project (string) – Project URL slug component (string) – Component URL slug

См.также

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

GET /api/components/(string: project)/(string: component)/new_template/¶

Downloads template file for new translations.

Parameters:	project (string) – Project URL slug component (string) – Component URL slug

См.также

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

GET /api/components/(string: project)/(string: component)/translations/¶

Returns list of translation objects in given component.

Response JSON Object:
Parameters:	project (string) – Project URL slug component (string) – Component URL slug
	results (array) – array of translation objects, see `GET /api/translations/(string:project)/(string:component)/(string:language)/`

См.также

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

GET /api/components/(string: project)/(string: component)/statistics/¶

Returns paginated statistics for all translations within component.

Добавлено в версии 2.7.

Response JSON Object:
Parameters:	project (string) – Project URL slug component (string) – Component URL slug
	results (array) – array of translation statis objects, see `GET /api/translations/(string:project)/(string:component)/(string:language)/statistics/`

Translations¶

GET /api/translations/¶: Returns list of translations.

См.также

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

Translation object attributes are documented at GET /api/translations/(string:project)/(string:component)/(string:language)/.

GET /api/translations/(string: project)/(string: component)/(string: language)/¶

Returns information about translation.

Parameters:

project (string) – Project URL slug
component (string) – Component URL slug
language (string) – Translation language code

Response JSON Object:

component (object) – component object, see GET /api/components/(string:project)/(string:component)/
failing_checks (int) – number of units with failing check
failing_checks_percent (float) – percetage of failing check units
failing_checks_words (int) – number of words with failing check
filename (string) – translation filename
fuzzy (int) – number of units marked for review
fuzzy_percent (float) – percetage of units marked for review
fuzzy_words (int) – number of words marked for review
have_comment (int) – number of units with comment
have_suggestion (int) – number of units with suggestion
is_template (boolean) – whether translation is monolingual base
language (object) – source language object, see GET /api/languages/(string:language)/
language_code (string) – language code used in the repository, this can be different from language code in the language object
last_author (string) – name of last author
last_change (timestamp) – last change timestamp
revision (string) – hash revision of the file
share_url (string) – URL for sharing leading to engage page
total (int) – total number of units
total_words (int) – total number of words
translate_url (string) – URL for translating
translated (int) – number of translated units
translated_percent (float) – percentage of translated units
translated_words (int) – number of translated words
repository_url (string) – URL to repository status, see GET /api/translations/(string:project)/(string:component)/(string:language)/repository/
file_url (string) – URL to file object, see GET /api/translations/(string:project)/(string:component)/(string:language)/file/

См.также

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

Example JSON data:

{
    "component": {
        "branch": "master",
        "file_format": "po",
        "filemask": "po/*.po",
        "git_export": "",
        "license": "",
        "license_url": "",
        "name": "Weblate",
        "new_base": "",
        "project": {
            "name": "Hello",
            "slug": "hello",
            "source_language": {
                "code": "en",
                "direction": "ltr",
                "name": "English",
                "nplurals": 2,
                "pluralequation": "n != 1",
                "url": "http://example.com/api/languages/en/",
                "web_url": "http://example.com/languages/en/"
            },
            "url": "http://example.com/api/projects/hello/",
            "web": "http://weblate.org/",
            "web_url": "http://example.com/projects/hello/"
        },
        "repo": "file:///home/nijel/work/weblate-hello",
        "slug": "weblate",
        "template": "",
        "url": "http://example.com/api/components/hello/weblate/",
        "vcs": "git",
        "web_url": "http://example.com/projects/hello/weblate/"
    },
    "failing_checks": 3,
    "failing_checks_percent": 75.0,
    "failing_checks_words": 11,
    "filename": "po/cs.po",
    "fuzzy": 0,
    "fuzzy_percent": 0.0,
    "fuzzy_words": 0,
    "have_comment": 0,
    "have_suggestion": 0,
    "is_template": false,
    "language": {
        "code": "cs",
        "direction": "ltr",
        "name": "Czech",
        "nplurals": 3,
        "pluralequation": "(n==1) ? 0 : (n>=2 && n<=4) ? 1 : 2",
        "url": "http://example.com/api/languages/cs/",
        "web_url": "http://example.com/languages/cs/"
    },
    "language_code": "cs",
    "last_author": "Weblate Admin",
    "last_change": "2016-03-07T10:20:05.499",
    "revision": "7ddfafe6daaf57fc8654cc852ea6be212b015792",
    "share_url": "http://example.com/engage/hello/cs/",
    "total": 4,
    "total_words": 15,
    "translate_url": "http://example.com/translate/hello/weblate/cs/",
    "translated": 4,
    "translated_percent": 100.0,
    "translated_words": 15,
    "url": "http://example.com/api/translations/hello/weblate/cs/",
    "web_url": "http://example.com/projects/hello/weblate/cs/"
}

GET /api/translations/(string: project)/(string: component)/(string: language)/file/¶

Download current translation file.

Query Parameters:
	format – File format to use, if not specified no format conversion happens, supported file formats: `po`, `mo`, `xliff`, `xliff12`, `tbx`
Parameters:	project (string) – Project URL slug component (string) – Component URL slug language (string) – Translation language code

См.также

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

POST /api/translations/(string: project)/(string: component)/(string: language)/file/¶

Upload new file with translations.

Parameters:	project (string) – Project URL slug component (string) – Component URL slug language (string) – Translation language code

См.также

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

CURL example:

curl -X POST \
    -F file=@strings.xml \
    -H "Authorization: Token TOKEN" \
    http://example.com/api/translations/hello/android/cs/file/

GET /api/translations/(string: project)/(string: component)/(string: language)/repository/¶

Returns information about VCS repository status.

The response is same as for GET /api/components/(string:project)/(string:component)/repository/.

Parameters:	project (string) – Project URL slug component (string) – Component URL slug language (string) – Translation language code

См.также

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

POST /api/translations/(string: project)/(string: component)/(string: language)/repository/¶

Performs given operation on the VCS repository.

See POST /api/projects/(string:project)/repository/ for documentation.

Request JSON Object:
Parameters:	project (string) – Project URL slug component (string) – Component URL slug language (string) – Translation language code
	operation – Operation to perform, one of `push`, `pull`, `commit`, `reset`
Response JSON Object:
	result (boolean) – result of the operation

См.также

Additional common headers, parameters and status codes are documented at Authentication and generic parameters.

GET /api/translations/(string: project)/(string: component)/(string: language)/statistics/¶

Returns detailed translation statistics.

Добавлено в версии 2.7.

Parameters:

project (string) – Project URL slug
component (string) – Component URL slug
language (string) – Translation language code

Response JSON Object:

code – language code
failing – number of failing checks
failing_percent – percentage of failing checks
fuzzy – number of strings needing review
fuzzy_percent – percentage of strings needing review
total_words – total number of words
translated_words – number of translated words
last_author – name of last author
last_change – date of last change
name – language name
total – total number of strings
translated – number of translated strings
translated_percent – percentage of translated strings
url – URL to access the translation (engagement URL)
url_translate – URL to access the translation (real translation URL)

Notification hooks¶

Notification hooks allow external applications to notify Weblate that VCS repository has been updated.

You can use repository endpoints for project, component and translation to update individual repositories, see POST /api/projects/(string:project)/repository/ for documentation.

GET /hooks/update/(string: project)/(string: component)/¶: Не рекомендуется, начиная с версии 2.6: Please use POST /api/components/(string:project)/(string:component)/repository/ instead which works properly with authentication for ACL limited projects.

Triggers update of a component (pulling from VCS and scanning for translation changes).

GET /hooks/update/(string: project)/¶: Не рекомендуется, начиная с версии 2.6: Please use POST /api/projects/(string:project)/repository/ instead which works properly with authentication for ACL limited projects.

Triggers update of all components in a project (pulling from VCS and scanning for translation changes).

POST /hooks/github/¶

Special hook for handling GitHub notifications and automatically updating matching components.

Примечание

GitHub includes direct support for notifying Weblate, just enable Weblate service hook in repository settings and set URL to URL of your Weblate installation.

См.также

Automatically receiving changes from GitHub: For instruction on setting up GitHub integration
https://help.github.com/articles/creating-webhooks: Generic information about GitHub Webhooks
ENABLE_HOOKS: For enabling hooks for whole Weblate

POST /hooks/gitlab/¶

Special hook for handling GitLab notifications and automatically updating matching components.

См.также

Automatically receiving changes from GitLab: For instruction on setting up GitLab integration
http://doc.gitlab.com/ce/web_hooks/web_hooks.html: Generic information about GitLab Webhooks
ENABLE_HOOKS: For enabling hooks for whole Weblate

POST /hooks/bitbucket/¶

Special hook for handling Bitbucket notifications and automatically updating matching components.

См.также

Automatically receiving changes from Bitbucket: For instruction on setting up Bitbucket integration
https://confluence.atlassian.com/bitbucket/manage-webhooks-735643732.html: Generic information about Bitbucket Webhooks
ENABLE_HOOKS: For enabling hooks for whole Weblate

Exports¶

Weblate provides various exports to allow you further process the data.

GET /exports/stats/(string: project)/(string: component)/¶

Query Parameters:
	jsonp (string) – JSONP callback function to wrap the data

Не рекомендуется, начиная с версии 2.6: Please use GET /api/components/(string:project)/(string:component)/statistics/ and GET /api/translations/(string:project)/(string:component)/(string:language)/statistics/ instead, it allows to access ACL controlled projects as well.

Retrieves statistics for given component in JSON format. Optionally as JSONP when you specify the callback in the jsonp parameter.

Example request:

GET /exports/stats/weblate/master/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

[
    {
        "code": "cs",
        "failing": 0,
        "failing_percent": 0.0,
        "fuzzy": 0,
        "fuzzy_percent": 0.0,
        "last_author": "Michal \u010ciha\u0159",
        "last_change": "2012-03-28T15:07:38+00:00",
        "name": "Czech",
        "total": 436,
        "total_words": 15271,
        "translated": 436,
        "translated_percent": 100.0,
        "translated_words": 3201,
        "url": "http://hosted.weblate.org/engage/weblate/cs/",
        "url_translate": "http://hosted.weblate.org/projects/weblate/master/cs/"
    },
    {
        "code": "nl",
        "failing": 21,
        "failing_percent": 4.8,
        "fuzzy": 11,
        "fuzzy_percent": 2.5,
        "last_author": null,
        "last_change": null,
        "name": "Dutch",
        "total": 436,
        "total_words": 15271,
        "translated": 319,
        "translated_percent": 73.2,
        "translated_words": 3201,
        "url": "http://hosted.weblate.org/engage/weblate/nl/",
        "url_translate": "http://hosted.weblate.org/projects/weblate/master/nl/"
    },
    {
        "code": "el",
        "failing": 11,
        "failing_percent": 2.5,
        "fuzzy": 21,
        "fuzzy_percent": 4.8,
        "last_author": null,
        "last_change": null,
        "name": "Greek",
        "total": 436,
        "total_words": 15271,
        "translated": 312,
        "translated_percent": 71.6,
        "translated_words": 3201,
        "url": "http://hosted.weblate.org/engage/weblate/el/",
        "url_translate": "http://hosted.weblate.org/projects/weblate/master/el/"
    },
]

RSS feeds¶

Changes in translations are exported in RSS feeds.

GET /exports/rss/(string: project)/(string: component)/(string: language)/¶: Retrieves RSS feed with recent changes for a translation.

GET /exports/rss/(string: project)/(string: component)/¶: Retrieves RSS feed with recent changes for a component.

GET /exports/rss/(string: project)/¶: Retrieves RSS feed with recent changes for a project.

GET /exports/rss/language/(string: language)/¶: Retrieves RSS feed with recent changes for a language.

GET /exports/rss/¶: Retrieves RSS feed with recent changes for Weblate instance.

См.также

RSS on wikipedia