Skip to main content
skill CX Codex

lokalise-observability — Claude Code skill: setup and guide

lokalise-observability sets up metrics, webhook tracking, and rate limit checks for Lokalise pipelines. Useful for tracking translation progress and API health.

MIT 1 installs ★ 2,935 updated 2026-11-01

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add jeremylongshore/tons-of-skills-marketplace --skill lokalise-observability -a claude-code
Open on GitHub

What lokalise-observability does

This skill implements observability patterns for translation workflows using the @lokalise/node-api package. It wraps SDK requests to capture call duration, error codes, and request volumes for Prometheus or Datadog collectors. It also periodically inspects project metrics, tracking key counts and remaining word volumes across configured locales.

A bundled Express handler receives incoming webhook events. Lokalise cancels webhook deliveries after an 8-second timeout, so the handler issues an immediate HTTP 200 before executing background jobs. You need an active Lokalise read token and an installed @lokalise/node-api dependency for these monitoring scripts to run.

What it helps with

  • track API latency and failure counts across SDK calls
  • monitor translation completion rates by locale
  • inspect remaining API rate limits from HTTP headers
  • record latency and failures for incoming webhooks

Example prompts for the agent

  • Configure metrics and alerts for Lokalise API calls
  • Track translation completion gauges across project locales
  • Set up a rate limit check script for the Lokalise API

How to install lokalise-observability

1Skills CLI (Vercel)

npx skills add jeremylongshore/tons-of-skills-marketplace --skill lokalise-observability -a claude-code

2Manually: put the files in place

~/.claude/skills/lokalise-observability/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/lokalise-observability/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about lokalise-observability

How to install lokalise-observability in Claude Code?

Run npx skills add jeremylongshore/tons-of-skills-marketplace --skill lokalise-observability -a claude-code. This command writes the skill definition to ~/.claude/skills/lokalise-observability/SKILL.md.

What does the lokalise-observability skill do?

It provides patterns to instrument @lokalise/node-api calls, publish translation progress gauges, monitor rate limits, and process webhooks.

Why does the webhook route return a response immediately?

Lokalise drops requests after an 8-second timeout. Returning an immediate HTTP 200 prevents delivery errors while background metric tracking continues.

Source text

SKILL.md · MIT
---
name: lokalise-observability
description: 'Set up comprehensive observability for Lokalise integrations with metrics,
  traces, and alerts.

  Use when implementing monitoring for Lokalise operations, setting up dashboards,

  or configuring alerting for Lokalise integration health.

  Trigger with phrases like "lokalise monitoring", "lokalise metrics",

  "lokalise observability", "monitor lokalise", "lokalise alerts", "lokalise tracing".

  '
allowed-tools: Read, Write, Edit, Bash(curl:*), Bash(jq:*), Bash(npm:*)
version: 1.14.0
license: MIT
author: Jeremy Longshore <[email protected]>
tags:
- saas
- lokalise
- monitoring
- observability
- dashboard
compatibility: Designed for Claude Code
---
# Lokalise Observability

## Overview

Monitor Lokalise translation pipeline health: API response times, rate limit consumption, translation completion rates, webhook delivery reliability, file upload/download status, and per-word cost tracking. Built around the `@lokalise/node-api` SDK with Prometheus-compatible metrics and alerting rules.

## Prerequisites

- `@lokalise/node-api` SDK installed
- Metrics backend (Prometheus, Datadog, CloudWatch, or OpenTelemetry collector)
- Lokalise API token with read access
- Optional: webhook endpoint for real-time event monitoring

## Instructions

### Step 1: Instrument API Calls with Metrics

Wrap every SDK call to emit duration, success/failure counts, and rate limit status.

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

interface MetricLabels {
  operation: string;
  status: "ok" | "error";
  code?: string;
}

// Implement this to emit to your metrics backend
declare function emitHistogram(name: string, value: number, labels: MetricLabels): void;
declare function emitCounter(name: string, value: number, labels: MetricLabels): void;

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

