Lokalise API Client for Python

Common errors

• AttributeError: 'LokaliseProject' object has no attribute 'get'

  cause You are trying to access fields on a Pydantic model (introduced in v4.x) using dictionary-like syntax (e.g., `project.get('name')` or `project['name']`), which was common in v3.x.
  fix Access model fields directly as attributes: `project.name`, `project.project_id`, etc. (e.g., `print(project.name)`).

• ImportError: cannot import name 'LokaliseClient' from 'lokalise'

  cause The main client class `LokaliseClient` is not directly under the top-level `lokalise` package in v4.x.
  fix Update your import statement to `from lokalise.client import LokaliseClient`.

• httpx.HTTPStatusError: Client error '401 Unauthorized' for url 'https://api.lokalise.com/api/v2/projects'

  cause The provided API token is invalid, expired, or does not have sufficient permissions for the requested operation.
  fix Double-check your `LOKALISE_API_TOKEN` environment variable for correctness. Ensure it has the necessary read/write permissions for the resources you are trying to access in Lokalise.

Warnings

• breaking Version 4.x introduced significant breaking changes from v3.x. The most notable change is the adoption of `pydantic` v2 for API responses, meaning methods now return strongly-typed Pydantic models instead of raw dictionaries. Additionally, the underlying HTTP client switched from `requests` to `httpx`.
  Fix: Update your code to expect Pydantic model objects (e.g., `project.name` instead of `project['name']`). Ensure `pydantic>=2.0` and `httpx` are installed. Refer to the official v4.0.0 migration guide.
• gotcha By default, API calls that return a list of items (e.g., `client.projects().list()`) will only return the first page of results. Automatic pagination is disabled by default for performance and control.
  Fix: To get all results, you can either enable auto-pagination when initializing the client (`LokaliseClient(token, enable_auto_pagination=True)`) or manually iterate through pages using the `next_page()` method on the response object.
• gotcha API tokens should be handled securely. Hardcoding tokens directly into your script is a security risk, especially in production environments.
  Fix: Store your API token in environment variables (e.g., `LOKALISE_API_TOKEN`) and access it using `os.environ.get('LOKALISE_API_TOKEN')`.

Install

• pip install python-lokalise-api Install stable version

Imports

• LokaliseClient
  wrong:

  from lokalise import LokaliseClient

  correct:

  from lokalise.client import LokaliseClient

  The client class is nested within the 'client' submodule since v4.x.

Quickstart

Initializes the LokaliseClient using an API token from environment variables and fetches a list of projects. This demonstrates basic client setup and interaction, ensuring the API token is handled securely.

import os
from lokalise.client import LokaliseClient

# Get your Lokalise API token from environment variables for security
API_TOKEN = os.environ.get('LOKALISE_API_TOKEN', '')

if not API_TOKEN:
    print("Error: LOKALISE_API_TOKEN environment variable not set.")
    print("Please set it (e.g., export LOKALISE_API_TOKEN='YOUR_TOKEN') and retry.")
else:
    try:
        client = LokaliseClient(API_TOKEN)
        # List projects (auto_pagination is False by default, returns first page)
        projects = client.projects().list()
        if projects:
            print(f"Found {len(projects)} projects on the first page:")
            for project in projects:
                print(f"  ID: {project.project_id}, Name: {project.name}")
        else:
            print("No projects found or API token is invalid.")
    except Exception as e:
        print(f"An error occurred: {e}")