tutorial

Uptime monitoring for Tolgee localization platform

Tolgee is an open source software localization and i18n platform built on Java and Spring Boot. It manages translation projects, screenshot storage, machine ...

Tolgee is an open source software localization and i18n platform built on Java and Spring Boot. It manages translation projects, screenshot storage, machine translation integrations, and webhook deliveries — all behind a REST API on port 8085. When Tolgee goes down, developers lose the ability to push new translation keys, translators cannot work, and any automated i18n pipeline that calls the Tolgee API breaks silently.

This tutorial covers production-grade uptime monitoring for Tolgee using Vigilmon. We will walk through:

  • Monitoring the Tolgee API server availability
  • Monitoring translation project storage health
  • Monitoring screenshot storage service
  • Monitoring machine translation provider connectivity
  • Monitoring webhook delivery health
  • Monitoring user authentication service

Prerequisites

  • Tolgee running on port 8085 (Docker or bare metal)
  • A free account at vigilmon.online

Part 1: Monitor the Tolgee API server

Tolgee exposes a REST API and management UI on port 8085. Spring Boot's built-in Actuator provides a /actuator/health endpoint that reports the aggregate health of all internal components.

Enable Spring Boot Actuator health endpoint

By default, Tolgee exposes the Actuator health endpoint. Verify it is reachable:

curl -s http://localhost:8085/actuator/health | jq .

Expected response when healthy:

{
  "status": "UP",
  "components": {
    "db": { "status": "UP" },
    "diskSpace": { "status": "UP" },
    "ping": { "status": "UP" }
  }
}

Docker Compose deployment

# docker-compose.yml
version: "3.8"

services:
  tolgee:
    image: tolgee/tolgee:latest
    ports:
      - "8085:8080"
    environment:
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/tolgee
      SPRING_DATASOURCE_USERNAME: tolgee
      SPRING_DATASOURCE_PASSWORD: tolgee
      TOLGEE_FILE_STORAGE_PATH: /data
      SERVER_PORT: 8080
    volumes:
      - tolgee_data:/data
    depends_on:
      - postgres

  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: tolgee
      POSTGRES_USER: tolgee
      POSTGRES_PASSWORD: tolgee
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  tolgee_data:
  postgres_data:

Vigilmon setup for Tolgee API health

  1. Log in to vigilmon.online and click Add Monitor.
  2. Choose HTTP(S) monitor.
  3. Enter: http://your-tolgee-host:8085/actuator/health
  4. Set interval to 1 minute.
  5. Add a keyword check: must contain "status":"UP".
  6. Set expected status code to 200.
  7. Name it Tolgee API Health.
  8. Click Save.

The keyword check is critical — a misconfigured proxy can return 200 with a cached error page. Checking for "status":"UP" confirms the Spring Boot application itself responded.

Part 2: Monitor translation project storage

Tolgee stores translation files, key-value pairs, and project data in its PostgreSQL database and local file storage. A storage failure causes all translation operations to fail even when the API server appears healthy.

Check database connectivity through the API

# Create a test project via the Tolgee REST API (requires API key)
curl -s -o /dev/null -w "%{http_code}" \
  -H "X-API-Key: your-api-key" \
  http://localhost:8085/api/projects
# Expected: 200

Vigilmon setup for translation storage

  1. Click Add Monitor.
  2. Choose HTTP(S) monitor.
  3. Enter: http://your-tolgee-host:8085/api/projects
  4. Set interval to 2 minutes.
  5. Under Custom headers, add: X-API-Key: your-api-key
  6. Expected status code: 200.
  7. Add a keyword check: must contain "content" or "totalElements" (Tolgee paginated response fields).
  8. Name it Tolgee Translation Storage.
  9. Click Save.

Part 3: Monitor screenshot storage service

Tolgee allows attaching screenshots to translation keys for context. Screenshots are stored in the configured file storage path (TOLGEE_FILE_STORAGE_PATH). If the storage volume fills up or becomes read-only, screenshot uploads fail.

Check the Actuator disk space health

The Spring Boot Actuator disk space health indicator reports when storage is critically low:

curl -s http://localhost:8085/actuator/health/diskSpace | jq .

Expected output:

{
  "status": "UP",
  "details": {
    "total": 107374182400,
    "free": 50000000000,
    "threshold": 10485760,
    "exists": true
  }
}

Vigilmon setup for storage health

  1. Click Add Monitor.
  2. Choose HTTP(S) monitor.
  3. Enter: http://your-tolgee-host:8085/actuator/health/diskSpace
  4. Set interval to 5 minutes.
  5. Add a keyword check: must contain "status":"UP".
  6. Name it Tolgee Screenshot Storage.
  7. Click Save.

Part 4: Monitor machine translation connectivity

Tolgee integrates with machine translation providers — Google Translate, AWS Translate, DeepL, and Azure Cognitive Services — to auto-suggest translations. If the MT provider connection breaks (expired credentials, quota exceeded, network issue), auto-suggestions silently stop working.

Configure MT provider in Tolgee

# application.yaml
tolgee:
  machine-translation:
    google:
      api-key: ${GOOGLE_TRANSLATE_API_KEY}
      default-enabled: true
    deep-l:
      auth-key: ${DEEPL_API_KEY}
      default-enabled: true

