---

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.0.0 license: MIT author: Jeremy Longshore jeremy@intentsolutions.io

Lokalise Hello World

Overview

Minimal working example demonstrating core Lokalise functionality: projects, keys, and translations.

Prerequisites

• Completed lokalise-install-auth setup
• Valid API token configured
• At least one Lokalise project (or we'll create one)

Instructions

Step 1: Create Entry File

# Create project directory
mkdir lokalise-demo && cd lokalise-demo
npm init -y
npm install @lokalise/node-api dotenv

# Create main file
touch index.mjs

Step 2: Initialize Client and List Projects

// index.mjs
import "dotenv/config";
import { LokaliseApi } from "@lokalise/node-api";

const lokaliseApi = new LokaliseApi({
  apiKey: process.env.LOKALISE_API_TOKEN,
});

async function main() {
  // List all projects
  const projects = await lokaliseApi.projects().list();
  console.log("Your Lokalise Projects:");
  projects.items.forEach(p => {
    console.log(`  - ${p.name} (${p.project_id})`);
  });
}

main().catch(console.error);

Step 3: Create a Project

async function createProject() {
  const project = await lokaliseApi.projects().create({
    name: "My Demo Project",
    description: "Created via API",
    languages: [
      { lang_iso: "en", custom_iso: "" },  // English (base)
      { lang_iso: "es", custom_iso: "" },  // Spanish
      { lang_iso: "fr", custom_iso: "" },  // French
    ],
    base_lang_iso: "en",
  });

  console.log(`Created project: ${project.name}`);
  console.log(`Project ID: ${project.project_id}`);
  return project;
}

Step 4: Add Translation Keys

async function addKeys(projectId: string) {
  const keys = await lokaliseApi.keys().create({
    project_id: projectId,
    keys: [
      {
        key_name: "welcome.title",
        platforms: ["web"],
        translations: [
          { language_iso: "en", translation: "Welcome to our app!" },
          { language_iso: "es", translation: "Bienvenido a nuestra app!" },
          { language_iso: "fr", translation: "Bienvenue dans notre app!" },
        ],
      },
      {
        key_name: "welcome.subtitle",
        platforms: ["web"],
        translations: [
          { language_iso: "en", translation: "Get started today" },
        ],
      },
    ],
  });

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

Step 5: Retrieve Translations

async function getTranslations(projectId: string) {
  const translations = await lokaliseApi.translations().list({
    project_id: projectId,
    filter_lang_id: 640,  // English language ID
  });

  console.log("English translations:");
  translations.items.forEach(t => {
    console.log(`  ${t.key_id}: ${t.translation}`);
  });
}

Output

• Working TypeScript/JavaScript file with Lokalise client
• Successfully listed, created projects
• Added translation keys with multiple languages
• Retrieved translations

Error Handling

Error	Cause	Solution
401 Unauthorized	Invalid token	Check LOKALISE_API_TOKEN
400 Bad Request	Invalid project/key params	Verify required fields
404 Not Found	Project doesn't exist	Check project_id
429 Too Many Requests	Rate limit hit	Wait 1 second, retry

Examples

Complete Hello World Script

import "dotenv/config";
import { LokaliseApi } from "@lokalise/node-api";

const lokaliseApi = new LokaliseApi({
  apiKey: process.env.LOKALISE_API_TOKEN,
});

async function helloLokalise() {
  // 1. List existing projects
  const projects = await lokaliseApi.projects().list();
  console.log(`Found ${projects.items.length} existing projects\n`);

  // 2. Create a demo project
  const project = await lokaliseApi.projects().create({
    name: `Demo ${Date.now()}`,
    languages: [
      { lang_iso: "en" },
      { lang_iso: "es" },
    ],
    base_lang_iso: "en",
  });
  console.log(`Created: ${project.name} (${project.project_id})\n`);

  // 3. Add a key with translations
  const keys = await lokaliseApi.keys().create({
    project_id: project.project_id,
    keys: [{
      key_name: "greeting",
      platforms: ["web"],
      translations: [
        { language_iso: "en", translation: "Hello, World!" },
        { language_iso: "es", translation: "Hola, Mundo!" },
      ],
    }],
  });
  console.log(`Added ${keys.items.length} key(s)\n`);

  // 4. Fetch the key back
  const fetchedKey = await lokaliseApi.keys().get(keys.items[0].key_id, {
    project_id: project.project_id,
  });
  console.log(`Key: ${fetchedKey.key_name.web}`);

  // 5. Clean up (optional)
  // await lokaliseApi.projects().delete(project.project_id);

  console.log("\nSuccess! Your Lokalise integration is working.");
}

helloLokalise().catch(console.error);

Using CLI for Quick Test

# List projects
lokalise2 --token $LOKALISE_API_TOKEN project list

# Get project details
lokalise2 --token $LOKALISE_API_TOKEN project --project-id YOUR_PROJECT_ID

# List keys in a project
lokalise2 --token $LOKALISE_API_TOKEN key list --project-id YOUR_PROJECT_ID

Resources

• Lokalise API Reference
• Projects API
• Keys API
• Translations API

Next Steps

Proceed to lokalise-local-dev-loop for development workflow setup.