Lokalise Install & Auth
Overview
Set up Lokalise SDK/CLI and configure API token authentication for translation management. Covers the Node.js SDK (@lokalise/node-api v12+), the CLI (lokalise2), and OAuth2 for Lokalise apps.
Prerequisites
- Node.js 18+ (SDK v9+ is ESM-only)
- Package manager (npm, pnpm, or yarn)
- Lokalise account with project access
- API token from Lokalise profile settings
Instructions
Step 1: Install Node.js SDK
set -euo pipefail
npm install @lokalise/node-api
npm install @lokalise/node-api@8
Step 2: Install CLI Tool
set -euo pipefail
brew tap lokalise/cli-2
brew install lokalise2
LATEST_CLI=$(curl -s https://api.github.com/repos/lokalise/lokalise-cli-2-go/releases/latest \
| grep -oP '"tag_name": "\K[^"]+')
curl -sL "https://github.com/lokalise/lokalise-cli-2-go/releases/download/${LATEST_CLI}/lokalise2_linux_x86_64.tar.gz" | tar xz
sudo mv lokalise2 /usr/local/bin/
lokalise2 --version
Step 3: Generate API Token
- Log into Lokalise
- Click profile avatar > Profile Settings
- Go to API tokens tab
- Click Generate new token
- Choose Read and write for full access (or Read only for CI download pipelines)
- Copy the token immediately (shown only once)
Step 4: Configure Authentication
export LOKALISE_API_TOKEN="your-api-token"
echo 'LOKALISE_API_TOKEN=your-api-token' >> .env
lokalise2 --token "$LOKALISE_API_TOKEN" project list
Step 5: Verify Connection
import { LokaliseApi } from "@lokalise/node-api";
const lokaliseApi = new LokaliseApi({
apiKey: process.env.LOKALISE_API_TOKEN!,
enableCompression: true,
});
const projects = await lokaliseApi.projects().list({ limit: 10 });
console.log(`Connected! Found ${projects.items.length} projects.`);
for (const p of projects.items) {
console.log(` ${p.project_id}: ${p.name}`);
}
Step 6: OAuth2 Authentication (for Lokalise Apps)
import { LokaliseApiOAuth } from "@lokalise/node-api";
const lokaliseApi = new LokaliseApiOAuth({
apiKey: oauthAccessToken,
});
const projects = await lokaliseApi.projects().list({ limit: 10 });
OAuth2 is required when building Lokalise marketplace apps that act on behalf of users. Standard API tokens are sufficient for internal integrations.
Output
- Installed
@lokalise/node-api package (ESM v9+ or CJS v8)
lokalise2 CLI installed and verified- Environment variable or .env file with API token
- Successful connection verification listing accessible projects
Error Handling
| Error | Cause | Solution |
|---|
401 Unauthorized | Invalid or expired token | Generate new token at Profile Settings > API Tokens |
403 Forbidden | Token lacks required scope | Use read-write token, or check OAuth scopes |
ERR_REQUIRE_ESM | Using require() with SDK v9+ | Use ESM import or downgrade to @lokalise/node-api@8 |
ENOTFOUND api.lokalise.com | Network blocked | Check firewall allows outbound HTTPS to api.lokalise.com |
Cannot find module | SDK not installed | Run npm install @lokalise/node-api |
Examples
TypeScript ESM Setup
import { LokaliseApi } from "@lokalise/node-api";
export function createClient(apiKey?: string): LokaliseApi {
const key = apiKey ?? process.env.LOKALISE_API_TOKEN;
if (!key) throw new Error("Set LOKALISE_API_TOKEN or pass apiKey");
return new LokaliseApi({ apiKey: key, enableCompression: true });
}
CLI Configuration File
token: "your-api-token"
project_id: "123456789.abcdef"
Verify Token Permissions (curl)
set -euo pipefail
curl -s -H "X-Api-Token: $LOKALISE_API_TOKEN" \
"https://api.lokalise.com/api2/projects?limit=5" \
| jq '.projects[] | {project_id, name}'
Resources
Next Steps
After successful auth, proceed to lokalise-hello-world for your first API call.