Monitor MT provider APIs directly

Monitor the MT provider APIs as separate checks to distinguish "Tolgee is down" from "Google Translate quota is exceeded":

| Provider | Monitor URL | Keyword | |----------|-------------|---------| | DeepL | https://api-free.deepl.com/v2/languages | language | | Google Translate | https://translation.googleapis.com/language/translate/v2/languages?key=YOUR_KEY | language | | Azure Cognitive | https://api.cognitive.microsofttranslator.com/languages?api-version=3.0 | translation |

Create one HTTP monitor per enabled MT provider, labeled Tolgee MT — DeepL, Tolgee MT — Google, etc.

Part 5: Monitor webhook delivery health

Tolgee can send webhooks when translation keys are created, updated, or deleted. Webhook deliveries that consistently fail indicate a misconfigured endpoint or a broken webhook URL — causing downstream i18n pipelines to miss update events.

Set up a webhook in Tolgee

Navigate to Project Settings → Webhooks in the Tolgee UI and configure your endpoint:

# Test your webhook receiver is reachable from Tolgee's network
curl -X POST https://your-app.example.com/webhook/tolgee \
  -H "Content-Type: application/json" \
  -d '{"type":"key.created","projectId":1}'
# Expected: 200 or 204

Monitor the webhook receiver endpoint

  1. Click Add Monitor in Vigilmon.
  2. Choose HTTP(S) monitor.
  3. Enter: https://your-app.example.com/webhook/tolgee (GET or HEAD request to verify the endpoint is up).
  4. Set interval to 2 minutes.
  5. Accepted status codes: 200,204,405 (405 Method Not Allowed is acceptable if GET is not supported — it means the server is up).
  6. Name it Tolgee Webhook Receiver.
  7. Click Save.

Part 6: Monitor user authentication service

Tolgee handles authentication internally using Spring Security. Failed login attempts, JWT token issues, or a broken OAuth2 configuration prevent all users from accessing the platform.

Check the authentication health

# The /api/public/info endpoint is publicly accessible and confirms auth stack is up
curl -s http://localhost:8085/api/public/info | jq .

Expected response:

{
  "serverVersion": "3.x.x",
  "authMethods": {
    "native": { "enabled": true }
  }
}

Vigilmon setup for authentication health

  1. Click Add Monitor.
  2. Choose HTTP(S) monitor.
  3. Enter: http://your-tolgee-host:8085/api/public/info
  4. Set interval to 1 minute.
  5. Add a keyword check: must contain "serverVersion".
  6. Name it Tolgee Auth Service.
  7. Click Save.

Part 7: SSL certificate monitoring

If Tolgee is behind a reverse proxy with TLS, monitor the certificate:

  1. In Vigilmon, click Add Monitor.
  2. Choose SSL monitor.
  3. Enter: tolgee.example.com
  4. Set alert threshold to 14 days before expiry.
  5. Add your alert channel.
  6. Click Save.

Part 8: Webhook alerts

Configure Vigilmon webhooks to notify your i18n team when Tolgee has a problem:

// webhook-receiver.ts
import express from 'express';

const app = express();
app.use(express.json());

app.post('/webhook/vigilmon', (req, res) => {
  const { monitor_name, status, url, response_code, checked_at } = req.body;

  if (status === 'down') {
    console.error('[VIGILMON] Tolgee monitor DOWN', {
      monitor: monitor_name,
      url,
      code: response_code,
      at: checked_at,
    });

    // Notify i18n team, halt translation pipelines, etc.
    notifyI18nTeam({ monitor: monitor_name, url });
  } else if (status === 'up') {
    console.info('[VIGILMON] Tolgee recovered', { monitor: monitor_name });
  }

  res.sendStatus(204);
});

Vigilmon sends this payload on DOWN and UP transitions:

{
  "monitor_id": "mon_ghi789",
  "monitor_name": "Tolgee API Health",
  "status": "down",
  "url": "http://your-tolgee-host:8085/actuator/health",
  "checked_at": "2026-06-30T10:30:00Z",
  "response_code": 503,
  "response_time_ms": 2100
}

Summary

Your Tolgee deployment now has six layers of monitoring:

  1. API Health — confirms the Spring Boot server is alive and all internal components report UP.
  2. Translation Storage — verifies the projects API and underlying PostgreSQL are serving data.
  3. Screenshot Storage — monitors disk space so uploads do not fail silently.
  4. Machine Translation — tracks each MT provider API independently to distinguish Tolgee failures from provider quota issues.
  5. Webhook Receiver — confirms downstream i18n pipelines are reachable from Tolgee's network.
  6. Authentication — validates the auth stack is serving the public info endpoint correctly.

Vigilmon handles check scheduling, multi-region polling, alert routing, and uptime history. Your i18n team gets notified within 60 seconds of any Tolgee failure.

Monitor your Tolgee platform free at vigilmon.online

#tolgee #localization #i18n #springboot #devops #monitoring

Monitor your app with Vigilmon

Free plan — 5 monitors, no credit card required. Up and running in 60 seconds.

Start free →
← Back to all articles