Lokalise Sdk PatternsSAFE

Model-agnostic agent-skills platform with a harness-free canonical layer, verified adapters, and the ccpi package manager. Explore at tonsofskills.com.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: lokalise-sdk-patterns
description: 'Apply production-ready Lokalise SDK patterns for TypeScript and Node.js.

  Use when implementing Lokalise integrations, refactoring SDK usage,

  or establishing team coding standards for Lokalise.

  Trigger with phrases like "lokalise SDK patterns", "lokalise best practices",

  "lokalise code patterns", "idiomatic lokalise".

  '
allowed-tools: Read, Write, Edit
version: 1.14.0
license: MIT
author: Jeremy Longshore <[email protected]>
tags:
- saas
- lokalise
- typescript
- nodejs
compatibility: Designed for Claude Code
---
# Lokalise SDK Patterns

## Overview

Production-grade patterns for `@lokalise/node-api`: client singleton, cursor pagination, typed error handling, batch operations, upload monitoring, and retry with rate limiting.

## Prerequisites

- `@lokalise/node-api` v12+ installed
- TypeScript 5+ with `strict` mode

## Instructions

1. Create a client singleton to centralize configuration and support branch-based project IDs.

```typescript
// src/lib/lokalise-client.ts
import { LokaliseApi } from "@lokalise/node-api";

let instance: LokaliseApi | null = null;

export function getClient(apiKey?: string): LokaliseApi {
  if (instance) return instance;
  const key = apiKey ?? process.env.LOKALISE_API_TOKEN;
  if (!key) throw new Error("Set LOKALISE_API_TOKEN or pass apiKey");
  instance = new LokaliseApi({ apiKey: key, enableCompression: true });
  return instance;
}

export function resetClient(): void { instance = null; }

/** Lokalise branch syntax: "projectId:branchName" */
export function projectId(id: string, branch?: string): string {
  return branch ? `${id}:${branch}` : id;
}
```

1. Build a cursor-based pagination helper that works with any paginated endpoint.

```typescript
// src/lib/paginate.ts
interface PaginatedResult<T> {
  items: T[];
  hasNextCursor(): boolean;
  nextCursor(): string;
}

type Fetcher<T> = (params: Record<string, unknown>) => Promise<PaginatedResult<T>>;

/** Async generator yielding all items across pages with rate-limit spacing. */
export async function* paginate<T>(
  fetcher: Fetcher<T>,
  baseParams: Record<string, unknown>,
  pageSize = 500
): AsyncGenerator<T, void, undefined> {
  let cursor: string | undefined;
  let n = 0;
  do {
    const params = { ...baseParams, limit: pageSize, ...(cursor ? { cursor } : {}) };
    if (n++ > 0) await new Promise((r) => setTimeout(r, 170)); // 6 req/sec
    const page = await fetcher(params);
    for (const item of page.items) yield item;
    cursor = page.hasNextCursor() ? page.nextCursor() : undefined;
  } while (cursor);
}

/** Collect all pages into an array (use only when dataset fits in memory). */
export async function paginateAll<T>(fetcher: Fetcher<T>, params: Record<string, unknown>): Promise<T[]> {
  const out: T[] = [];
  for await (const item of paginate(fetcher, params)) out.push(item);
  return out;
}
```

Usage:

```typescript
const allKeys = await paginateAll(
  (p) => client.keys().list(p),
  { project_id: "123456.abcdef", include_translations: 1 }
);
```

1. Wrap API calls with structured error handling that classifies retryable errors.

```typescript
// src/lib/lokalise-api.ts
export class LokaliseError extends Error {
  constructor(
    message: string,
    public readonly statusCode: number,
    public readonly isRetryable: boolean
  ) {
    super(message);
    this.name = "LokaliseError";
  }
}

export async function apiCall<T>(fn: () => Promise<T>): Promise<T> {
  try {
    return await fn();
  } catch (err: unknown) {
    if (err && typeof err === "object" && "code" in err) {
      const e = err as { code: number; message: string };
      throw new LokaliseError(e.message, e.code, e.code === 429 || e.code >= 500);
    }
    throw err;
  }
}

// Usage
try {
  const keys = await apiCall(() => client.keys().list({ project_id: pid, limit: 500 }));
} catch (err) {
  if (err instanceof LokaliseError && err.isRetryable) {
    console.log("Transient failure, safe to retry");
  }
}
```

1. Batch key operations that chunk requests to respect the 500-key-per-request limit.

```typescript
// src/lib/batch.ts
function chunk<T>(arr: T[], size: number): T[][] {
  const out: T[][] = [];
  for (let i = 0; i < arr.length; i += size) out.push(arr.slice(i, i + size));
  return out;
}

/** Create keys in batches of 500 with rate-limit spacing. */
export async function batchCreateKeys(
  client: LokaliseApi, projectId: string,
  keys: Array<{ key_name: { web: string }; platforms: string[]; tags?: string[];
    translations?: Array<{ language_iso: string; translation: string }> }>
): Promise<{ created: number; errors: Error[] }> {
  const batches = chunk(keys, 500);
  let created = 0;
  const errors: Error[] = [];
  for (let i = 0; i < batches.length; i++) {
    try {
      const r = await client.keys().create({ project_id: projectId, keys: batches[i] });
      created += r.items.length;
    } catch (err) { errors.push(err as Error); }
    if (i < batches.length - 1) await new Promise((r) => setTimeout(r, 500));
  }
  return { created, errors };
}

/** Delete keys in batches of 500. */
export async function batchDeleteKeys(
  client: LokaliseApi, projectId: string, keyIds: number[]
): Promise<number> {
  const batches = chunk(keyIds, 500);
  let deleted = 0;
  for (let i = 0; i < batches.length; i++) {
    const r = await client.keys().bulk_delete(batches[i], { project_id: projectId });
    deleted += r.keys_removed;
    if (i < batches.length - 1) await new Promise((r) => setTimeout(r, 500));
  }
  return deleted;
}
```

1. Upload files with async process monitoring and progress callbacks.

```typescript
// src/lib/upload.ts
import { readFileSync } from "node:fs";

export async function uploadWithProgress(
  client: LokaliseApi, projectId: string,
  opts: { filePath: string; langIso: string; tags?: string[];
    replaceModified?: boolean; cleanupMode?: boolean },
  onProgress?: (status: string, elapsedMs: number) => void
): Promise<{ processI

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.