Tolgee Platform Documentation

Tolgee implements observability through three core capabilities:

1. Distributed Tracing: Uses the OpenTelemetry Java Agent to follow requests across service boundaries (Spring MVC, JDBC, Redis, HTTP clients).
2. Log Correlation: The OTEL agent injects trace_id and span_id into the SLF4J MDC, allowing Logback to include them in log outputs. This enables jumping from a trace to its logs.
3. Metrics: RED metrics (Request rates, Error rates, Latency percentiles) are generated from traces by the backend (e.g., Tempo's metrics_generator) and stored in Prometheus.

Tolgee uses two primary filter classes to manage query conditions in the translation view:

1. QueryGlobalFiltering: Applies to keys as a whole. This includes filters for key id/name, namespace, search, screenshots, branch, tags, and tasks.
2. QueryTranslationFiltering: Applies to translations within specific languages. This includes filters for state, has-comments, has-suggestions, label, auto-translated, and outdated status.

Important Semantics:

• Translation-level filters are OR-ed together during query construction in TranslationsViewQueryBuilder.getWhereConditions. For example, combining filterState=en,TRANSLATED with filterHasUnresolvedCommentsInLang=de returns the union of the two sets, not the intersection.

To disable the Tolgee provider for a component or a specific story, set parameters.tolgee.disable to true. You can re-enable it for specific stories by setting it to false.

import React from 'react';
import { ConfirmButton } from './ConfirmButton';

export default {
  component: ConfirmButton,
  parameters: { tolgee: { disable: true } }, // meta level disable
};

export const ButtonWithoutTolgee = {};

export const ButtonWithTolgee = {
  parameters: { tolgee: { disable: false } }, // story level enable
};

If the database is under load, use Traces to find slow database spans and identify the parent API endpoints that triggered them. Check db.statement and db.operation for details.

TraceQL query for slow PostgreSQL queries:

Frontend

Before committing, run prettier, eslint, and tsc to ensure code quality and pass the static check workflow:

cd webapp
npm run prettier
npm run tsc
npm run eslint

Backend

Use the ktlintFormat Gradle task to format Kotlin code:

./gradlew ktlintFormat

Add the Tolgee Compose SDK to your Android project using Version Catalogs and Gradle.

# gradle/libs.versions.toml
[libraries]
tolgee = { group = "io.tolgee.mobile-kotlin-sdk", name = "compose", version.ref = "tolgee" }

// build.gradle.kts
dependencies {
    implementation(libs.tolgee)
}

If you need to run the E2E environment manually (e.g., for debugging), follow these steps:

1. Prepare environment: Follow the project's development guide.
2. Install dependencies: Run npm ci within the e2e directory.
3. Start Frontend: Run the webapp with the VITE_APP_API_URL pointing to the E2E backend port (8201).
4. Start Docker Services: Run the required Docker services (such as the fake SMTP server) using the runDockerE2eDev Gradle task.
5. Start Backend: Run the server application using the e2e Spring profile.
6. Run Tests: Execute the openE2eDev Gradle task to start the tests.
7. Cleanup: Stop the Docker services using stopDockerE2e.

Add your Tolgee API credentials to your environment configuration files (e.g., src/environments/environment.ts). You will need tolgeeApiUrl and tolgeeApiKey.

export const environment = {
  production: false,
  tolgeeApiUrl: '{{{apiUrl}}}',
  tolgeeApiKey: '{{{apiKey}}}',
};

You can override the default language for a component (meta level) or a specific story (story level) by setting the globals.tolgeeLanguage property.

import React from 'react';
import { ConfirmButton } from './ConfirmButton';

export default {
  component: ConfirmButton,
  globals: { tolgeeLanguage: 'fr' }, // meta level override
};

export const ButtonFr = {};

export const ButtonDe = {
  globals: { tolgeeLanguage: 'de' }, // story level override
};

TraceQL metrics allow you to derive time-series metrics directly from trace data at query time without prior configuration. This is ideal for ad-hoc exploration and investigating hypotheses using any span attribute.

Syntax

Append a metrics function to a TraceQL selector using a pipe (|):

{ selector } | metrics_function()

How to Query

1. In Grafana Explore, select Tempo as the datasource.
2. Enter your metrics query (ensuring it ends with a | function()).
3. Click Run query.

Grouping Results

You can group the resulting time-series by specific attributes using the by clause:

{ status = error } | rate() by (span.http.route)

{ span.http.route = "/v2/projects" && status = error } | rate()