async function trackedApiCall<T>(
  operation: string,
  fn: () => Promise<T>
): Promise<T> {
  const start = performance.now();
  try {
    const result = await fn();
    const durationMs = performance.now() - start;

    emitHistogram("lokalise_api_duration_ms", durationMs, {
      operation,
      status: "ok",
    });
    emitCounter("lokalise_api_requests_total", 1, {
      operation,
      status: "ok",
    });

    return result;
  } catch (err: unknown) {
    const code = (err as { code?: number })?.code?.toString() ?? "unknown";
    const durationMs = performance.now() - start;

    emitHistogram("lokalise_api_duration_ms", durationMs, {
      operation,
      status: "error",
      code,
    });
    emitCounter("lokalise_api_requests_total", 1, {
      operation,
      status: "error",
      code,
    });

    throw err;
  }
}

// Usage — wrap every SDK call
const keys = await trackedApiCall("keys.list", () =>
  lok.keys().list({ project_id: projectId, limit: 500 })
);

const bundle = await trackedApiCall("files.download", () =>
  lok.files().download(projectId, {
    format: "json",
    filter_langs: ["en"],
    original_filenames: false,
  })
);
```

### Step 2: Monitor Translation Completion

Poll project statistics and emit per-locale progress as gauge metrics.

```typescript
declare function emitGauge(name: string, value: number, labels: Record<string, string>): void;

async function collectTranslationMetrics(projectId: string): Promise<void> {
  const project = await trackedApiCall("projects.get", () =>
    lok.projects().get(projectId)
  );

  // Overall progress
  emitGauge("lokalise_translation_progress_pct", project.statistics?.progress_total ?? 0, {
    project: projectId,
    locale: "all",
  });

  emitGauge("lokalise_keys_total", project.statistics?.keys_total ?? 0, {
    project: projectId,
  });

  // Per-language progress
  const languages = await trackedApiCall("languages.list", () =>
    lok.languages().list({ project_id: projectId, limit: 100 })
  );

  for (const lang of languages.items) {
    emitGauge("lokalise_translation_progress_pct", lang.statistics?.progress ?? 0, {
      project: projectId,
      locale: lang.lang_iso,
    });
    emitGauge("lokalise_words_to_do", lang.statistics?.words_to_do ?? 0, {
      project: projectId,
      locale: lang.lang_iso,
    });
  }
}

// Run on a schedule (every 5 minutes)
// setInterval(() => collectTranslationMetrics(projectId), 5 * 60_000);
```

### Step 3: Track Rate Limit Consumption

```bash
set -euo pipefail
# Quick rate limit check — call from a monitoring cron job
HEADERS=$(curl -sI "https://api.lokalise.com/api2/projects?limit=1" \
  -H "X-Api-Token: ${LOKALISE_API_TOKEN}" 2>/dev/null)

LIMIT=$(echo "$HEADERS" | grep -i "x-ratelimit-limit" | awk '{print $2}' | tr -d '\r')
REMAINING=$(echo "$HEADERS" | grep -i "x-ratelimit-remaining" | awk '{print $2}' | tr -d '\r')
RESET=$(echo "$HEADERS" | grep -i "x-ratelimit-reset" | awk '{print $2}' | tr -d '\r')

echo "Rate limit: ${REMAINING}/${LIMIT} remaining (resets at ${RESET})"

# Emit as metrics for Prometheus/Datadog
# lokalise_rate_limit_remaining ${REMAINING}
# lokalise_rate_limit_max ${LIMIT}
```

### Step 4: Monitor Webhook Delivery

Track webhook processing success and latency in your webhook handler.

```typescript
import express from "express";

const webhookMetrics = {
  received: 0,
  processed: 0,
  failed: 0,
  totalLatencyMs: 0,
};

