Weblate’s REST API¶
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.
The API is also documented using OpenAPI 3.0 on the /api/schema/
URL, you
can browse at /api/docs/
.
Note
OpenAPI is available as a feature preview. The documentation is most likely incomplete at this point and subject to change. Please consult the documentation below for more detailed information on the API.
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 uses a
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
andapi
are supported. The latter provides web browser interface for API.page – Returns given page of paginated results (use next and previous fields in response to automate the navigation).
page_size – Return the given number of items per request. The default is 50 and the maximum is 1000. For the units endpoints the default is 100 with a maximum of 10000. The default value is also configurable using the PAGE_SIZE setting.
- Request Headers:
Authorization – optional token to authenticate as
Authorization: Token YOUR-TOKEN
- 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 the result (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 the API
web_url (string) – URL to access this resource using web browser
- Status Codes:
200 OK – when request was correctly handled
201 Created – when a new object was created successfully
204 No Content – when an object was deleted successfully
400 Bad Request – when form parameters are missing
403 Forbidden – when access is denied
429 Too Many Requests – when throttling is in place
Authentication tokens¶
Changed in version 4.10: Project scoped tokens were introduced in the 4.10 release.
Each user has a personal access token which can be obtained in the user
profile. Newly generated user tokens have the wlu_
prefix.
It is possible to create project scoped tokens for API access to given project
only. These tokens can be identified by the wlp_
prefix.
Authentication examples¶
Example request:
GET /api/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript
Authorization: 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/
Components and categories¶
To access a component which is nested inside a Category, you need to URL
encode the category name into a component name separated with a slash. For
example usage
placed in a docs
category needs to be used as
docs%252Fusage
. Full URL in this case would be for example
https://example.com/api/components/hello/docs%252Fusage/repository/
.
API rate limiting¶
The API requests are rate limited; the default configuration limits it to 100 requests per day for anonymous users and 5000 requests per hour for authenticated users.
Rate limiting can be adjusted in the settings.py
; see
Throttling in Django REST framework documentation
for more details how to configure it.
In the Docker container this can be configured using
WEBLATE_API_RATELIMIT_ANON
and WEBLATE_API_RATELIMIT_USER
.
The status of rate limiting is reported in following headers:
|
Allowed number of requests to perform |
|
Remaining number of requests to perform |
|
Number of seconds until the rate-limit window resets |
Changed in version 4.1: Added ratelimiting status headers.
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 Authorization: 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/" }
Users¶
Added in version 4.0.
- GET /api/users/¶
Returns a list of users if you have permissions to see manage users. If not, then you get to see only your own details.
See also
Users object attributes are documented at
GET /api/users/(str:username)/
.
- POST /api/users/¶
Creates a new user.
- Parameters:
username (string) – Username
full_name (string) – User full name
email (string) – User email
is_superuser (boolean) – Is user superuser? (optional)
is_active (boolean) – Is user active? (optional)
is_bot (boolean) – Is user bot? (optional) (used for project scoped tokens)
- GET /api/users/(str: username)/¶
Returns information about users.
- Parameters:
username (string) – User’s username
- Response JSON Object:
username (string) – username of a user
full_name (string) – full name of a user
email (string) – email of a user
is_superuser (boolean) – whether the user is a super user
is_active (boolean) – whether the user is active
is_bot (boolean) – whether the user is bot (used for project scoped tokens)
date_joined (string) – date the user is created
last_login (string) – date the user last signed in
groups (array) – link to associated groups; see
GET /api/groups/(int:id)/
Example JSON data:
{ "email": "user@example.com", "full_name": "Example User", "username": "exampleusername", "groups": [ "http://example.com/api/groups/2/", "http://example.com/api/groups/3/" ], "is_superuser": true, "is_active": true, "is_bot": false, "date_joined": "2020-03-29T18:42:42.617681Z", "url": "http://example.com/api/users/exampleusername/", "statistics_url": "http://example.com/api/users/exampleusername/statistics/" }
- PUT /api/users/(str: username)/¶
Changes the user parameters.
- Parameters:
username (string) – User’s username
- Response JSON Object:
username (string) – username of a user
full_name (string) – full name of a user
email (string) – email of a user
is_superuser (boolean) – whether the user is a super user
is_active (boolean) – whether the user is active
is_bot (boolean) – whether the user is bot (used for project scoped tokens)
date_joined (string) – date the user is created
- PATCH /api/users/(str: username)/¶
Changes the user parameters.
- Parameters:
username (string) – User’s username
- Response JSON Object:
username (string) – username of a user
full_name (string) – full name of a user
email (string) – email of a user
is_superuser (boolean) – whether the user is a super user
is_active (boolean) – whether the user is active
is_bot (boolean) – whether the user is bot (used for project scoped tokens)
date_joined (string) – date the user is created
- DELETE /api/users/(str: username)/¶
Deletes all user information and marks the user inactive.
- Parameters:
username (string) – User’s username
- POST /api/users/(str: username)/groups/¶
Associate groups with a user.
- Parameters:
username (string) – User’s username
- Form Parameters:
string group_id – The unique group ID
- DELETE /api/users/(str: username)/groups/¶
Added in version 4.13.1.
Remove user from a group.
- Parameters:
username (string) – User’s username
- Form Parameters:
string group_id – The unique group ID
- GET /api/users/(str: username)/statistics/¶
List statistics of a user.
- Parameters:
username (string) – User’s username
- Response JSON Object:
translated (int) – Number of translations by user
suggested (int) – Number of suggestions by user
uploaded (int) – Number of uploads by user
commented (int) – Number of comments by user
languages (int) – Number of languages user can translate
- GET /api/users/(str: username)/notifications/¶
List subscriptions of a user.
- Parameters:
username (string) – User’s username
- POST /api/users/(str: username)/notifications/¶
Associate subscriptions with a user.
- Parameters:
username (string) – User’s username
- Request JSON Object:
notification (string) – Name of notification registered
scope (int) – Scope of notification from the available choices
frequency (int) – Frequency choices for notifications
- GET /api/users/(str: username)/notifications/(int: subscription_id)/¶
Get a subscription associated with a user.
- Parameters:
username (string) – User’s username
subscription_id (int) – ID of notification registered
- PUT /api/users/(str: username)/notifications/(int: subscription_id)/¶
Edit a subscription associated with a user.
- Parameters:
username (string) – User’s username
subscription_id (int) – ID of notification registered
- Request JSON Object:
notification (string) – Name of notification registered
scope (int) – Scope of notification from the available choices
frequency (int) – Frequency choices for notifications
- PATCH /api/users/(str: username)/notifications/(int: subscription_id)/¶
Edit a subscription associated with a user.
- Parameters:
username (string) – User’s username
subscription_id (int) – ID of notification registered
- Request JSON Object:
notification (string) – Name of notification registered
scope (int) – Scope of notification from the available choices
frequency (int) – Frequency choices for notifications
- DELETE /api/users/(str: username)/notifications/(int: subscription_id)/¶
Delete a subscription associated with a user.
- Parameters:
username (string) – User’s username
subscription_id – Name of notification registered
subscription_id – int
Groups¶
Added in version 4.0.
- GET /api/groups/¶
Returns a list of groups if you have permissions to see manage groups. If not, then you get to see only the groups the user is a part of.
See also
Group object attributes are documented at
GET /api/groups/(int:id)/
.
- POST /api/groups/¶
Creates a new group.
- Parameters:
name (string) – Group name
project_selection (int) – Group of project selection from given options
language_selection (int) – Group of languages selected from given options
defining_project (str) – link to the defining project, used for Managing per-project access control; see
GET /api/projects/(string:project)/
- GET /api/groups/(int: id)/¶
Returns information about group.
- Parameters:
id (int) – Group’s ID
- Response JSON Object:
name (string) – name of a group
project_selection (int) – integer corresponding to group of projects
language_selection (int) – integer corresponding to group of languages
roles (array) – link to associated roles; see
GET /api/roles/(int:id)/
projects (array) – link to associated projects; see
GET /api/projects/(string:project)/
components (array) – link to associated components; see
GET /api/components/(string:project)/(string:component)/
componentlists (array) – link to associated componentlist; see
GET /api/component-lists/(str:slug)/
defining_project (str) – link to the defining project, used for Managing per-project access control; see
GET /api/projects/(string:project)/
Example JSON data:
{ "name": "Guests", "defining_project": null, "project_selection": 3, "language_selection": 1, "url": "http://example.com/api/groups/1/", "roles": [ "http://example.com/api/roles/1/", "http://example.com/api/roles/2/" ], "languages": [ "http://example.com/api/languages/en/", "http://example.com/api/languages/cs/", ], "projects": [ "http://example.com/api/projects/demo1/", "http://example.com/api/projects/demo/" ], "componentlist": "http://example.com/api/component-lists/new/", "components": [ "http://example.com/api/components/demo/weblate/" ] }
- PUT /api/groups/(int: id)/¶
Changes the group parameters.
- Parameters:
id (int) – Group’s ID
- Response JSON Object:
name (string) – name of a group
project_selection (int) – integer corresponding to group of projects
language_selection (int) – integer corresponding to group of Languages
- PATCH /api/groups/(int: id)/¶
Changes the group parameters.
- Parameters:
id (int) – Group’s ID
- Response JSON Object:
name (string) – name of a group
project_selection (int) – integer corresponding to group of projects
language_selection (int) – integer corresponding to group of languages
- DELETE /api/groups/(int: id)/¶
Deletes the group.
- Parameters:
id (int) – Group’s ID
- POST /api/groups/(int: id)/roles/¶
Associate roles with a group.
- Parameters:
id (int) – Group’s ID
- Form Parameters:
string role_id – The unique role ID
- POST /api/groups/(int: id)/components/¶
Associate components with a group.
- Parameters:
id (int) – Group’s ID
- Form Parameters:
string component_id – The unique component ID
- DELETE /api/groups/(int: id)/components/(int: component_id)¶
Delete component from a group.
- Parameters:
id (int) – Group’s ID
component_id (int) – The unique component ID
- POST /api/groups/(int: id)/projects/¶
Associate projects with a group.
- Parameters:
id (int) – Group’s ID
- Form Parameters:
string project_id – The unique project ID
- DELETE /api/groups/(int: id)/projects/(int: project_id)¶
Delete project from a group.
- Parameters:
id (int) – Group’s ID
project_id (int) – The unique project ID
- POST /api/groups/(int: id)/languages/¶
Associate languages with a group.
- Parameters:
id (int) – Group’s ID
- Form Parameters:
string language_code – The unique language code
- DELETE /api/groups/(int: id)/languages/(string: language_code)¶
Delete language from a group.
- Parameters:
id (int) – Group’s ID
language_code (string) – The unique language code
- POST /api/groups/(int: id)/componentlists/¶
Associate componentlists with a group.
- Parameters:
id (int) – Group’s ID
- Form Parameters:
string component_list_id – The unique componentlist ID
- DELETE /api/groups/(int: id)/componentlists/(int: component_list_id)¶
Delete componentlist from a group.
- Parameters:
id (int) – Group’s ID
component_list_id (int) – The unique componentlist ID
- POST /api/groups/(int: id)/admins/¶
Added in version 5.5.
Add user to team admins.
- Parameters:
id (int) – Group’s ID
- Form Parameters:
string user_id – The user’s ID
- DELETE /api/groups/(int: id)/admins/(int: user_id)¶
Added in version 5.5.
Delete user from team admins.
- Parameters:
id (int) – Group’s ID
user_id (integer) – The user’s ID
Roles¶
- GET /api/roles/¶
Returns a list of all roles associated with user. If user is superuser, then list of all existing roles is returned.
See also
Roles object attributes are documented at
GET /api/roles/(int:id)/
.
- POST /api/roles/¶
Creates a new role.
- Parameters:
name (string) – Role name
permissions (array) – List of codenames of permissions
- GET /api/roles/(int: id)/¶
Returns information about a role.
- Parameters:
id (int) – Role ID
- Response JSON Object:
name (string) – Role name
permissions (array) – list of codenames of permissions
Example JSON data:
{ "name": "Access repository", "permissions": [ "vcs.access", "vcs.view" ], "url": "http://example.com/api/roles/1/", }
- PUT /api/roles/(int: id)/¶
Changes the role parameters.
- Parameters:
id (int) – Role’s ID
- Response JSON Object:
name (string) – Role name
permissions (array) – list of codenames of permissions
- PATCH /api/roles/(int: id)/¶
Changes the role parameters.
- Parameters:
id (int) – Role’s ID
- Response JSON Object:
name (string) – Role name
permissions (array) – list of codenames of permissions
- DELETE /api/roles/(int: id)/¶
Deletes the role.
- Parameters:
id (int) – Role’s ID
Languages¶
- GET /api/languages/¶
Returns a list of all languages.
See also
Language object attributes are documented at
GET /api/languages/(string:language)/
.
- POST /api/languages/¶
Creates a new language.
- Parameters:
code (string) – Language name
name (string) – Language name
direction (string) – Text direction
population (int) – Number of speakers
plural (object) – Language plural formula and number
- GET /api/languages/(string: language)/¶
Returns information about a language.
- Parameters:
language (string) – Language code
- Response JSON Object:
code (string) – Language code
direction (string) – Text direction
plural (object) – Object of language plural information
aliases (array) – Array of aliases for language
- Request JSON Object:
population (int) – Number of speakers
Example JSON data:
{ "code": "en", "direction": "ltr", "name": "English", "population": 159034349015, "plural": { "id": 75, "source": 0, "number": 2, "formula": "n != 1", "type": 1 }, "aliases": [ "english", "en_en", "base", "source", "eng" ], "url": "http://example.com/api/languages/en/", "web_url": "http://example.com/languages/en/", "statistics_url": "http://example.com/api/languages/en/statistics/" }
- PUT /api/languages/(string: language)/¶
Changes the language parameters.
- Parameters:
language (string) – Language’s code
- Request JSON Object:
name (string) – Language name
direction (string) – Text direction
population (int) – Number of speakers
plural (object) – Language plural details
- PATCH /api/languages/(string: language)/¶
Changes the language parameters.
- Parameters:
language (string) – Language’s code
- Request JSON Object:
name (string) – Language name
direction (string) – Text direction
population (int) – Number of speakers
plural (object) – Language plural details
- DELETE /api/languages/(string: language)/¶
Deletes the language.
- Parameters:
language (string) – Language’s code
- GET /api/languages/(string: language)/statistics/¶
Returns statistics for a language.
- Parameters:
language (string) – Language code
See also
Returned attributes are described in Statistics.
Projects¶
- GET /api/projects/¶
Returns a list of all projects.
See also
Project object attributes are documented at
GET /api/projects/(string:project)/
.
- POST /api/projects/¶
Creates a new project.
- Parameters:
name (string) – Project name
slug (string) – Project slug
web (string) – Project website
- GET /api/projects/(string: project)/¶
Returns information about a project.
- Parameters:
project (string) – Project URL slug
- Response JSON Object:
name (string) – project name
slug (string) – project slug
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/
changes_list_url (string) – URL to changes list; see
GET /api/projects/(string:project)/changes/
credits_url (string) – URL to list contributor credits; see
GET /api/projects/(string:project)/credits/
translation_review (boolean) – Enable reviews
source_review (boolean) – Enable source reviews
set_language_team (boolean) – Set 「Language-Team」 header
enable_hooks (boolean) – Enable hooks
instructions (string) – Translation instructions
language_aliases (string) – Language aliases
Example JSON data:
{ "name": "Hello", "slug": "hello", "url": "http://example.com/api/projects/hello/", "web": "https://weblate.org/", "web_url": "http://example.com/projects/hello/" }
- PATCH /api/projects/(string: project)/¶
Added in version 4.3.
Edit a project by a PATCH request.
- Parameters:
project (string) – Project URL slug
component (string) – Component URL slug
- PUT /api/projects/(string: project)/¶
Added in version 4.3.
Edit a project by a PUT request.
- Parameters:
project (string) – Project URL slug
- DELETE /api/projects/(string: project)/¶
Deletes a project.
- Parameters:
project (string) – Project URL slug
- GET /api/projects/(string: project)/changes/¶
Returns a list of project changes. This is essentially a project scoped
GET /api/changes/
accepting same params.- Parameters:
project (string) – Project URL slug
- Response JSON Object:
results (array) – array of component objects; see
GET /api/changes/(int:id)/
- GET /api/projects/(string: project)/file/¶
Added in version 5.5.
Downloads all available translations associated with the project as an archive file using the requested format and language.
- Parameters:
project (string) – Project URL slug
- Query Parameters:
format (string) – The archive format to use; If not specified, defaults to
zip
; Supported formats:zip
andzip:CONVERSION
whereCONVERSION
is one of converters listed at Downloading translations.language_code (string) – The language code to download; If not specified, all languages are included.
- GET /api/projects/(string: project)/repository/¶
Returns information about VCS repository status. This endpoint contains only an overall summary for all repositories for the project. To get more detailed status use
GET /api/components/(string:project)/(string:component)/repository/
.- Parameters:
project (string) – Project 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
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.
- Parameters:
project (string) – Project URL slug
- Request JSON Object:
operation (string) – Operation to perform: one of
push
,pull
,commit
,reset
,cleanup
,file-sync
,file-scan
- Response JSON Object:
result (boolean) – result of the operation
CURL example:
curl \ -d operation=pull \ -H "Authorization: Token TOKEN" \ http://example.com/api/projects/hello/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 a list of translation components in the given project.
- Parameters:
project (string) – Project URL slug
- Response JSON Object:
results (array) – array of component objects; see
GET /api/components/(string:project)/(string:component)/
- POST /api/projects/(string: project)/components/¶
Changed in version 4.3: The
zipfile
anddocfile
parameters are now accepted for VCS-less components, see Local files.Changed in version 4.6: The cloned repositories are now automatically shared within a project using Weblate internal URLs. Use
disable_autoshare
to turn off this.Creates translation components in the given project.
Hint
Use Weblate internal URLs when creating multiple components from a single VCS repository.
Note
Most of the component creation happens in the background. Check the
task_url
attribute of created component and follow the progress there.- Parameters:
project (string) – Project URL slug
- Form Parameters:
file zipfile – ZIP file to upload into Weblate for translations initialization
file docfile – Document to translate
boolean disable_autoshare – Disables automatic repository sharing via Weblate internal URLs.
- Request JSON Object:
object – Component parameters, see
GET /api/components/(string:project)/(string:component)/
- Response JSON Object:
result (object) – Created component object; see
GET /api/components/(string:project)/(string:component)/
JSON can not be used when uploading the files using the
zipfile
anddocfile
parameters. The data has to be uploaded as multipart/form-data.CURL form request example:
curl \ --form docfile=@strings.html \ --form name=Weblate \ --form slug=weblate \ --form file_format=html \ --form new_lang=add \ -H "Authorization: Token TOKEN" \ http://example.com/api/projects/hello/components/
CURL JSON request example:
curl \ --data-binary '{ "branch": "main", "file_format": "po", "filemask": "po/*.po", "name": "Weblate", "slug": "weblate", "repo": "https://github.com/WeblateOrg/hello.git", "template": "", "new_base": "po/hello.pot", "vcs": "git" }' \ -H "Content-Type: application/json" \ -H "Authorization: Token TOKEN" \ http://example.com/api/projects/hello/components/
JSON request to create a new component from Git:
POST /api/projects/hello/components/ HTTP/1.1 Host: example.com Accept: application/json Content-Type: application/json Authorization: Token TOKEN Content-Length: 20 { "branch": "main", "file_format": "po", "filemask": "po/*.po", "name": "Weblate", "slug": "weblate", "repo": "https://github.com/WeblateOrg/hello.git", "template": "", "new_base": "po/hello.pot", "vcs": "git" }
JSON request to create a new component from another one:
POST /api/projects/hello/components/ HTTP/1.1 Host: example.com Accept: application/json Content-Type: application/json Authorization: Token TOKEN Content-Length: 20 { "file_format": "po", "filemask": "po/*.po", "name": "Weblate", "slug": "weblate", "repo": "weblate://weblate/hello", "template": "", "new_base": "po/hello.pot", "vcs": "git" }
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 { "branch": "main", "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", "population": 159034349015, "name": "English", "url": "http://example.com/api/languages/en/", "web_url": "http://example.com/languages/en/" }, "url": "http://example.com/api/projects/hello/", "web": "https://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/projects/(string: project)/languages/¶
Returns paginated statistics for all languages within a project.
- Parameters:
project (string) – Project URL slug
- Response JSON Object:
results (array) – array of translation statistics objects
language (string) – language name
code (string) – language code
total (int) – total number of strings
translated (int) – number of translated strings
translated_percent (float) – percentage of translated strings
total_words (int) – total number of words
translated_words (int) – number of translated words
words_percent (float) – percentage of translated words
- GET /api/projects/(string: project)/statistics/¶
Returns statistics for a project.
- Parameters:
project (string) – Project URL slug
See also
Returned attributes are described in Statistics.
- GET /api/projects/(string: project)/categories/¶
Added in version 5.0: Returns categories for a project. See
GET /api/categories/(int:id)/
for field definitions.- param project:
Project URL slug
- type project:
string
- GET /api/projects/(string: project)/labels/¶
Added in version 5.3: Returns labels for a project.
- param project:
Project URL slug
- type project:
string
- >json int id:
ID of the label
- >json string name:
name of the label
- >json string color:
color of the label
- POST /api/projects/(string: project)/labels/¶
Added in version 5.3: Creates a label for a project.
- param project:
Project URL slug
- type project:
string
- <json string name:
name of the label
- <json string color:
color of the label
- GET /api/projects/(string: project)/credits/¶
Returns contributor credits for a project.
Added in version 5.7.
- Parameters:
project (string) – Project URL slug
start (date) – Lower-bound ISO 8601 timestamp (mandatory)
end (date) – Upper-bound ISO 8601 timestamp (mandatory)
lang (source_language) – Language code to search for
- Response JSON Object:
email (string) – Email of the contributor
full_name (string) – Full name of the contributor
change_count (string) – Number of changes done in the time range
Components¶
Hint
Use POST /api/projects/(string:project)/components/
to create new components.
- GET /api/components/¶
Returns a list of translation components.
See also
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:
project (object) – the translation project; see
GET /api/projects/(string:project)/
name (string) – Component name
slug (string) – Component slug
vcs (string) – Version control system
linked_component (string) – component whose repository is linked via Weblate internal URLs
repo (string) – Source code repository, this is the actual repository URL even when Weblate internal URLs are used, use
linked_component
to detect this situationgit_export (string) – Exported repository URL
branch (string) – Repository branch, this is the actual repository branch even when Weblate internal URLs are used
push (string) – Repository push URL, this is the actual repository URL even when Weblate internal URLs are used
push_branch (string) – Push branch, this is the actual repository branch even when Weblate internal URLs are used
filemask (string) – File mask
template (string) – Monolingual base language file
edit_template (string) – Edit base file
intermediate (string) – Intermediate language file
new_base (string) – Template for new translations
file_format (string) – File format
license (string) – Translation license
agreement (string) – Contributor agreement
new_lang (string) – Adding new translation
language_code_style (string) – Language code style
source_language (object) – source language object; see
GET /api/languages/(string:language)/
check_flags (string) – Translation flags
priority (string) – Priority
enforced_checks (string) – Enforced checks
restricted (string) – Restricted access
repoweb (string) – Repository browser
report_source_bugs (string) – Source string bug reporting address
merge_style (string) – Merge style
commit_message (string) – Commit, add, delete, merge, add-on, and merge request messages
add_message (string) – Commit, add, delete, merge, add-on, and merge request messages
delete_message (string) – Commit, add, delete, merge, add-on, and merge request messages
merge_message (string) – Commit, add, delete, merge, add-on, and merge request messages
addon_message (string) – Commit, add, delete, merge, add-on, and merge request messages
pull_message (string) – Commit, add, delete, merge, add-on, and merge request messages
allow_translation_propagation (string) – Allow translation propagation
enable_suggestions (string) – Enable suggestions
suggestion_voting (string) – Suggestion voting
suggestion_autoaccept (string) – Automatically accept suggestions
push_on_commit (string) – Push on commit
locked (bool) – Whether component is locked, this field is read-only; see
GET /api/components/(string:project)/(string:component)/lock/
commit_pending_age (string) – Age of changes to commit
auto_lock_error (string) – Lock on error
language_regex (string) – Language filter
variant_regex (string) – Variants regular expression
is_glossary (bool) – Use as a glossary
glossary_color (string) – Glossary color
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 status; see
GET /api/components/(string:project)/(string:component)/lock/
changes_list_url (string) – URL to changes list; see
GET /api/components/(string:project)/(string:component)/changes/
task_url (string) – URL to a background task (if any); see
GET /api/tasks/(str:uuid)/
credits_url (string) – URL to list contributor credits; see
GET /api/components/(string:project)/(string:component)/credits/
Example JSON data:
{ "branch": "main", "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", "population": 159034349015, "name": "English", "url": "http://example.com/api/languages/en/", "web_url": "http://example.com/languages/en/" }, "url": "http://example.com/api/projects/hello/", "web": "https://weblate.org/", "web_url": "http://example.com/projects/hello/" }, "source_language": { "code": "en", "direction": "ltr", "population": 159034349015, "name": "English", "url": "http://example.com/api/languages/en/", "web_url": "http://example.com/languages/en/" }, "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/" }
- PATCH /api/components/(string: project)/(string: component)/¶
Edit a component by a PATCH request.
- Parameters:
project (string) – Project URL slug
component (string) – Component URL slug
source_language (string) – Project source language code (optional)
- Request JSON Object:
name (string) – name of component
slug (string) – slug of component
repo (string) – VCS repository URL
CURL example:
curl \ --data-binary '{"name": "new name"}' \ -H "Content-Type: application/json" \ -H "Authorization: Token TOKEN" \ PATCH http://example.com/api/projects/hello/components/
JSON request example:
PATCH /api/projects/hello/components/ HTTP/1.1 Host: example.com Accept: application/json Content-Type: application/json Authorization: Token TOKEN Content-Length: 20 { "name": "new name" }
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 { "branch": "main", "file_format": "po", "filemask": "po/*.po", "git_export": "", "license": "", "license_url": "", "name": "new name", "slug": "weblate", "project": { "name": "Hello", "slug": "hello", "source_language": { "code": "en", "direction": "ltr", "population": 159034349015, "name": "English", "url": "http://example.com/api/languages/en/", "web_url": "http://example.com/languages/en/" }, "url": "http://example.com/api/projects/hello/", "web": "https://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/" }
- PUT /api/components/(string: project)/(string: component)/¶
Edit a component by a PUT request.
- Parameters:
project (string) – Project URL slug
component (string) – Component URL slug
- Request JSON Object:
branch (string) – VCS repository branch
file_format (string) – file format of translations
filemask (string) – mask of translation files in the repository
name (string) – name of component
slug (string) – slug of component
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
- DELETE /api/components/(string: project)/(string: component)/¶
Deletes a component.
- Parameters:
project (string) – Project URL slug
component (string) – Component URL slug
- GET /api/components/(string: project)/(string: component)/changes/¶
Returns a list of component changes. This is essentially a component scoped
GET /api/changes/
accepting same params.- Parameters:
project (string) – Project URL slug
component (string) – Component URL slug
- Response JSON Object:
results (array) – array of component objects; see
GET /api/changes/(int:id)/
- GET /api/components/(string: project)/(string: component)/file/¶
Added in version 4.9.
Downloads all available translations associated with the component as an archive file using the requested format.
- Parameters:
project (string) – Project URL slug
component (string) – Component URL slug
- Query Parameters:
format (string) – The archive format to use; If not specified, defaults to
zip
; Supported formats:zip
andzip:CONVERSION
whereCONVERSION
is one of converters listed at Downloading translations.
- GET /api/components/(string: project)/(string: component)/screenshots/¶
Returns a list of component screenshots.
- Parameters:
project (string) – Project URL slug
component (string) – Component URL slug
- Response JSON Object:
results (array) – array of component screenshots; see
GET /api/screenshots/(int:id)/
- GET /api/components/(string: project)/(string: component)/lock/¶
Returns component lock status.
- Parameters:
project (string) – Project URL slug
component (string) – Component URL slug
- Response JSON Object:
locked (boolean) – whether component is locked for updates
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/
.- Parameters:
project (string) – Project URL slug
component (string) – Component URL slug
- Request JSON Object:
lock – Boolean whether to lock or not.
CURL example:
curl \ -d lock=true \ -H "Authorization: Token TOKEN" \ http://example.com/api/components/hello/weblate/repository/
JSON request example:
POST /api/components/hello/weblate/repository/ HTTP/1.1 Host: example.com Accept: application/json Content-Type: application/json Authorization: Token TOKEN Content-Length: 20 {"lock": true}
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 {"locked":true}
- 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 (string) – Remote commit information
status (string) – VCS repository status as reported by VCS
merge_failure – Text describing merge failure or null if there is none
- POST /api/components/(string: project)/(string: component)/repository/¶
Performs the given operation on a VCS repository.
See
POST /api/projects/(string:project)/repository/
for documentation.- Parameters:
project (string) – Project URL slug
component (string) – Component URL slug
- Request JSON Object:
operation (string) – Operation to perform: one of
push
,pull
,commit
,reset
,cleanup
- Response JSON Object:
result (boolean) – result of the operation
CURL example:
curl \ -d operation=pull \ -H "Authorization: Token TOKEN" \ http://example.com/api/components/hello/weblate/repository/
JSON request example:
POST /api/components/hello/weblate/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/components/(string: project)/(string: component)/monolingual_base/¶
Downloads base file for monolingual translations.
- Parameters:
project (string) – Project URL slug
component (string) – Component URL slug
- 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
- GET /api/components/(string: project)/(string: component)/translations/¶
Returns a list of translation objects in the given component.
- Parameters:
project (string) – Project URL slug
component (string) – Component URL slug
- Response JSON Object:
results (array) – array of translation objects; see
GET /api/translations/(string:project)/(string:component)/(string:language)/
- POST /api/components/(string: project)/(string: component)/translations/¶
Creates new translation in the given component.
- Parameters:
project (string) – Project URL slug
component (string) – Component URL slug
- Request JSON Object:
language_code (string) – translation language code; see
GET /api/languages/(string:language)/
- Response JSON Object:
result (object) – new translation object created
CURL example:
curl \ -d language_code=cs \ -H "Authorization: Token TOKEN" \ http://example.com/api/projects/hello/components/
JSON request example:
POST /api/projects/hello/components/ HTTP/1.1 Host: example.com Accept: application/json Content-Type: application/json Authorization: Token TOKEN Content-Length: 20 {"language_code": "cs"}
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 { "failing_checks": 0, "failing_checks_percent": 0, "failing_checks_words": 0, "filename": "po/cs.po", "fuzzy": 0, "fuzzy_percent": 0.0, "fuzzy_words": 0, "have_comment": 0, "have_suggestion": 0, "is_template": false, "is_source": false, "language": { "code": "cs", "direction": "ltr", "population": 1303174280 "name": "Czech", "url": "http://example.com/api/languages/cs/", "web_url": "http://example.com/languages/cs/" }, "language_code": "cs", "id": 125, "last_author": null, "last_change": null, "share_url": "http://example.com/engage/hello/cs/", "total": 4, "total_words": 15, "translate_url": "http://example.com/translate/hello/weblate/cs/", "translated": 0, "translated_percent": 0.0, "translated_words": 0, "url": "http://example.com/api/translations/hello/weblate/cs/", "web_url": "http://example.com/projects/hello/weblate/cs/" }
- GET /api/components/(string: project)/(string: component)/statistics/¶
Returns paginated statistics for all translations within component.
- Parameters:
project (string) – Project URL slug
component (string) – Component URL slug
See also
Returned attributes are described in Statistics.
- GET /api/components/(string: project)/(string: component)/links/¶
Returns projects linked with a component.
Added in version 4.5.
- Parameters:
project (string) – Project URL slug
component (string) – Component URL slug
- Response JSON Object:
projects (array) – associated projects; see
GET /api/projects/(string:project)/
- POST /api/components/(string: project)/(string: component)/links/¶
Associate project with a component.
Added in version 4.5.
- Parameters:
project (string) – Project URL slug
component (string) – Component URL slug
- Form Parameters:
string project_slug – Project slug
- DELETE /api/components/(string: project)/(string: component)/links/(string: project_slug)/¶
Remove association of a project with a component.
Added in version 4.5.
- Parameters:
project (string) – Project URL slug
component (string) – Component URL slug
project_slug (string) – Slug of the project to remove
- GET /api/components/(string: project)/(string: component)/credits/¶
Returns contributor credits for a project.
Added in version 5.7.
- Parameters:
project (string) – Project URL slug
start (date) – Lower-bound ISO 8601 timestamp (mandatory)
end (date) – Upper-bound ISO 8601 timestamp (mandatory)
lang (source_language) – Language code to search for
- Response JSON Object:
email (string) – Email of the contributor
full_name (string) – Full name of the contributor
change_count (string) – Number of changes done in the time range
Translations¶
- GET /api/translations/¶
Returns a list of translations.
See also
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 a 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 strings failing checks
failing_checks_percent (float) – percentage of strings failing checks
failing_checks_words (int) – number of words with failing checks
filename (string) – translation filename
fuzzy (int) – number of fuzzy (marked for edit) strings
fuzzy_percent (float) – percentage of fuzzy (marked for edit) strings
fuzzy_words (int) – number of words in fuzzy (marked for edit) strings
have_comment (int) – number of strings with comment
have_suggestion (int) – number of strings with suggestion
is_template (boolean) – whether the translation has a 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) – revision hash for the file
share_url (string) – URL for sharing leading to engagement page
total (int) – total number of strings
total_words (int) – total number of words
translate_url (string) – URL for translating
translated (int) – number of translated strings
translated_percent (float) – percentage of translated strings
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/
changes_list_url (string) – URL to changes list; see
GET /api/translations/(string:project)/(string:component)/(string:language)/changes/
units_list_url (string) – URL to strings list; see
GET /api/translations/(string:project)/(string:component)/(string:language)/units/
Example JSON data:
{ "component": { "branch": "main", "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", "population": 159034349015, "name": "English", "url": "http://example.com/api/languages/en/", "web_url": "http://example.com/languages/en/" }, "url": "http://example.com/api/projects/hello/", "web": "https://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", "population": 1303174280 "name": "Czech", "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/" }
- DELETE /api/translations/(string: project)/(string: component)/(string: language)/¶
Deletes a translation.
- Parameters:
project (string) – Project URL slug
component (string) – Component URL slug
language (string) – Translation language code
- GET /api/translations/(string: project)/(string: component)/(string: language)/changes/¶
Returns a list of translation changes. This is essentially a translations-scoped
GET /api/changes/
accepting the same parameters.- Parameters:
project (string) – Project URL slug
component (string) – Component URL slug
language (string) – Translation language code
- Response JSON Object:
results (array) – array of component objects; see
GET /api/changes/(int:id)/
- GET /api/translations/(string: project)/(string: component)/(string: language)/units/¶
Returns a list of translation units.
- Parameters:
project (string) – Project URL slug
component (string) – Component URL slug
language (string) – Translation language code
q (string) – Search query string Searching (optional)
- Response JSON Object:
results (array) – array of component objects; see
GET /api/units/(int:id)/
- POST /api/translations/(string: project)/(string: component)/(string: language)/units/¶
Add new unit.
- Parameters:
project (string) – Project URL slug
component (string) – Component URL slug
language (string) – Translation language code
- Request JSON Object:
key (string) – Monolingual translations: Key of translation unit
value (array) – Monolingual translations: Source strings (use single string if not creating plural)
context (string) – Bilingual translations: Context of a translation unit
source (array) – Bilingual translations: Source strings (use single string if not creating plural)
target (array) – Bilingual translations: Target strings (use single string if not creating plural)
state (int) – String state; see
GET /api/units/(int:id)/
- Response JSON Object:
unit (object) – newly created unit; see
GET /api/units/(int:id)/
See also
- POST /api/translations/(string: project)/(string: component)/(string: language)/autotranslate/¶
Trigger automatic translation.
- Parameters:
project (string) – Project URL slug
component (string) – Component URL slug
language (string) – Translation language code
- Request JSON Object:
mode (string) – Automatic translation mode
filter_type (string) – Automatic translation filter type
auto_source (string) – Automatic translation source -
mt
orothers
component (string) – Turn on contribution to shared translation memory for the project to get access to additional components.
engines (array) – Machine translation engines
threshold (string) – Score threshold
- GET /api/translations/(string: project)/(string: component)/(string: language)/file/¶
Download current translation file as it is stored in the VCS (without the
format
parameter) or converted to another format (see Downloading translations).Note
This API endpoint uses different logic for output than rest of API as it operates on whole file rather than on data. Set of accepted
format
parameter differs and without such parameter you get translation file as stored in VCS.- Response Headers:
Last-Modified – Timestamp of last change to this file.
- Request Headers:
If-Modified-Since – Skips response if the file has not been modified since that time.
- Query Parameters:
format – File format to use; if not specified no format conversion happens; see Downloading translations for supported formats
q (string) – Filter downloaded strings, see Search Page, only applicable when conversion is in place (
format
is specified).
- Parameters:
project (string) – Project URL slug
component (string) – Component URL slug
language (string) – Translation language code
- 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
- Form Parameters:
string conflicts – How to deal with conflicts (
ignore
,replace-translated
orreplace-approved
), see Conflicts handlingfile file – Uploaded file
string email – Author e-mail
string author – Author name
string method – Upload method (
translate
,approve
,suggest
,fuzzy
,replace
,source
,add
), see Import methodsstring fuzzy – Fuzzy (marked for edit) strings processing (empty,
process
,approve
)
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
- 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.- Parameters:
project (string) – Project URL slug
component (string) – Component URL slug
language (string) – Translation language code
- Request JSON Object:
operation (string) – Operation to perform: one of
push
,pull
,commit
,reset
,cleanup
- Response JSON Object:
result (boolean) – result of the operation
- GET /api/translations/(string: project)/(string: component)/(string: language)/statistics/¶
Returns detailed translation statistics.
- Parameters:
project (string) – Project URL slug
component (string) – Component URL slug
language (string) – Translation language code
See also
Returned attributes are described in Statistics.
Memory¶
Added in version 4.14.
- GET /api/memory/¶
Returns a list of memory results.
- DELETE /api/memory/(int: memory_object_id)/¶
Deletes a memory object
- Parameters:
memory_object_id – Memory Object ID
Units¶
A unit is a single piece of a translation which pairs a source string with a
corresponding translated string and also contains some related metadata. The
term is derived from the translate.storage.base.TranslationUnit
in Translate Toolkit
and XLIFF.
- GET /api/units/¶
Returns list of translation units.
- Parameters:
q (string) – Search query string Searching (optional)
See also
Unit object attributes are documented at
GET /api/units/(int:id)/
.
- GET /api/units/(int: id)/¶
Changed in version 4.3: The
target
andsource
are now arrays to properly handle plural strings.Returns information about translation unit.
- Parameters:
id (int) – Unit ID
- Response JSON Object:
translation (string) – URL of a related translation object
source (array) – source string
previous_source (string) – previous source string used for fuzzy matching
target (array) – target string
id_hash (string) – unique identifier of the unit
content_hash (string) – unique identifier of the source string
location (string) – location of the unit in source code
context (string) – translation unit context
note (string) – translation unit note
flags (string) – translation unit flags
labels (array) – translation unit labels, available on source units
state (int) – unit state, 0 - untranslated, 10 - needs editing, 20 - translated, 30 - approved, 100 - read only
fuzzy (boolean) – whether the unit is fuzzy or marked for review
translated (boolean) – whether the unit is translated
approved (boolean) – whether the translation is approved
position (int) – unit position in translation file
has_suggestion (boolean) – whether the unit has suggestions
has_comment (boolean) – whether the unit has comments
has_failing_check (boolean) – whether the unit has failing checks
num_words (int) – number of source words
priority (int) – translation priority; 100 is default
id (int) – unit identifier
explanation (string) – String explanation, available on source units, see Additional info on source strings
extra_flags (string) – Additional string flags, available on source units, see Customizing behavior using flags
web_url (string) – URL where the unit can be edited
source_unit (string) – Source unit link; see
GET /api/units/(int:id)/
pending (boolean) – whether the unit is pending for write
timestamp (timestamp) – string age
last_updated (timestamp) – last string update
- PATCH /api/units/(int: id)/¶
Added in version 4.3.
Performs partial update on translation unit.
- Parameters:
id (int) – Unit ID
- Request JSON Object:
state (int) – unit state, 0 - untranslated, 10 - needs editing, 20 - translated, 30 - approved (need review workflow enabled, see Dedicated reviewers)
target (array) – target string
explanation (string) – String explanation, available on source units, see Additional info on source strings
extra_flags (string) – Additional string flags, available on source units, see Customizing behavior using flags
labels (array) – labels, available on source units
- PUT /api/units/(int: id)/¶
Added in version 4.3.
Performs full update on translation unit.
- Parameters:
id (int) – Unit ID
- Request JSON Object:
state (int) – unit state, 0 - untranslated, 10 - needs editing, 20 - translated, 30 - approved (need review workflow enabled, see Dedicated reviewers)
target (array) – target string
explanation (string) – String explanation, available on source units, see Additional info on source strings
extra_flags (string) – Additional string flags, available on source units, see Customizing behavior using flags
labels (array) – labels, available on source units
- DELETE /api/units/(int: id)/¶
Added in version 4.3.
Deletes a translation unit.
- Parameters:
id (int) – Unit ID
Changes¶
- GET /api/changes/¶
Changed in version 4.1: Filtering of changes was introduced in the 4.1 release.
Returns a list of translation changes.
See also
Change object attributes are documented at
GET /api/changes/(int:id)/
.- Query Parameters:
user (string) – Username of user to filters
action (int) – Action to filter, can be used several times
timestamp_after (timestamp) – ISO 8601 formatted timestamp to list changes after
timestamp_before (timestamp) – ISO 8601 formatted timestamp to list changes before
- GET /api/changes/(int: id)/¶
Returns information about translation change.
- Parameters:
id (int) – Change ID
- Response JSON Object:
unit (string) – URL of a related unit object
translation (string) – URL of a related translation object
component (string) – URL of a related component object
user (string) – URL of a related user object
author (string) – URL of a related author object
timestamp (timestamp) – event timestamp
action (int) – numeric identification of action
action_name (string) – text description of action
target (string) – event changed text
old (string) – previous text
details (object) – additional details about the change
id (int) – change identifier
Screenshots¶
- GET /api/screenshots/¶
Returns a list of screenshot string information.
See also
Screenshot object attributes are documented at
GET /api/screenshots/(int:id)/
.
- GET /api/screenshots/(int: id)/¶
Returns information about screenshot information.
- Parameters:
id (int) – Screenshot ID
- Response JSON Object:
name (string) – name of a screenshot
component (string) – URL of a related component object
file_url (string) – URL to download a file; see
GET /api/screenshots/(int:id)/file/
units (array) – link to associated source string information; see
GET /api/units/(int:id)/
- GET /api/screenshots/(int: id)/file/¶
Download the screenshot image.
- Parameters:
id (int) – Screenshot ID
- POST /api/screenshots/(int: id)/file/¶
Replace screenshot image.
- Parameters:
id (int) – Screenshot ID
- Form Parameters:
file image – Uploaded file
CURL example:
curl -X POST \ -F image=@image.png \ -H "Authorization: Token TOKEN" \ http://example.com/api/screenshots/1/file/
- POST /api/screenshots/(int: id)/units/¶
Associate source string with screenshot.
- Parameters:
id (int) – Screenshot ID
- Form Parameters:
string unit_id – Unit ID
- Response JSON Object:
name (string) – name of a screenshot
translation (string) – URL of a related translation object
file_url (string) – URL to download a file; see
GET /api/screenshots/(int:id)/file/
units (array) – link to associated source string information; see
GET /api/units/(int:id)/
- DELETE /api/screenshots/(int: id)/units/(int: unit_id)¶
Remove source string association with screenshot.
- Parameters:
id (int) – Screenshot ID
unit_id – Source string unit ID
- POST /api/screenshots/¶
Creates a new screenshot.
- Form Parameters:
file image – Uploaded file
string name – Screenshot name
string project_slug – Project slug
string component_slug – Component slug
string language_code – Language code
- Response JSON Object:
name (string) – name of a screenshot
component (string) – URL of a related component object
file_url (string) – URL to download a file; see
GET /api/screenshots/(int:id)/file/
units (array) – link to associated source string information; see
GET /api/units/(int:id)/
- PATCH /api/screenshots/(int: id)/¶
Edit partial information about screenshot.
- Parameters:
id (int) – Screenshot ID
- Response JSON Object:
name (string) – name of a screenshot
component (string) – URL of a related component object
file_url (string) – URL to download a file; see
GET /api/screenshots/(int:id)/file/
units (array) – link to associated source string information; see
GET /api/units/(int:id)/
- PUT /api/screenshots/(int: id)/¶
Edit full information about screenshot.
- Parameters:
id (int) – Screenshot ID
- Response JSON Object:
name (string) – name of a screenshot
component (string) – URL of a related component object
file_url (string) – URL to download a file; see
GET /api/screenshots/(int:id)/file/
units (array) – link to associated source string information; see
GET /api/units/(int:id)/
- DELETE /api/screenshots/(int: id)/¶
Delete screenshot.
- Parameters:
id (int) – Screenshot ID
Add-ons¶
Added in version 4.4.1.
- GET /api/addons/¶
Returns a list of add-ons.
See also
Add-on object attributes are documented at
GET /api/addons/(int:id)/
.
- GET /api/addons/(int: id)/¶
Returns information about add-on information.
- Parameters:
id (int) – Add-on ID
- Response JSON Object:
name (string) – name of an add-on
component (string) – URL of a related component object
configuration (object) – Optional add-on configuration
See also
- POST /api/components/(string: project)/(string: component)/addons/¶
Creates a new add-on.
- Parameters:
project_slug (string) – Project slug
component_slug (string) – Component slug
- Request JSON Object:
name (string) – name of an add-on
configuration (object) – Optional add-on configuration
- PATCH /api/addons/(int: id)/¶
Edit partial information about add-on.
- Parameters:
id (int) – Add-on ID
- Response JSON Object:
configuration (object) – Optional add-on configuration
- PUT /api/addons/(int: id)/¶
Edit full information about add-on.
- Parameters:
id (int) – Add-on ID
- Response JSON Object:
configuration (object) – Optional add-on configuration
- DELETE /api/addons/(int: id)/¶
Delete add-on.
- Parameters:
id (int) – Add-on ID
Component lists¶
Added in version 4.0.
- GET /api/component-lists/¶
Returns a list of component lists.
See also
Component list object attributes are documented at
GET /api/component-lists/(str:slug)/
.
- GET /api/component-lists/(str: slug)/¶
Returns information about component list.
- Parameters:
slug (string) – Component list slug
- Response JSON Object:
name (string) – name of a component list
slug (string) – slug of a component list
show_dashboard (boolean) – whether to show it on a dashboard
components (array) – link to associated components; see
GET /api/components/(string:project)/(string:component)/
auto_assign (array) – automatic assignment rules
- PUT /api/component-lists/(str: slug)/¶
Changes the component list parameters.
- Parameters:
slug (string) – Component list slug
- Request JSON Object:
name (string) – name of a component list
slug (string) – slug of a component list
show_dashboard (boolean) – whether to show it on a dashboard
- PATCH /api/component-lists/(str: slug)/¶
Changes the component list parameters.
- Parameters:
slug (string) – Component list slug
- Request JSON Object:
name (string) – name of a component list
slug (string) – slug of a component list
show_dashboard (boolean) – whether to show it on a dashboard
- DELETE /api/component-lists/(str: slug)/¶
Deletes the component list.
- Parameters:
slug (string) – Component list slug
- GET /api/component-lists/(str: slug)/components/¶
Added in version 5.0.1: List components in a component list.
- param slug:
Component list slug
- type slug:
string
- form string component_id:
Component ID
- >json array results:
array of component objects; see
GET /api/components/(string:project)/(string:component)/
- POST /api/component-lists/(str: slug)/components/¶
Associate component with a component list.
- Parameters:
slug (string) – Component list slug
- Form Parameters:
string component_id – Component ID
- DELETE /api/component-lists/(str: slug)/components/(str: component_slug)¶
Disassociate a component from the component list.
- Parameters:
slug (string) – Component list slug
component_slug (string) – Component slug
Glossary¶
Changed in version 4.5: Glossaries are now stored as regular components, translations and strings, please use respective API instead.
Tasks¶
Added in version 4.4.
- GET /api/tasks/¶
Listing of the tasks is currently not available.
- GET /api/tasks/(str: uuid)/¶
Returns information about a task.
- Parameters:
uuid (string) – Task UUID
- Response JSON Object:
completed (boolean) – Whether the task has completed
progress (int) – Task progress in percent
result (object) – Task result or progress details
log (string) – Task log
Statistics¶
- GET /api/(str: object)/statistics/¶
There are several statistics endpoints for objects and all of them contain same structure.
- Parameters:
object (string) – URL path
- Response JSON Object:
total (int) – total number of strings
total_words (int) – total number of words
total_chars (int) – total number of characters
last_change (timestamp) – date of last change
translated (int) – number of translated strings
translated_percent (float) – percentage of translated strings
translated_words (int) – number of translated words
translated_words_percent (float) – percentage of translated words
translated_chars (int) – number of translated characters
translated_chars_percent (float) – percentage of translated characters
fuzzy (int) – number of fuzzy (marked for edit) strings
fuzzy_words (int) – number of fuzzy (marked for edit) words
fuzzy_chars (int) – number of fuzzy (marked for edit) characters
fuzzy_percent (float) – percentage of fuzzy (marked for edit) strings
fuzzy_words_percent (float) – percentage of fuzzy (marked for edit) words
fuzzy_chars_percent (float) – percentage of fuzzy (marked for edit) characters
failing (int) – number of failing checks
failing_percent (float) – percentage of failing checks
approved (int) – number of approved strings
approved_words (int) – number of approved words
approved_chars (int) – number of approved characters
approved_percent (float) – percentage of approved strings
approved_words_percent (float) – percentage of approved words
approved_chars_percent (float) – percentage of approved characters
readonly (int) – number of read-only strings
readonly_words (int) – number of read-only words
readonly – number of read-only characters
readonly_percent (float) – percentage of read-only strings
readonly_words_percent (float) – percentage of read-only words
readonly_char_percent (float) – percentage of read-only characters
suggestions (int) – number of strings with suggestions
comments (int) – number of strings with comments
name (string) – object name
url (string) – URL to access the object (if applicable)
url_translate (string) – URL to access the translation (if applicable)
code (string) – language code (if applicable)
See also
GET /api/languages/(string:language)/statistics/
,GET /api/projects/(string:project)/statistics/
,GET /api/categories/(int:id)/statistics/
,GET /api/components/(string:project)/(string:component)/statistics/
,GET /api/translations/(string:project)/(string:component)/(string:language)/statistics/
Metrics¶
- GET /api/metrics/¶
Returns server metrics.
Changed in version 5.6.1: Metrics can now be exposed in OpenMetrics compatible format with
?format=openmetrics
.- Response JSON Object:
units (int) – Number of units
units_translated (int) – Number of translated units
users (int) – Number of users
changes (int) – Number of changes
projects (int) – Number of projects
components (int) – Number of components
translations (int) – Number of translations
languages (int) – Number of used languages
checks (int) – Number of triggered quality checks
configuration_errors (int) – Number of configuration errors
suggestions (int) – Number of pending suggestions
celery_queues (object) – Lengths of Celery queues, see Background tasks using Celery
name (string) – Configured server name
Search¶
- GET /api/search/¶
Added in version 4.18.
Returns site-wide search results as a list. There is no pagination on the result set, only first few matches are returned for each category.
- Response JSON Object:
name (str) – Name of the matched item.
url (str) – Web URL of the matched item.
category (str) – Category of the matched item.
Categories¶
- GET /api/categories/¶
Added in version 5.0.
Lists available categories. See
GET /api/categories/(int:id)/
for field definitions.
- POST /api/categories/¶
Added in version 5.0.
Creates a new category. See
GET /api/categories/(int:id)/
for field definitions.
- GET /api/categories/(int: id)/¶
Added in version 5.0.
- Parameters:
id (int) – Category ID
- Response JSON Object:
name (str) – Name of category.
slug (str) – Slug of category.
project (str) – Link to a project.
category (str) – Link to a parent category.
- PATCH /api/categories/(int: id)/¶
Added in version 5.0: Edit partial information about category.
- param id:
Category ID
- type id:
int
- >json object configuration:
Optional category configuration
- PUT /api/categories/(int: id)/¶
Added in version 5.0: Edit full information about category.
- param id:
Category ID
- type id:
int
- >json object configuration:
Optional category configuration
- DELETE /api/categories/(int: id)/¶
Added in version 5.0: Delete category.
- param id:
Category ID
- type id:
int
- GET /api/categories/(int: id)/statistics/¶
Added in version 5.5.
Returns statistics for a category.
- Parameters:
project (int) – Category id
See also
Returned attributes are described in Statistics.
Notification hooks¶
Notification hooks allow external applications to notify Weblate that the VCS repository has been updated.
You can use repository endpoints for projects, components and translations to
update individual repositories; see
POST /api/projects/(string:project)/repository/
for documentation.
- GET /hooks/update/(string: project)/(string: component)/¶
Deprecated since version 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)/¶
Deprecated since version 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.
Note
GitHub includes direct support for notifying Weblate: enable Weblate service hook in repository settings and set the URL to the URL of your Weblate installation.
See also
- Automatically receiving changes from GitHub
For instruction on setting up GitHub integration
- https://docs.github.com/en/get-started/customizing-your-github-workflow/exploring-integrations/about-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.
See also
- Automatically receiving changes from GitLab
For instruction on setting up GitLab integration
- https://docs.gitlab.com/ee/user/project/integrations/webhooks.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.
See also
- Automatically receiving changes from Bitbucket
For instruction on setting up Bitbucket integration
- https://support.atlassian.com/bitbucket-cloud/docs/manage-webhooks/
Generic information about Bitbucket Webhooks
ENABLE_HOOKS
For enabling hooks for whole Weblate
- POST /hooks/pagure/¶
Special hook for handling Pagure notifications and automatically updating matching components.
See also
- Automatically receiving changes from Pagure
For instruction on setting up Pagure integration
- https://docs.pagure.org/pagure/usage/using_webhooks.html
Generic information about Pagure Webhooks
ENABLE_HOOKS
For enabling hooks for whole Weblate
- POST /hooks/azure/¶
Special hook for handling Azure DevOps notifications and automatically updating matching components.
Note
Please ensure that Resource details to send is set to All, otherwise Weblate will not be able to match your Azure repository.
See also
- Automatically receiving changes from Azure Repos
For instruction on setting up Azure integration
- https://learn.microsoft.com/en-us/azure/devops/service-hooks/services/webhooks?view=azure-devops
Generic information about Azure DevOps Web Hooks
ENABLE_HOOKS
For enabling hooks for whole Weblate
- POST /hooks/gitea/¶
Special hook for handling Gitea Webhook notifications and automatically updating matching components.
See also
- Automatically receiving changes from Gitea Repos
For instruction on setting up Gitea integration
- https://docs.gitea.io/en-us/webhooks/
Generic information about Gitea Webhooks
ENABLE_HOOKS
For enabling hooks for whole Weblate
- POST /hooks/gitee/¶
Special hook for handling Gitee Webhook notifications and automatically updating matching components.
See also
- Automatically receiving changes from Gitee Repos
For instruction on setting up Gitee integration
- https://gitee.com/help/categories/40
Generic information about Gitee Webhooks
ENABLE_HOOKS
For enabling hooks for whole Weblate
Exports¶
Weblate provides various exports to allow you to further process the data.
- GET /exports/stats/(string: project)/(string: component)/¶
- Query Parameters:
format (string) – Output format: either
json
orcsv
Deprecated since version 2.6: Please use
GET /api/components/(string:project)/(string:component)/statistics/
andGET /api/translations/(string:project)/(string:component)/(string:language)/statistics/
instead; it allows access to ACL controlled projects as well.Retrieves statistics for given component in given format.
Example request:
GET /exports/stats/weblate/main/ 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 Čihař", "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/main/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/main/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/main/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.
See also