Lokalise API v2 official Ruby interface
Official opinionated Ruby interface for the Lokalise API that represents returned data as Ruby objects.
Index
Getting Started
Installation and Requirements
This gem requires Ruby 2.4+ and RubyGems package manager.
Install it by running:
$ gem install ruby-lokalise-api
Initializing the Client
In order to perform API requests, you require a special token that can be obtained in your personal profile (API tokens section). Note that the owner of the token must have admin access rights.
After you've obtained the token, initialize the client:
require 'ruby-lokalise-api'
@client = Lokalise.client 'YOUR_TOKEN_HERE'
Now the @client can be used to perform API requests! Learn more about additional options in the Customizing request section.
Objects and models
Individual objects are represented as instances of Ruby classes which are called models. Each model responds to the methods that are named after the API object's attributes. This file lists all objects and their methods.
Here is an example:
project = client.project '123'
project.name
project.description
project.created_by
Many resources have common methods like project_id and branch:
webhook = client.webhook project_id, '123.abc'
webhook.project_id
webhook.branch
To get access to raw data returned by the API, use #raw_data:
project.raw_data
Models support method chaining, meaning you can fetch a resource, update and delete it in one line:
@client.project('123').update(name: 'New name').destroy
Reloading data
Most of the resources can be reloaded using the reload_data method. This method will fetch the latest data for the resource:
project = client.project '123'
# do something else...
# project might be updated via UI, so load new data:
reloaded_project = project.reload_data
# now `reloaded_project` has fresh data from the API
Collections of resources and pagination
Fetching (or creating/updating) multiple objects will return a collection of objects. To get access to the actual data, use #collection method:
project = @client.projects.collection.first # => Get the first project
project.name
Bulk fetches support pagination. There are two common parameters available:
:limit(defaults to100, maximum is5000) - number of records to display per page:page(defaults to1) - page to fetch
projects = @client.projects limit: 10, page: 3 #=> Paginate by 10 records and fetch the third page
Collections respond to the following methods:
#total_pages#total_results#results_per_page#current_page#next_page?#last_page?#prev_page?#first_page?
For example:
projects.current_page #=> 3
projects.last_page? #=> true, this is the last page and there are no more projects available
On top of that, you may easily fetch the next or the previous page of the collection by using:
#next_page#prev_page
These methods return instances of the same collection class or nil if the next/previous page is unavailable. Methods respect the parameters you've initially passed:
translations = @client.translations 'project_id', limit: 4, page: 2, disable_references: 0 # => we passed three parameters here
translations.prev_page # => will load the previous page while preserving the `limit` and `disable_references` params
Branching
If you are using project branching feature, simply add branch name separated by semicolon to your project ID in any endpoint to access the branch. For example, in order to access new-feature branch for the project with an id 123abcdef.01:
@client.files '123abcdef.01:new-feature'
Available Resources
Branches
Fetch branches
@client.branches(project_id, params = {}) # Input:
## project_id (string, required)
## params (hash)
### :page and :limit
# Output:
## Collection of comments available in the branches project
Fetch branch
@client.branch(project_id, branch_id) # Input:
## project_id (string, required)
## branch_id (string or integer, required)
# Output:
## Branch inside the given project
Create branch
@client.create_branch(project_id, params) # Input:
## project_id (string, required)
## params (hash, required):
### :name (string) - name of the branch
# Output:
## Created branch
Update branch
@client.update_branch(project_id, branch_id, params) # Input:
## project_id (string, required)
## branch_id (string or integer, required)
## params (hash, required):
### :name (string) - name of the branch
# Output:
## Updated branch
Alternatively:
branch = @client.branch('project_id', 'branch_id')
branch.update params
Delete branch
@client.destroy_branch(project_id, branch_id) # Input:
## project_id (string, required)
## branch_id (string or integer, required)
# Output:
## Hash with the project's id and "branch_deleted"=>true
Alternatively:
branch = @client.branch('project_id', 'branch_id')
branch.destroy
Merge branch
@client.merge_branch(project_id, branch_id, params) # Input:
## project_id (string, required)
## branch_id (string or integer, required)
## params (hash)
# Output:
## Hash with the project's id, "branch_merged"=>true, and branch attributes
Alternatively:
branch = @client.branch('project_id', 'branch_id')
branch.merge params
Comments
Fetch project comments
@client.project_comments(project_id, params = {}) # Input:
## project_id (string, required)
## params (hash)
### :page and :limit
# Output:
## Collection of comments available in the given project
Fetch key comments
@client.comments(project_id, key_id, params = {}) # Input:
## project_id (string, required)
## key_id (string, required)
## params (hash)
### :page and :limit
# Output:
## Collection of comments available for the specified key in the given project
Create key comments
@client.create_comments(project_id, key_id, params) # Input:
## project_id (string, required)
## key_id (string, required)
## params (array or hash, required) - contains parameter of newly created comments. Pass array of hashes to create multiple comments, or a hash to create a single comment
### :comment (string, required)
# Output:
## Newly created comment
Fetch key comment
@client.comment(project_id, key_id, comment_id) # Input:
## project_id (string, required)
## key_id (string, required)
## comment_id (string, required)
# Output:
## Comment for the key in the given project
Delete key comment
@client.destroy_comment(project_id, key_id, comment_id) # Input:
## project_id (string, required)
## key_id (string, required)
## comment_id (string, required)
# Output:
## Hash with the project's id and "comment_deleted"=>true
Alternatively:
comment = @client.comment('project_id', 'comment_id')
comment.destroy
Contributors
Fetch contributors
@client.contributors(project_id, params = {}) # Input:
## project_id (string, required)
## params (hash)
### :page and :limit
# Output:
## Collection of contributors in the given project
Fetch a single contributor
@client.contributor(project_id, contributor_id) # Input:
## project_id (string, required)
## contributor_id (string, required) - named as "user_id" in the response
# Output:
## Contributor in the given project
Create contributors
@client.create_contributors(project_id, params) # Input:
## project_id (string, required)
## params (array of hashes or hash, required) - parameters for the newly created contributors. Pass array of hashes to create multiple contributors, or a hash to create a single contributor
### :email (string, required)
### :fullname (string)
### :is_admin (boolean)
### :is_reviewer (boolean)
### :languages (array of hashes, required if "is_admin" set to false) - possible languages attributes:
#### :lang_iso (string, required)
#### :is_writable (boolean)
### :admin_rights (array)
# Output:
## Collection of newly created contributors
Update contributor
@client.update_contributor(project_id, contributor_id, params) # Input:
## project_id (string, required)
## contributor_id (string, required)
## params (hash, required)
### :is_admin (boolean)
### :is_reviewer (boolean)
### :languages (array of hashes) - possible languages attributes:
#### :lang_iso (string, required)
#### :is_writable (boolean)
### :admin_rights (array)
# Output:
## Updated contributor
Alternatively:
contributor = @client.contributor('project_id', 'contributor_id')
contributor.update(params)
Delete contributor
@client.destroy_contributor(project_id, contributor_id) # Input:
## project_id (string, required)
## contributor_id (string, required)
# Output:
## Hash with the project's id and "contributor_deleted"=>true
Alternatively:
contributor = @client.contributor('project_id', 'id')
contributor.destroy
Translation files
Fetch translation files
@client.files(project_id, params = {}) # Input:
## project_id (string, required)
## params (hash)
### :page and :limit
# Output:
## Collection of translation files available in the given project
Download translation files
Exports project files as a .zip bundle and makes them available to download (the link is valid for 12 months).
@client.download_files(project_id, params) # Input:
## project_id (string, required)
## params (hash, required)
### :format (string, required) - one of the file formats supported by Lokalise (json, xml, po etc).
### Find the list of other supported params at https://app.lokalise.com/api2docs/curl/#transition-download-files-post
# Output:
## Hash with the project id and a "bundle_url" link
Upload translation file
Starting from 9 May 2020, background uploading is the preferred method of importing translation files. Version 3 supports only asynchronous uploading. Version 2 still allows synchronous uploading but this feature will be removed in the near future.
@client.upload_file(project_id, params) # Input:
## project_id (string, required)
## params (hash, required)
### :data (string, required) - base64-encoded data (the format must be supported by Lokalise)
### :filename (string, required)
### :lang_iso (string, required)
### Find the list of other supported params at https://app.lokalise.com/api2docs/curl/#transition-upload-a-file-post
# Output:
## QueuedProcess resource
A QueuedProcess resource will be returned. This resource contains a status of the import job, process ID to manually check the status, and some other attributes:
queued_process = @client.upload_file project_id,
data: 'Base-64 encoded data... ZnI6DQogI...',
filename: 'my_file.yml',
lang_iso: 'en'
queued_process.status # => 'queued'
queued_process.process_id # => 'ff1876382b7ba81f2bb465da8f030196ec401fa6'
Your job is to periodically reload data for the queued process and check the status attribute:
reloaded_process = queued_process.reload_data # loads new data from the API
reloaded_process.status # => 'finished'
Alternatively, you may use the queued_process method:
reloaded_process = @client.queued_process project_id, queued_process.process_id
It is up to you to decide how to poll API for changes (remember that larger files will take more time to be imported), but here's a simple example:
def uploaded?(process)
5.times do # try to check the status 5 times
queued_process = queued_process.reload_data # load new data
return(true) if queued_process.status == 'finished' # return true is the upload has finished
sleep 1 # wait for 1 second, adjust this number with regards to the upload size
end
return false # if all 5 checks failed, return false (probably something is wrong)
end
queued_process = @client.upload_file project_id,
data: 'Base-64 encoded data... ZnI6DQogI...',
filename: 'my_file.yml',
lang_iso: 'en'
uploaded? queued_process
Keys
Fetch project keys
@client.keys(project_id, params = {}) # Input:
## project_id (string, required)
## params (hash)
### :page and :limit
# Output:
## Collection of keys available in the given project
Fetch a single project key
@client.key(project_id, key_id, params = {}) # Input:
## project_id (string, required)
## key_id (string, required)
## params (hash)
### :disable_references (string) - possible values are "1" and "0".
# Output:
## Project key
Create project keys
@client.create_keys(project_id, params) # Input:
## project_id (string, required)
## params (array of hashes or hash, required)
### :key_name (string or hash, required) - for projects with enabled per-platform key names, pass hash with "ios", "android", "web" and "other" params.
### :platforms (array) - supported values are "ios", "android", "web" and "other"
### Find all other supported attributes at https://app.lokalise.com/api2docs/curl/#transition-create-keys-post
# Output:
## Collection of newly created keys
Update project key
@client.update_key(project_id, key_id, params = {}) # Input:
## project_id (string, required)
## key_id (string, required)
## params (hash)
### Find a list of supported attributes at https://app.lokalise.com/api2docs/curl/#transition-update-a-key-put
# Output:
## Updated key
Alternatively:
key = @client.key('project_id', 'key_id')
key.update(params)
Bulk update project keys
@client.update_keys(project_id, params) # Input:
## project_id (string, required)
## params (hash or array of hashes, required)
### :key_id (string, required)
### Find all other supported attributes at https://app.lokalise.com/api2docs/curl/#transition-bulk-update-put
# Output:
## Collection of updated keys
Delete project key
@client.destroy_key(project_id, key_id) # Input:
## project_id (string, required)
## key_id (string, required)
# Output:
## Hash with project_id and "key_removed" set to "true"
Alternatively:
key = @client.key('project_id', 'key_id')
key.destroy
Bulk delete project keys
@client.destroy_keys(project_id, key_ids) # Input:
## project_id (string, required)
## key_ids (array, required)
# Output:
## Hash with project_id and "keys_removed" set to "true"
Alternatively:
keys = @client.keys('project_id')
keys.destroy_all # => will effectively destroy all keys in the project
Languages
Fetch system languages
@client.system_languages(params = {}) # Input:
## params (hash)
### :page and :limit
# Output:
## Collection of system languages supported by Lokalise
Fetch project languages
@client.project_languages(project_id, params = {}) # Input:
## project_id (string, required)
## params (hash)
### :page and :limit
# Output:
## Collection of languages available in the given project
Fetch a single project language
@client.language(project_id, language_id) # Input:
## project_id (string, required)
## language_id (string, required)
# Output:
## A single language in the given project
Create project languages
@client.create_languages(project_id, params) # Input:
## project_id (string, required)
## params (array of hashes or hash, required) - contains parameter of newly created languages. Pass array of hashes to create multiple languages, or a hash to create a single language
### :lang_iso (string, required)
### :custom_iso (string)
### :custom_name (string)
### :custom_plural_forms (array) - can contain only plural forms initially supported by Lokalise
# Output:
## Collection of newly created languages
Update project language
@client.update_language(project_id, language_id, params) # Input:
## project_id (string, required)
## language_id (string, required)
## params (hash, required)
### :lang_iso (string, required)
### :custom_name (string)
### :plural_forms (array) - can contain only plural forms initially supported by Lokalise
# Output:
## Updated language
Alternatively:
language = @client.language('project_id', 'lang_id')
language.update(params)
Delete project language
@client.destroy_language(project_id, language_id) # Input:
## project_id (string, required)
## language_id (string, required)
# Output:
## Hash with the project's id and "language_deleted"=>true
Alternatively:
language = @client.language('project_id', 'lang_id')
language.destroy
Orders
Fetch order collection
@client.orders(team_id, params = {}) # Input:
## team_id (integer, string, required)
## params (hash)
### :page and :limit
# Output:
## Collection of orders for the given team
Fetch a single order
@client.order(team_id, order_id) # Input:
## team_id (string, integer, required)
## order_id (string, required)
# Output:
## A single order
Create an order
@client.create_order(team_id, params) # Input:
## team_id (string, integer, required)
## params (hash, required)
### project_id (string, required)
### card_id (integer, string, required) - card to process payment
### briefing (string, required)
### source_language_iso (string, required)
### target_language_isos (array of strings, required)
### keys (array of integers, required) - keys to include in the order
### provider_slug (string, required)
### translation_tier (integer, required)
### dry_run (boolean) - return the response without actually placing an order. Useful for price estimation. Default is `false`
### translation_style (string) - only for gengo provider. Available values are `formal`, `informal`, `business`, `friendly`. Defaults to `friendly`.
# Output:
## A newly created order
Payment cards
Fetch payment card collection
@client.payment_cards(params = {}) # Input:
## params (hash)
### :page and :limit
# Output:
## Collection of payment cards under the `payment_cards` attribute
Fetch a single payment card
@client.payment_card(card_id) # Input:
## card_id (string, required)
# Output:
## A single payment card
Create a payment card
@client.create_payment_card(params) # Input:
## params (hash, required)
### number (integer, string, required) - card number
### cvc (integer, required) - 3-digit card CVV (CVC)
### exp_month (integer, required) - card expiration month (1 - 12)
### exp_year (integer, required) - card expiration year (for example, 2019)
# Output:
## A newly created payment card
Delete a payment card
@client.destroy_payment_card(card_id) # Input:
## card_id (integer, string, required)
# Output:
## Hash containing card id and `card_deleted => true` attribute
Alternatively:
card = @client.payment_card('card_id')
card.destroy
Projects
Fetch projects collection
@client.projects(params = {}) # Input:
## params (hash)
### :filter_team_id (string) - load projects only for the given team
### :page and :limit
# Output:
## Collection of projects under the `projects` attribute
Fetch a single project
@client.project(project_id) # Input:
## project_id (string, required)
# Output:
## A single project
Create a project
@client.create_project(params) # Input:
## params (hash, required)
### name (string, required)
### description (string)
### team_id (integer) - you must be an admin of the chosen team. When omitted, defaults to the current team of the token's owner
# Output:
## A newly created project
Update a project
@client.update_project(project_id, params) # Input:
## project_id (string, required)
## params (hash, required)
### name (string, required)
### description (string)
# Output:
## An updated project
Alternatively:
project = @client.project('project_id')
project.update(params)
Empty a project
Deletes all keys and translations from the project.
@client.empty_project(project_id) # Input:
## project_id (string, required)
# Output:
## A project containing its id and a `keys_deleted => true` attribute
Alternatively:
project = @client.project('project_id')
project.empty
Delete a project
@client.destroy_project(project_id) # Input:
## project_id (string, required)
# Output:
## A project containing its id and a `project_deleted => true` attribute
Alternatively:
project = @client.project('project_id')
project.destroy
Queued processes
Fetch queued processes
@client.queued_processes(project_id) # Input:
## project_id (string, required)
# Output:
## Collection of queued processes
Fetch a single queued process
@client.queued_process(project_id, process_id) # Input:
## project_id (string, required)
## process_id (string, required)
# Output:
## Queued process resource
Screenshots
Fetch screenshots
@client.screenshots(project_id, params = {}) # Input:
## project_id (string, required)
## params (hash)
### :page and :limit
# Output:
## Collection of project screenshots
Fetch a single screenshot
@client.screeshot(project_id, screeshot_id) # Input:
## project_id (string, required)
## screeshot_id (string, required)
# Output:
## A single screenshot
Create screenshots
@client.create_screenshots(project_id, params) # Input:
## project_id (string, required)
## params (hash or array of hashes, required)
### :data (string, required) - the actual screenshot, base64-encoded (with leading image type "data:image/jpeg;base64,"). JPG and PNG formats are supported.
### :title (string)
### :description (string)
### :ocr (boolean) - recognize translations on the image and attach screenshot to all possible keys
### :key_ids (array) - attach the screenshot to key IDs specified
### :tags (array)
# Output:
## Collection of created screenshots
Update screenshot
@client.update_screenshot(project_id, screenshot_id, params = {}) # Input:
## project_id (string, required)
## screenshot_id (string, required)
## params (hash)
### :title (string)
### :description (string)
### :key_ids (array) - attach the screenshot to key IDs specified
### :tags (array)
# Output:
## Updated screenshot
Alternatively:
screenshot = @client.screenshot('project_id', 'screen_id')
screenshot.update(params)
Delete screenshot
@client.destroy_screenshot(project_id, screenshot_id) # Input:
## project_id (string, required)
## screenshot_id (string, required)
# Output:
## Hash with the project id and "screenshot_deleted" set to "true"
Alternatively:
screenshot = @client.screenshot('project_id', 'screen_id')
screenshot.destroy
Snapshots
Fetch snapshots
@client.snapshots(project_id, params = {}) # Input:
## project_id (string, required)
## params (hash)
### :filter_title (string) - set title filter for the list
### :page and :limit
# Output:
## Collection of project snapshots
Create snapshot
@client.create_snapshot(project_id, params = {}) # Input:
## project_id (string, required)
## params (hash)
### :title (string)
# Output:
## Created snapshot
Restore snapshot
@client.restore_snapshot(project_id, snapshot_id) # Input:
## project_id (string, required)
## snapshot_id (string, required)
# Output:
## Information about the restored project from the specified snapshot
Alternatively:
snapshot = @client.snapshots('project_id').first # you can't fetch a single snapshot
snapshot.restore
Delete snapshot
@client.destroy_snapshot(project_id, snapshot_id) # Input:
## project_id (string, required)
## snapshot_id (string, required)
# Output:
## Hash with the project id and "snapshot_deleted" set to "true"
Alternatively:
snapshot = @client.snapshots('project_id').first # you can't fetch a single snapshot
snapshot.destroy
Tasks
Fetch tasks
@client.tasks(project_id, params = {}) # Input:
## project_id (string, required)
## params (hash)
### :filter_title (string) - set title filter for the list
### :page and :limit
# Output:
## Collection of tasks for the project
Fetch a single task
@client.task(project_id, task_id, params = {}) # Input:
## project_id (string, required)
## task_id (string, required)
# Output:
## Single task for the project
Create task
@client.create_task(project_id, params) # Input:
## project_id (string, required)
## params (hash, required)
### title (string, required)
### keys (array) - translation key ids. Required if "parent_task_id" is not specified
### languages (array of hashes, required)
#### language_iso (string)
#### users (array) - list of users identifiers, assigned to work on the language
### Find other supported options at https://app.lokalise.com/api2docs/curl/#transition-create-a-task-post
# Output:
## A newly created task
Update task
@client.update_task(project_id, task_id, params = {}) # Input:
## project_id (string, required)
## task_id (string or integer, required)
## params (hash)
### Find supported params at https://app.lokalise.com/api2docs/curl/#transition-update-a-task-put
# Output:
## An updated task
Alternatively:
task = @client.task('project_id', 'task_id')
task.update(params)
Delete task
@client.destroy_task(project_id, task_id) # Input:
## project_id (string, required)
## task_id (string, required)
# Output:
## Hash with the project id and "task_deleted" set to "true"
Alternatively:
task = @client.task('project_id', 'task_id')
task.destroy
Teams
Fetch teams
@client.teams(params = {}) # Input:
## params (hash)
### :page and :limit
# Output:
## Collection of teams
Team users
Fetch team users
@client.team_users(team_id, params = {}) # Input:
## team_id (string, required)
## params (hash)
### :page and :limit
# Output:
## Collection of team users
Fetch a single team user
@client.team_user(team_id, user_id) # Input:
## team_id (string, required)
## user_id (string, required)
# Output:
## Team user
Update team user
@client.update_team_user(team_id, user_id, params) # Input:
## team_id (string, required)
## user_id (string, required)
## params (hash, required):
### :role (string, required) - :owner, :admin, or :member
# Output:
## Updated team user
Alternatively:
user = @client.team_user('team_id', 'user_id')
user.update(params)
Delete team user
@client.destroy_team_user(team_id, user_id) # Input:
## team_id (string, required)
## user_id (string, required)
# Output:
## Hash with "team_id" and "team_user_deleted" set to "true"
Alternatively:
user = @client.team_user('team_id', 'user_id')
user.destroy
Team user groups
Fetch team user groups
@client.team_user_groups(team_id, params = {}) # Input:
## team_id (string, required)
## params (hash)
### :page and :limit
# Output:
## Collection of team user groups
Fetch a single group
@client.team_user_group(team_id, group_id) # Input:
## team_id (string, required)
## group_id (string, required)
# Output:
## Group
Create group
@client.create_team_user_group(team_id, params) # Input:
## team_id (string, required)
## params (hash, required):
### :name (string, required)
### :is_reviewer (boolean, required)
### :is_admin (boolean, required)
### :admin_rights (array) - required only if is_admin is true
### :languages (array of hashes) - required if is_admin is false
# Output:
## Updated group
Update group
@client.update_team_user_group(team_id, group_id, params) # Input:
## team_id (string, required)
## group_id (string, required)
## params (hash, required):
### :name (string, required)
### :is_reviewer (boolean, required)
### :is_admin (boolean, required)
### :admin_rights (array) - required only if is_admin is true
### :languages (array of hashes) - required if is_admin is false
# Output:
## Updated group
Alternatively:
group = @client.team_user_group('team_id', 'group_id')
group.update(params)
Add projects to group
@client.add_projects_to_group(team_id, group_id, project_ids) # Input:
## team_id (string, required)
## group_id (string, required)
## project_ids (string or array, required) - project ids that you would like to add to this group
Alternatively:
group = @client.team_user_group('team_id', 'group_id')
group.add_projects projects: [project_id1, project_id2]
Remove projects from group
@client.remove_projects_from_group(team_id, group_id, project_ids) # Input:
## team_id (string, required)
## group_id (string, required)
## project_ids (string or array, required) - project ids that you would like to remove from this group
Alternatively:
group = @client.team_user_group('team_id', 'group_id')
group.remove_projects projects: [project_id1, project_id2]
Add users (members) to group
@client.add_users_to_group(team_id, group_id, user_ids) # Input:
## team_id (string, required)
## group_id (string, required)
## user_ids (string or array, required) - user ids that you would like to add to this group
Alternatively:
group = @client.team_user_group('team_id', 'group_id')
group.add_users users: [user_id1, user_id2]
Remove users (members) from group
@client.remove_users_from_group(team_id, group_id, user_ids) # Input:
## team_id (string, required)
## group_id (string, required)
## user_ids (string or array, required) - user ids that you would like to add to this group
Alternatively:
group = @client.team_user_group('team_id', 'group_id')
group.remove_users users: [user_id1, user_id2]
Destroy group
@client.destroy_team_user_group(team_id, group_id) # Input:
## team_id (string, required)
## group_id (string, required)
# Output:
## Hash with "team_id" and "group_deleted" set to "true"
Alternatively:
group = @client.team_user_group('team_id', 'group_id')
group.destroy
Translations
Fetch translations
@client.translations(project_id, params = {}) # Input:
## project_id (string, required)
## params (hash)
### Find full list in the docs
### :page and :limit
# Output:
## Collection of translations for the project
Fetch a single translation
@client.translation(project_id, translation_id, params = {}) # Input:
## project_id (string, required)
## translation_id (string, required)
## params (hash)
### :disable_references (string) - whether to disable key references. Supported values are 0 and 1
# Output:
## Single translation for the project
Update translation
@client.update_translation(project_id, translation_id, params = {}) # Input:
## project_id (string, required)
## translation_id (string, required)
## params (hash, required)
### :translation (string or hash, required) - the actual translation. Provide hash for plural keys.
### :is_fuzzy (boolean)
### :is_reviewed (boolean)
# Output:
## Updated translation
Alternatively:
translation = @client.translation('project_id', 'translation_id')
translation.update(params)
Translation Providers
Translation provider attributes
Fetch translation providers
@client.translation_providers(team_id, params = {}) # Input:
## team_id (string, required)
## params (hash)
### :page and :limit
# Output:
## Collection of providers for the team
Fetch a single translation provider
@client.translation_provider(team_id, provider_id) # Input:
## team_id (string, required)
## provider_id (string, required)
# Output:
## Single provider for the team
Translation Statuses
Custom translation statuses must be enabled for the project before using this endpoint! It can be done in the project settings.
Fetch translation statuses
@client.translation_statuses(project_id, params = {}) # Input:
## project_id (string, required)
## params (hash)
### :page and :limit
# Output:
## Collection of translation statuses for the project
Fetch a single translation status
@client.translation_status(project_id, status_id) # Input:
## project_id (string, required)
## status_id (string or integer, required)
# Output:
## Translation status inside the given project
Create translation status
@client.create_translation_status(project_id, params) # Input:
## project_id (string, required)
## params (hash, required)
### :title (string, required) - title of the new status
### :color (string, required) - HEX color code of the new status. Lokalise allows a very limited number of color codes to set. Check the official docs or use `#translation_status_colors` method listed below to find the list of supported colors
# Output:
## Created translation status
Update translation status
@client.update_translation_status(project_id, status_id, params) # Input:
## project_id (string, required)
## status_id (string or integer, required)
## params (hash, required)
### :title (string, required) - title of the new status
### :color (string, required) - HEX color code of the new status
# Output:
## Updated translation status
Alternatively:
status = @client.translation_status(project_id, status_id)
status.update(params)
Delete translation status
@client.destroy_translation_status(project_id, status_id) # Input:
## project_id (string, required)
## status_id (string or integer, required)
# Output:
## Result of the delete operation
Alternatively:
status = @client.translation_status(project_id, status_id)
status.destroy
Supported color codes for translation statuses
As long as Lokalise supports only very limited array of color hexadecimal codes for custom translation statuses, this method can be used to fetch all permitted values.
@client.translation_status_colors(project_id) # Input:
## project_id (string, required)
# Output:
## Array of color codes in HEX format
Webhooks
Fetch webhooks
@client.webhooks(project_id, params = {}) # Input:
## project_id (string, required)
## params (hash)
### :page and :limit
# Output:
## Collection of webhooks for the project
Fetch a single webhook
@client.webhook(project_id, webhook_id) # Input:
## project_id (string, required)
## webhook_id (string, required)
# Output:
## Webhook for the given project
Create webhook
@client.create_webhook(project_id, params) # Input:
## project_id (string, required)
## params (hash, required)
### :url (string, required) - webhook URL
### :events (array, required) - events to subscribe to. Check the API docs to find the list of supported events
### :event_lang_map (array) - map the event with an array of languages iso codes
# Output:
## Created webhook
Update webhook
@client.update_webhook(project_id, webhook_id, params) # Input:
## project_id (string, required)
## webhook_id (string, required)
## params (hash)
### :url (string) - webhook URL
### :events (array) - events to subscribe to. Check the API docs to find the list of supported events
### :event_lang_map (array) - map the event with an array of languages iso codes
# Output:
## Updated webhook
Alternatively:
webhook = @client.webhook(project_id, webhook_id)
webhook.update(params)
Delete webhook
@client.destroy_webhook(project_id, webhook_id) # Input:
## project_id (string, required)
## webhook_id (string, required)
# Output:
## Result of the delete operation
Alternatively:
webhook = @client.webhook(project_id, webhook_id)
webhook.destroy
Regenerate webhook secret
@client.regenerate_webhook_secret(project_id, webhook_id) # Input:
## project_id (string, required)
## webhook_id (string, required)
# Output:
## Hash containing `project_id` and new `secret`
Alternatively:
webhook = @client.webhook(project_id, webhook_id)
webhook.regenerate_secret
Additional Info
Customizing Request
Choosing Adapter
This library utilizes Faraday to perform requests. The default adapter is built-in Net::HTTP but you may customize it as needed.
For example, to use Excon:
require 'excon' # somewhere in your code
Faraday.default_adapter = :excon
All supported adapters are listed on Faraday official website.
Setting Timeouts
Request timeouts may be adjusted during client initialization:
@client = Lokalise.client('YOUR_TOKEN', open_timeout: 100, timeout: 500)
@client.open_timeout # => 100
@client.timeout # => 500
Both values are in seconds. They can be adjusted later with simple accessors:
@client.open_timeout = 200
@client.timeout = 600
@client.open_timeout # => 200
@client.timeout # => 600
Customizing JSON parser
This gem used to rely on MultiJson but it is not maintained anymore. By default we are using a built-in JSON module but you may utilize any other parser by overriding #custom_dump and #custom_load methods inside Lokalise::JsonHandler module.
For example, to use Oj you would do the following:
require 'oj'
module Lokalise
module JsonHandler
# This method accepts a Ruby object and must return a JSON string
def custom_dump(obj)
Oj.dump obj
end
# This method accepts JSON and must return Ruby object
def custom_load(obj)
Oj.load obj
end
end
end
Error handling
The gem may raise the following custom exceptions:
Lokalise::Error::BadRequest(400) - the provided request incorrectLokalise::Error::Unauthorized(401) - token is missing or incorrectLokalise::Error::Forbidden(403) - authenticated user does not have sufficient rights to perform the desired actionLokalise::Error::NotFound(404) - the provided endpoint (resource) cannot be foundLokalise::Error::MethodNowAllowed(405) - HTTP request with the provided verb is not supported by the endpointLokalise::Error::NotAcceptable(406) - posted resource is malformedLokalise::Error::Conflict(409) - request conflicts with another requestLokalise::Error::Locked(423) - your token is used simultaneously in multiple requestsLokalise::Error::TooManyRequests(429)Lokalise::Error::ServerError(500)Lokalise::Error::BadGateway(502)Lokalise::Error::ServiceUnavailable(503)Lokalise::Error::GatewayTimeout(504)
API Rate Limits
Lokalise does not rate-limit API requests, however retain a right to decline the service in case of excessive use. Only one concurrent request per token is allowed. To ensure data consistency, it is not recommended to access the same project simultaneously using multiple tokens.
Running Tests
- Copypaste
.env.examplefile as.env. Put your API token inside. The.envfile is excluded from version control so your token is safe. All in all, we use pre-recorded VCR cassettes, so the actual API requests won't be sent. However, providing at least some token is required. - Run
rspec .. Observe test results and code coverage.
License
This gem is licensed under the MIT License.
Copyright (c) Lokalise team, Ilya Bodrov