app.post("/webhooks/lokalise", async (req: express.Request, res: express.Response) => {
  webhookMetrics.received++;
  const start = performance.now();

  // Respond immediately — Lokalise times out after 8 seconds
  res.status(200).json({ received: true });

  try {
    await processWebhookEvent(req.body);
    webhookMetrics.processed++;
  } catch (error) {
    webhookMetrics.failed++;
    console.error("Webhook processing failed:", error);
  }

  const latencyMs = performance.now() - start;
  webhookMetrics.totalLatencyMs += latencyMs;

  emitCounter("lokalise_webhook_received_total", 1, {
    event: req.body.event,
    status: webhookMetrics.failed > 0 ? "error" : "ok",
  });
  emitHistogram("lokalise_webhook_processing_ms", latencyMs, {
    event: req.body.event,
    status: "ok",
  });
});

// Health endpoint exposing webhook metrics
app.get("/metrics/webhooks", (_req, res) => {
  res.json({
    received: webhookMetrics.received,
    processed: webhookMetrics.processed,
    failed: webhookMetrics.failed,
    avgLatencyMs: webhookMetrics.received > 0
      ? Math.round(webhookMetrics.totalLatencyMs / webhookMetrics.received)
      : 0,
  });
});
```

### Step 5: Register Webhooks for Key Events

```bash
set -euo pipefail
# Subscribe to events that matter for pipeline monitoring
curl -s -X POST "https://api.lokalise.com/api2/projects/${LOKALISE_PROJECT_ID}/webhooks" \
  -H "X-Api-Token: ${LOKALISE_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.company.com/lokalise",
    "events": [
      "project.imported",
      "project.exported",
      "project.key.added",
      "project.key.modified",
      "project.translation.updated",
      "project.translation.proofread",
      "project.task.closed",
      "project.contributor.added"
    ]
  }' | jq '{webhook_id: .webhook.webhook_id, events: .webhook.events}'
```

### Step 6: Prometheus Alerting Rules

```yaml
groups:
  - name: lokalise
    rules:
      - alert: LokaliseApiRateLimited
        expr: rate(lokalise_api_requests_total{status="error", code="429"}[5m]) > 0
        for: 2m
        annotations:
          summary: "Lokalise API rate limit hit — requests being throttled"
          runbook: "Check for runaway loops. Lokalise limit is 6 req/sec per token."

      - alert: LokaliseApiErrors
        expr: rate(lokalise_api_requests_total{status="error", code=~"5.."}[10m]) > 0.1
        for: 5m
        annotations:
          summary: "Lokalise API returning 5xx errors"
          runbook: "Check https://status.lokalise.com. Enable fallback translations."

      - alert: TranslationProgressStalled
        expr: lokalise_translation_progress_pct < 80 and changes(lokalise_translation_progress_pct[24h]) == 0
        for: 24h
        annotations:
          summary: "Translation progress stalled at {{ $value }}% for 24+ hours"

      - alert: WebhookDeliveryFailing
        expr: rate(lokalise_webhook_received_total{status="error"}[1h]) > 3
        annotations:
          summary: "Lokalise webhook deliveries failing ({{ $value }} errors/hour)"

      - alert: LokaliseApiLatencyHigh
        expr: histogram_quantile(0.95, rate(lokalise_api_duration_ms_bucket[5m])) > 5000
        for: 10m
        annotations:
          summary: "Lokalise API P95 latency above 5 seconds"
