Lokalise API 2.0 Ruby interface.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github
lib
spec
.env.example
.gitignore
.rspec
.rubocop.yml
.travis.yml
CHANGELOG.md
Gemfile
LICENSE
README.md
Rakefile
ruby-lokalise-api.gemspec

README.md

Lokalise API 2.0 official Ruby interface

Gem Version Build Status

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!

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

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

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 to 100, maximum is 5000) - number of records to display per page
  • :page (defaults to 1) - 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

Available Resources

Comments

Comments attributes

Fetch project comments

Doc

@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

Doc

@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

Doc

@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

Doc

@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

Doc

@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

Doc

@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

Doc

@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

Doc

@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

Doc

@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

Doc

@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

Files

File attributes

Fetch translation files

Doc

@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

Doc

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://lokalise.co/api2docs/ruby/#transition-download-files-post 
                                        # Output:
                                        ## Hash with the project id and a "bundle_url" link

Upload translation file

Doc

@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://lokalise.co/api2docs/ruby/#transition-upload-a-file-post
                                        # Output:
                                        ## Hash with information about the upload

Keys

Key attributes

Fetch project keys

Doc

@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

Doc

@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

Doc

@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://lokalise.co/api2docs/ruby/#transition-create-keys-post 
                                          # Output:
                                          ## Collection of newly created keys

Update project key

Doc

@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://lokalise.co/api2docs/ruby/#transition-update-a-key-put
                                                      # Output:
                                                      ## Updated key

Alternatively:

key = @client.key('project_id', 'key_id')
key.update(params)

Bulk update project keys

Doc

@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://lokalise.co/api2docs/ruby/#transition-bulk-update-put 
                                         # Output:
                                         ## Collection of updated keys

Delete project key

Doc

@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

Doc

@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

Language attributes

Fetch system languages

Doc

@client.system_languages(params = {})   # Input:
                                        ## params (hash)
                                        ### :page and :limit
                                        # Output:
                                        ## Collection of system languages supported by Lokalise

Fetch project languages

Doc

@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

Doc

@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

Doc

@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

Doc

@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

Doc

@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

Projects

Project attributes

Fetch projects collection

Doc

@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

Doc

@client.project(project_id)     # Input:
                                ## project_id (string, required)
                                # Output:
                                ## A single project 

Create a project

Doc

@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

Doc

@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

Doc

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

Doc

@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

Screenshots

Screenshot attributes

Fetch screenshots

Doc

@client.screenshots(project_id, params = {})  # Input:
                                              ## project_id (string, required)
                                              ## params (hash)
                                              ### :page and :limit
                                              # Output:
                                              ## Collection of project screenshots

Fetch a single screenshot

Doc

@client.screeshot(project_id, screeshot_id)     # Input:
                                                ## project_id (string, required)
                                                ## screeshot_id (string, required)
                                                # Output:
                                                ## A single screenshot 

Create screenshots

Doc

@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

Doc

@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

Doc

@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

Snapshot attributes

Fetch snapshots

Doc

@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

Doc

@client.create_snapshot(project_id, params = {})  # Input:
                                                  ## project_id (string, required)
                                                  ## params (hash)
                                                  ### :title (string)
                                                  # Output:
                                                  ## Created snapshot

Restore snapshot

Doc

@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

Doc

@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

Task attributes

Fetch tasks

Doc

@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

Doc

@client.task(project_id, task_id, params = {})  # Input:
                                                ## project_id (string, required)
                                                ## task_id (string, required)
                                                # Output:
                                                ## Single task for the project

Create task

Doc

@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://lokalise.co/api2docs/ruby/#transition-create-a-task-post 
                                         # Output:
                                         ## A newly created task 

Update task

Doc

@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://lokalise.co/api2docs/ruby/#transition-update-a-task-put 
                                                       # Output:
                                                       ## An updated task 

Alternatively:

task = @client.task('project_id', 'task_id')
task.update(params)

Delete task

Doc

@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

Doc

@client.teams(params = {})  # Input:
                            ## params (hash)
                            ### :page and :limit
                            # Output:
                            ## Collection of teams

Team users

Team user attributes

Fetch team users

Doc

@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

Doc

@client.team_user(team_id, user_id)  # Input:
                                          ## team_id (string, required)
                                          ## user_id (string, required)
                                          # Output:
                                          ## Team user

Update team user

Doc

@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

Doc

@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

Translations

Translation attributes

Fetch translations

Doc

@client.translations(project_id, params = {})   # Input:
                                                ## project_id (string, required)
                                                ## params (hash)
                                                ### :disable_references (string) - whether to disable key references. Supported values are 0 and 1
                                                ### :page and :limit
                                                # Output:
                                                ## Collection of translations for the project

Fetch a single translation

Doc

@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

Doc

@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)

Additional Info

Error handling

Error codes

The gem may raise the following custom exceptions:

  • Lokalise::Error::BadRequest (400) - the provided request incorrect
  • Lokalise::Error::Unauthorized (401) - token is missing or incorrect
  • Lokalise::Error::Forbidden (403) - authenticated user does not have sufficient rights to perform the desired action
  • Lokalise::Error::NotFound (404) - the provided endpoint (resource) cannot be found
  • Lokalise::Error::MethodNowAllowed (405) - HTTP request with the provided verb is not supported by the endpoint
  • Lokalise::Error::NotAcceptable (406) - posted resource is malformed
  • Lokalise::Error::Conflict (409) - request conflicts with another request
  • Lokalise::Error::Locked (423) - your token is used simultaneously in multiple requests
  • Lokalise::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

  1. Copypaste .env.example file as .env. Put your API token inside. The .env file 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.
  2. Run rspec .. Observe test results and code coverage.

License

This gem is licensed under the MIT License.

Copyright (c) Lokalise team, Ilya Bodrov