Lokalise Install Auth
Apps & Automationlokalise-install-authLokalise Install Auth is an Agent Skill for apps & automation published in the jeremylongshore/claude-code-plugins-plus-skills repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Install and configure Lokalise SDK/CLI authentication. Use when setting up a new Lokalise integration, configuring API tokens, or initializing Lokalise in your project. Trigger with phrases like "install lokalise", "setup lokalise", "lokalise auth", "configure lokalise API token".
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/HEAD/plugins/saas-packs/lokalise-pack/skills/lokalise-install-auth/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/lokalise-install-auth, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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
# SDK v9+ is ESM-only — requires "type": "module" in package.json or .mjs files
npm install @lokalise/node-api
# For CommonJS projects that cannot migrate to ESM, pin to v8
npm install @lokalise/node-api@8
Step 2: Install CLI Tool
set -euo pipefail
# macOS via Homebrew
brew tap lokalise/cli-2
brew install lokalise2
# Linux — download latest release binary
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/
# Verify installation
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
# Set environment variable (recommended)
export LOKALISE_API_TOKEN="your-api-token"
# Or create .env file for local development
echo 'LOKALISE_API_TOKEN=your-api-token' >> .env
# CLI configuration — creates ~/.lokalise2/config.yml
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, // Gzip responses for faster transfers
});
// Test connection by listing projects
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";
// Use token obtained via OAuth2 flow
// OAuth scopes: read_projects, write_projects, read_keys, write_keys, etc.
const lokaliseApi = new LokaliseApiOAuth({
apiKey: oauthAccessToken,
});
// All SDK methods work identically with OAuth tokens
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-apipackage (ESM v9+ or CJS v8) lokalise2CLI 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
// src/lib/lokalise.ts
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
# ~/.lokalise2/config.yml
token: "your-api-token"
project_id: "123456789.abcdef"
Verify Token Permissions (curl)
set -euo pipefail
# Check which projects the token can access
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.