```

### Step 7: Translation Pipeline Dashboard Spec

Key panels for Grafana/Datadog:

| Panel | Metric | Type |
|-------|--------|------|
| API Request Rate | `rate(lokalise_api_requests_total[5m])` | Time series |
| API Latency P50/P95 | `histogram_quantile(0.5/0.95, ...)` | Time series |
| Rate Limit Remaining | `lokalise_rate_limit_remaining` | Gauge |
| Translation Progress | `lokalise_translation_progress_pct` by locale | Bar chart |
| Words Remaining | `lokalise_words_to_do` by locale | Bar chart |
| Webhook Success Rate | `rate(lokalise_webhook_received_total{status="ok"}[5m])` | Time series |
| Error Rate by Code | `rate(lokalise_api_requests_total{status="error"}[5m])` by code | Stacked area |

## Output

- `trackedApiCall()` wrapper emitting duration and error metrics for every Lokalise API operation
- Translation progress gauge metrics broken down by project and locale
- Rate limit consumption monitoring via response headers
- Webhook delivery tracking with latency and error counters
- Prometheus alerting rules for rate limiting, API errors, stalled progress, and webhook failures
- Dashboard specification with 7 panels covering the full translation pipeline

## Error Handling

| Issue | Cause | Solution |
|-------|-------|----------|
| `429 Too Many Requests` | Exceeded 6 req/sec rate limit | Add request throttling with p-queue |
| Webhook not firing | Wrong event type registered | Verify event names match API reference |
| Progress metric stuck at 0 | Language not added to project | Add target locale in Lokalise project settings |
| Stale metrics | Polling interval too long | Reduce collection interval to 5 minutes |
| High cardinality | Too many label values | Limit `operation` labels to top-level SDK methods |

## Examples

### Verify a stalled translation pipeline before paging a team

An alert reports that French translations have remained at 74% for a day. First
query the project statistic and the webhook/error metrics for the same window;
do not assume that a low progress value is an API outage. If API latency and
error rate are normal but no `project.translation.updated` events arrived,
route the incident to the translation owner with the project and locale. If
the webhook error metric is elevated, preserve the failed delivery identifiers
and use the webhook runbook before replaying or changing any production data.

## Resources

- [Lokalise Webhooks API](https://developers.lokalise.com/reference/create-a-webhook)
- [Lokalise Webhook Events](https://developers.lokalise.com/docs/webhook-events)
- [Lokalise API Rate Limits](https://developers.lokalise.com/reference/api-rate-limits)
- [Lokalise Project Statistics](https://developers.lokalise.com/reference/retrieve-a-project)
- [Prometheus Alerting Rules](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/)
- [p-queue](https://github.com/sindresorhus/p-queue) — rate-limited request queue

## Next Steps

For setting up real-time automation based on webhook events, see `lokalise-webhooks-events`. For incident response procedures when alerts fire, see `lokalise-incident-runbook`.

© Jeremy Longshore · MIT · jeremylongshore/tons-of-skills-marketplace

Similar skills

All skills for DevOps and infrastructure →

From the same set139

The whole set →
gc-log-analyzer A skill for reading garbage collector logs in performance testing work. It turns on by itself when the request mentions gc log analyzer. CX Codex +1 1installs klingai-audit-logging klingai-audit-logging sets up tamper-evident audit logging for Kling AI API calls. It tracks video generation tasks, checks log integrity, and hashes prompts. CX Codex +1 1installs openrouter-audit-logging The openrouter-audit-logging skill adds an audit trail for OpenRouter calls, recording request metadata, cost, and a prompt hash. Use it to investigate errors or track model usage. CX Codex +1 1installs monitoring-whale-activity The monitoring-whale-activity skill monitors large cryptocurrency transactions and whale wallet movements across multiple blockchains in real-time. Triggers on phrases like "track whales", "monitor large transfers", "check whale activity". CX Codex +1 1installs model-evaluation-metrics The model-evaluation-metrics skill supports model evaluation work in ML Training by generating code, configurations, guidance, and checks for the results. CX Codex +1 1installs date-range-analyzer A skill for date range work in data analytics tasks. It turns on by itself when a request mentions date range analyzer. CX Codex +1 1installs data-story-outliner data-story-outliner — a skill for Claude Code, Codex, Cursor, and other AI coding assistants that auto-activates when working with data analytics. CX Codex +1 1installs retention-calculator This skill handles retention calculator work in data analytics, producing code and configuration guidance. It activates from related requests. CX Codex +1 1installs

Project sponsors

Companies that keep this analytics open