Getting Started

Installation and Requirements

Add package to the mix.exs file:

def deps do
  [
    {:elixir_lokalise_api, "~> 4.0"}
  ]
end

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

After you’ve obtained the token, put it inside config.exs:

config :elixir_lokalise_api, api_token: "LOKALISE_API_TOKEN"

If you are using ENV variables, use the following approach:

config :elixir_lokalise_api, api_token: {:system, "ENV_VARIABLE_NAME"}

If you are using OAuth 2 tokens:

config :elixir_lokalise_api, oauth2_token: "YOUR_API_OAUTH2_TOKEN"

Update OAuth 2 tokens on the fly:

:oauth2_token |> ElixirLokaliseApi.Config.put_env(oauth2_token)

Now you can send API requests!

Objects and models

Individual objects are represented as Elixir structs which are called models. Each model responds to the methods that are named after the API object’s attributes.

Here is an example:

{:ok, project} = ElixirLokaliseApi.Projects.find("123.abc")

project.name
project.description
project.base_language_iso

You can also use pattern matching:

{:ok, %ElixirLokaliseApi.Model.Project{} = project} = ElixirLokaliseApi.Projects.find("123.abc")

Many resources have common methods like project_id and branch:

{:ok, webhook} = ElixirLokaliseApi.Webhooks.find("123.abc", "345def")
webhook.project_id
webhook.branch

Collections of resources and pagination

Fetching (or creating/updating) multiple objects will return a collection of objects represented as a struct. To get access to the actual data, use the items attribute. Each item of the collection is usually represented as a model struct:

{:ok, %ElixirLokaliseApi.Collection.Projects{} = projects} = ElixirLokaliseApi.Projects.all()

project = hd projects.items # => Get the first project from the collection

%ElixirLokaliseApi.Model.Project{} = project # => project is a model struct

project.name # => you can fetch attributes easily
project.description

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

{:ok, projects} = ElixirLokaliseApi.Projects.all(page: 3, limit: 10) #=> Paginate by 10 records and fetch the third page

Paginated collections have the following attributes:

projects.total_count # => Total number of items
projects.page_count # => Total number of pages
projects.per_page_limit # => The number of items per page
projects.current_page # => Currently requested page number

To work with pagination data, use the ElixirLokaliseApi.Pagination module:

projects |> ElixirLokaliseApi.Pagination.first_page?() # => Is this the first page?
projects |> ElixirLokaliseApi.Pagination.last_page?() # => Is this the last page?
projects |> ElixirLokaliseApi.Pagination.next_page?() # => Is there a next page available?
projects |> ElixirLokaliseApi.Pagination.prev_page?() # => Is there a previous page available?
projects |> Pagination.next_page() # => What is the number of the next page?
projects |> Pagination.prev_page() # => What is the number of the previous page?

Cursor pagination

The client supports two cursor pagination formats.

APIv2 cursor pagination

The List Keys and List Translations endpoints support cursor pagination, which is recommended for its faster performance compared to traditional offset pagination.

Offset pagination is used by default, so you must explicitly set pagination to "cursor":

{:ok, %KeysCollection{} = keys} =
  Keys.all(
    @project_id,
    limit: 2,
    pagination: "cursor",
    cursor: "eyIxIjozNzk3ODEzODh9"
  )

keys.per_page_limit # => 2
keys.next_cursor # => "eyIxIjo0NTc4NDUxMDd9"

For these APIv2 endpoints, pagination information is returned in HTTP response headers and added to the resulting collection.

API v1 cursor pagination

API v1 endpoints, such as List Audit Logs, use a different cursor pagination format.

You do not need to set pagination: "cursor". The pagination information is returned directly in the response body as has_more and next_cursor:

alias ElixirLokaliseApi.CursorPagination
alias ElixirLokaliseApi.V1.AuditLogs

{:ok, audit_logs} = AuditLogs.all(limit: 2)

audit_logs.has_more # => true
audit_logs.next_cursor # => "eyJpZCI6..."

You can use CursorPagination helpers to inspect the collection:

CursorPagination.has_more?(audit_logs) # => true
CursorPagination.next_cursor?(audit_logs) # => true
CursorPagination.last_page?(audit_logs) # => false
CursorPagination.next_cursor(audit_logs) # => "eyJpZCI6..."

Pass the returned cursor to fetch the next collection:

{:ok, next_audit_logs} =
  AuditLogs.all(
    limit: 2,
    cursor: CursorPagination.next_cursor(audit_logs)
  )

API v1 endpoints use the separately configurable :base_url_api_v1 base URL. APIv2 endpoints continue to use :base_url_api.

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:

{:ok, files} = ElixirLokaliseApi.Files.all("123abcdef.01:new-feature")

files.project_id # => "123abcdef.01"
files.branch # => "new-feature"

file = hd files.items
file.filename