Lokalise Observability

Overview

Monitor Lokalise translation pipeline health including API response times, key completion rates, webhook delivery reliability, and translation throughput.

Prerequisites

• Lokalise API integration with @lokalise/node-api SDK
• Metrics backend (Prometheus, Datadog, or CloudWatch)
• Webhook endpoint for Lokalise project events

Instructions

Step 1: Track API Call Metrics

import { LokaliseApi } from '@lokalise/node-api';

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();
    emitMetric('lokalise_api_duration_ms', performance.now() - start, { operation, status: 'ok' });
    emitMetric('lokalise_api_requests_total', 1, { operation, status: 'ok' });
    return result;
  } catch (err: any) {
    emitMetric('lokalise_api_requests_total', 1, { operation, status: 'error', code: err.code });
    throw err;
  }
}

// Usage
const keys = await trackedApiCall('keys.list', () => lok.keys().list({ project_id: projectId, limit: 500 }));  # HTTP 500 Internal Server Error

Step 2: Monitor Translation Completion

// Poll translation progress per locale and emit as gauge metrics
async function checkTranslationProgress(projectId: string) {
  const stats = await lok.translationStatuses().list({ project_id: projectId });
  const languages = await lok.languages().list({ project_id: projectId });

  for (const lang of languages.items) {
    const progress = lang.words_translated / Math.max(lang.words_total, 1) * 100;
    emitGauge('lokalise_translation_progress_pct', progress, { project: projectId, locale: lang.lang_iso });
  }
}

Step 3: Configure Webhooks for Real-Time Events

set -euo pipefail
# Register a webhook for project completion events
curl -X POST "https://api.lokalise.com/api2/projects/PROJECT_ID/webhooks" \
  -H "X-Api-Token: $LOKALISE_API_TOKEN" \
  -d '{
    "url": "https://hooks.company.com/lokalise",
    "events": ["project.translation_completed", "project.exported", "project.key.added"],
    "event_lang_map": [{"event": "project.translation_completed", "lang_iso_codes": ["fr", "de", "ja"]}]
  }'

Step 4: Alert on Pipeline Issues

groups:
  - name: lokalise
    rules:
      - alert: LokaliseApiRateLimited
        expr: rate(lokalise_api_requests_total{status="error", code="429"}[5m]) > 0  # HTTP 429 Too Many Requests
        annotations: { summary: "Lokalise API rate limit hit (6 req/s cap)" }
      - alert: TranslationStalled
        expr: lokalise_translation_progress_pct < 50 and time() - lokalise_last_translation_activity > 86400  # 86400: timeout: 24 hours
        annotations: { summary: "Translation progress stalled for 24+ hours" }
      - alert: WebhookDeliveryFailing
        expr: rate(lokalise_webhook_failures_total[1h]) > 3
        annotations: { summary: "Lokalise webhook deliveries failing" }

Step 5: Build a Translation Pipeline Dashboard

Key panels: API request rate and latency, translation completion % by locale (bar chart), daily keys added/modified, webhook delivery success rate, and per-word cost tracking (Lokalise charges per word for machine translation features).

Error Handling

Examples

Basic usage: Apply lokalise observability to a standard project setup with default configuration options.

Advanced scenario: Customize lokalise observability for production environments with multiple constraints and team-specific requirements.

Output

• Configuration files or code changes applied to the project
• Validation report confirming correct implementation
• Summary of changes made and their rationale

Resources

• Official monitoring documentation
• Community best practices and patterns
• Related skills in this plugin pack