Getting started¶
Installation and requirements¶
This plugin requires Python 3.6 or above and PIP.
Install it by running:
pip install python-lokalise-api
Initializing the client¶
In order to perform API requests, you require a special token that can be obtained in your personal Lokalise profile (API tokens section).
After you’ve obtained the token, import the plugin and initialize the client:
import lokalise
client = lokalise.Client('YOUR_API_TOKEN')
Now use the client
variable to perform API requests!
You may also check the Customizing client section to learn how to set timeouts.
Initializing the client with OAuth 2 token¶
You can also send API requests with OAuth 2 tokens. To achieve that, you have to instantiate a proper class:
import lokalise
client = lokalise.OAuthClient('YOUR_OAUTH_API_TOKEN')
This class accepts the same options as a regular Client
.
Objects and models¶
Individual objects retrieved from the API (projects, contributors, translation keys etc) are represented as instances of Python classes. They are called models. Each model responds to the methods that are named after the API object attributes.
For example:
project = client.project('123.abc')
project.name # => "Sample Project"
project.description # => "This is a demo project."
order = client.order(345, 5678)
order.status # => "completed"
order.provider_slug # => "gengo"
Many resources respond to common methods: project_id
,
team_id
, user_id
, and branch
:
contributor = client.contributor('project.123.id', 456)
contributor.project_id # => 'project.123.id'
language = client.language('project.123.id', 21045)
language.branch # => 'master'
You may also fetch raw data returned by the API:
project = client.project('123.abc')
project.raw_data
Collections of resources and pagination¶
Retrieving, creating, or updating multiple objects will return a collection of objects (with individual objects represented as models).
projects = client.projects() # projects collection
To get access to the actual data, use items
:
print(projects.items)
first_project = projects.items[0]
first_project.name
first_project.description
Bulk fetches support pagination. There are two common options available:
"limit"
(defaults to100
, maximum is5000
) - number of records to display per page."page"
(defaults to1
) - page to fetch.
For example:
client.projects({"limit": 2, "page": 3}) # 2 projects per page, get the 3rd page
client.contributors('project.123', {"limit": 5}) # 5 contributors per page, get the 1st page
Collections has the following attributes (some of the attributes may be absent depending on the endpoint):
current_page
- the number of the current page.total_count
- total number of records available.page_count
- total number of pages available.limit
- number of records per page.project_id
- ID of the project that the collection belongs to.user_id
- ID of the user the collection belongs to.team_id
- ID of the team the collection belongs to.branch
- project branch that the collection was fetched from.errors
- errors that occured during the request processing. Usually this attribute is empty or absent, but it may contain a list of error messages in certain cases. For example, suppose you are creating multiple project languages, and one of the languages is incorrect. All languages with proper attributes will be created and returned as collection.errors
will contain a list of errors explaining that one of the languages has incorrect attributes.
Collections respond to the following methods:
is_last_page()
is_first_page()
has_next_page()
has_prev_page()
For example:
projects = client.projects({"limit": 2, "page": 3})
projects.is_last_page() # => True, this is the last page
projects.has_next_page() # => False, no more pages available
projects.has_prev_page() # => True, there is a previous page available
Branching¶
If you are using project branching feature,
simply add a branch name separated by semicolon to your project ID in any endpoint to access the branch.
For example, in order to access the new-feature
branch for the project with an id of 123abcdef.01
:
contributors = client.contributors('123abcdef.01:new-feature')
contributors.branch # => "new-feature"
contributors.project_id # => "123abcdef.01"
contributors.items[0].contributor_id # => 12345