Lokalise Local Dev Loop
Apps & Automationlokalise-local-dev-loopLokalise 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".
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/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-authsetup - 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
| Error | Cause | Solution |
|---|---|---|
project_id not found | Missing config | Set LOKALISE_PROJECT_ID or lokalise.json |
File not found | Wrong path | Check bundle_structure matches src/locales |
Rate limit 429 | Too many requests | Add delay between operations |
Polling timeout | Large file upload | Increase 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.