OpenParable
Skip to content
← Back to skills

Lokalise Local Dev Loop

Apps & Automation
lokalise-local-dev-loop

Lokalise Local Dev Loop is an Agent Skill for apps & automation published in the Dicklesworthstone/pi_agent_rust repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Configure Lokalise local development with file sync and hot reload. Use when setting up a development environment, configuring translation sync, or establishing a fast iteration cycle with Lokalise. Trigger with phrases like "lokalise dev setup", "lokalise local development", "lokalise dev environment", "develop with lokalise", "lokalise sync".

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/Dicklesworthstone/pi_agent_rust/blob/HEAD/tests/ext_conformance/artifacts/plugins-community/plugins/saas-packs/lokalise-pack/skills/lokalise-local-dev-loop/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/lokalise-local-dev-loop, 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 Local Dev Loop

Overview

Set up a fast, reproducible local development workflow for Lokalise with automatic translation sync.

Prerequisites

  • Completed lokalise-install-auth setup
  • Node.js 18+ with npm/pnpm
  • Lokalise CLI v2 (lokalise2) installed
  • Existing Lokalise project

Instructions

Step 1: Create Project Structure

my-lokalise-project/
├── src/
│   ├── i18n/
│   │   ├── index.ts          # i18n setup and exports
│   │   └── config.ts         # Lokalise configuration
│   └── locales/
│       ├── en.json           # English (base)
│       ├── es.json           # Spanish
│       └── fr.json           # French
├── scripts/
│   ├── lokalise-pull.sh      # Download translations
│   └── lokalise-push.sh      # Upload source strings
├── .env.local                # Local secrets (git-ignored)
├── .env.example              # Template for team
├── lokalise.json             # Lokalise CLI config
└── package.json

Step 2: Create Lokalise CLI Config

// lokalise.json
{
  "$schema": "https://json.schemastore.org/lokalise.json",
  "project_id": "YOUR_PROJECT_ID.abcdef",
  "export": {
    "format": "json",
    "original_filenames": false,
    "bundle_structure": "locales/%LANG_ISO%.json",
    "placeholder_format": "icu",
    "export_empty_as": "skip"
  },
  "import": {
    "file_path": "./src/locales/en.json",
    "lang_iso": "en",
    "replace_modified": true,
    "convert_placeholders": true,
    "detect_icu_plurals": true
  }
}

Step 3: Create Sync Scripts

#!/bin/bash
# scripts/lokalise-pull.sh - Download translations from Lokalise

set -e

PROJECT_ID="${LOKALISE_PROJECT_ID:-$(jq -r '.project_id' lokalise.json)}"

echo "Pulling translations from Lokalise..."

lokalise2 \
  --token "$LOKALISE_API_TOKEN" \
  --project-id "$PROJECT_ID" \
  file download \
  --format json \
  --original-filenames=false \
  --bundle-structure "src/locales/%LANG_ISO%.json" \
  --placeholder-format icu \
  --export-empty-as skip \
  --unzip-to .

echo "Translations downloaded to src/locales/"
#!/bin/bash
# scripts/lokalise-push.sh - Upload source strings to Lokalise

set -e

PROJECT_ID="${LOKALISE_PROJECT_ID:-$(jq -r '.project_id' lokalise.json)}"

echo "Pushing source strings to Lokalise..."

lokalise2 \
  --token "$LOKALISE_API_TOKEN" \
  --project-id "$PROJECT_ID" \
  file upload \
  --file "./src/locales/en.json" \
  --lang-iso en \
  --replace-modified \
  --convert-placeholders \
  --detect-icu-plurals \
  --poll \
  --poll-timeout 120s

echo "Source strings uploaded successfully!"

Step 4: Configure package.json Scripts

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "i18n:pull": "bash scripts/lokalise-pull.sh",
    "i18n:push": "bash scripts/lokalise-push.sh",
    "i18n:sync": "npm run i18n:push && npm run i18n:pull",
    "predev": "npm run i18n:pull",
    "prebuild": "npm run i18n:pull"
  }
}

Step 5: Set Up File Watcher (Optional)

// scripts/watch-translations.ts
import chokidar from "chokidar";
import { exec } from "child_process";

const watcher = chokidar.watch("./src/locales/en.json", {
  persistent: true,
  ignoreInitial: true,
});

watcher.on("change", (path) => {
  console.log(`Source file changed: ${path}`);
  console.log("Pushing to Lokalise...");
  exec("npm run i18n:push", (error, stdout, stderr) => {
    if (error) {
      console.error(`Push failed: ${error.message}`);
      return;
    }
    console.log(stdout);
  });
});

console.log("Watching for translation changes...");

Output

  • Working development environment with translation sync
  • CLI scripts for push/pull operations
  • Optional file watcher for automatic uploads
  • Pre-build hooks ensure translations are current

Error Handling

ErrorCauseSolution
project_id not foundMissing configSet LOKALISE_PROJECT_ID or lokalise.json
File not foundWrong pathCheck bundle_structure matches src/locales
Rate limit 429Too many requestsAdd delay between operations
Polling timeoutLarge file uploadIncrease poll-timeout

Examples

Quick Pull/Push Commands

# Pull all translations
npm run i18n:pull

# Push source strings only
npm run i18n:push

# Full sync (push then pull)
npm run i18n:sync

Environment Setup

# .env.local
LOKALISE_API_TOKEN=your-api-token
LOKALISE_PROJECT_ID=123456789.abcdef

React i18n Integration

// src/i18n/index.ts
import i18n from "i18next";
import { initReactI18next } from "react-i18next";

import en from "../locales/en.json";
import es from "../locales/es.json";
import fr from "../locales/fr.json";

i18n.use(initReactI18next).init({
  resources: {
    en: { translation: en },
    es: { translation: es },
    fr: { translation: fr },
  },
  lng: "en",
  fallbackLng: "en",
  interpolation: { escapeValue: false },
});

export default i18n;

Git Hooks with Husky

# .husky/pre-commit
#!/bin/sh
npm run i18n:push

Resources

Next Steps

See lokalise-sdk-patterns for production-ready code patterns.