Lokalise Hello WorldSAFE

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-hello-world
description: 'Create a minimal working Lokalise example.

  Use when starting a new Lokalise integration, testing your setup,

  or learning basic Lokalise API patterns.

  Trigger with phrases like "lokalise hello world", "lokalise example",

  "lokalise quick start", "simple lokalise code".

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

## Overview

End-to-end walkthrough: list projects, create a test project, add keys, set translations across languages, and retrieve them. Covers both the Node SDK (`@lokalise/node-api`) and the CLI (`lokalise2`).

## Prerequisites

- Lokalise API token exported as `LOKALISE_API_TOKEN`
- Node.js 18+ with `@lokalise/node-api` installed (`npm i @lokalise/node-api`)
- Lokalise CLI v2 installed (`brew install lokalise2` or [binary releases](https://github.com/lokalise/lokalise-cli-2-go/releases))

## Instructions

1. List all projects using the SDK and CLI.

```typescript
import { LokaliseApi } from "@lokalise/node-api";

const client = new LokaliseApi({ apiKey: process.env.LOKALISE_API_TOKEN! });

const projects = await client.projects().list({ page: 1, limit: 20 });
for (const p of projects.items) {
  console.log(`${p.project_id}  ${p.name}  (${p.statistics.languages} languages)`);
}
```

```bash
set -euo pipefail
lokalise2 --token "$LOKALISE_API_TOKEN" project list
```

1. Create a test project with three languages.

```typescript
const project = await client.projects().create({
  name: "hello-world-test",
  description: "Quick start demo",
  languages: [
    { lang_iso: "en", custom_name: "English" },
    { lang_iso: "fr", custom_name: "French" },
    { lang_iso: "de", custom_name: "German" },
  ],
  base_language_iso: "en",
});

const PROJECT_ID = project.project_id;
console.log(`Created project: ${PROJECT_ID}`);
```

1. Add translation keys with their English (base language) translations in a single call.

```typescript
const keys = await client.keys().create({
  project_id: PROJECT_ID,
  keys: [
    {
      key_name: { web: "greeting.hello" },
      platforms: ["web"],
      translations: [{ language_iso: "en", translation: "Hello" }],
    },
    {
      key_name: { web: "greeting.goodbye" },
      platforms: ["web"],
      translations: [{ language_iso: "en", translation: "Goodbye" }],
    },
    {
      key_name: { web: "app.title" },
      platforms: ["web"],
      translations: [{ language_iso: "en", translation: "My Application" }],
    },
  ],
});

console.log(`Created ${keys.items.length} keys`);
```

1. Set translations for French and German by retrieving key IDs and updating each translation.

```typescript
const allKeys = await client.keys().list({
  project_id: PROJECT_ID,
  limit: 100,
});

const translations: Record<string, Record<string, string>> = {
  "greeting.hello":   { fr: "Bonjour",         de: "Hallo" },
  "greeting.goodbye": { fr: "Au revoir",       de: "Auf Wiedersehen" },
  "app.title":        { fr: "Mon Application",  de: "Meine Anwendung" },
};

for (const key of allKeys.items) {
  const keyName = key.key_name.web;
  const langs = translations[keyName];
  if (!langs) continue;

  for (const [langIso, value] of Object.entries(langs)) {
    const existing = key.translations.find(
      (t: { language_iso: string }) => t.language_iso === langIso
    );
    if (existing) {
      await client.translations().update(existing.translation_id, {
        project_id: PROJECT_ID,
        translation: value,
      });
    }
  }
}

console.log("Translations set for fr and de");
```

1. Retrieve and display all translations grouped by key.

```typescript
const result = await client.translations().list({
  project_id: PROJECT_ID,
  page: 1,
  limit: 100,
});

const grouped = new Map<number, { key: string; langs: Record<string, string> }>();
for (const t of result.items) {
  if (!grouped.has(t.key_id)) {
    grouped.set(t.key_id, { key: `key:${t.key_id}`, langs: {} });
  }
  grouped.get(t.key_id)!.langs[t.language_iso] = t.translation;
}

for (const [, entry] of grouped) {
  console.log(`\n${entry.key}`);
  for (const [lang, text] of Object.entries(entry.langs)) {
    console.log(`  ${lang}: ${text}`);
  }
}
```

1. Verify via CLI by listing keys and exporting translations.

```bash
set -euo pipefail
PROJECT_ID="YOUR_PROJECT_ID"

# List keys
lokalise2 --token "$LOKALISE_API_TOKEN" key list \
  --project-id "$PROJECT_ID" \
  --limit 100

# Export all translations as JSON
lokalise2 --token "$LOKALISE_API_TOKEN" file download \
  --project-id "$PROJECT_ID" \
  --format json \
  --original-filenames=false \
  --bundle-structure "%LANG_ISO%.json" \
  --unzip-to ./locales
```

## Output

- A new Lokalise project with 3 keys and translations in 3 languages
- Console output showing all key/translation pairs
- Exported JSON files in `./locales/` (if CLI step run)

## Error Handling

| Error | Cause | Solution |
|-------|-------|----------|
| `401 Unauthorized` | Invalid or expired API token | Verify `LOKALISE_API_TOKEN` is set and valid |
| `400 Bad Request` | Missing required fields (e.g., `key_name`) | Check payload matches API schema |
| `404 Not Found` | Project ID does not exist | Run project list to get correct ID |
| `429 Too Many Requests` | Exceeded 6 req/sec rate limit | Add 170ms delay between calls or batch operations |
| `Cannot find module` | SDK not installed | Run `npm i @lokalise/node-api` |

## Examples

### Minimal One-File Script

```typescript
// hello-lokalise.ts — run with: npx tsx hello-lokalise.ts
import { LokaliseApi } from "@lokalise/node-api";

const api = new LokaliseApi({ apiKey: process.env.LOKALISE_API_TOKEN! });

// Create project
const proj = await api.projects().create({
  name: `demo-${Date.now()}`,
  languages: [{ lang_iso: "en" }, { lang_iso: "es" }],
  base_language_iso: "en",
});

// Add a key with trans

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.