### Install Frontend Dependencies and Start Development Server

Source: https://github.com/tolgee/tolgee-platform/blob/main/DEVELOPMENT.md

Install npm dependencies for the library and webapp, then start the frontend development server.

```shell
npm --prefix library ci
cd webapp && npm ci && npm run start
```

--------------------------------

### Install Frontend Dependencies and Start Server

Source: https://context7.com/tolgee/tolgee-platform/llms.txt

Install Node.js dependencies for the Tolgee frontend and then start the development server. The frontend will be available at http://localhost:3000.

```bash
npm --prefix library ci
cd webapp && npm ci

npm run start
```

--------------------------------

### Start Local Webhook Server

Source: https://github.com/tolgee/tolgee-platform/blob/main/docs/local-observability-stack/5_Alerting.md

Run this command to start a local webhook server for testing contact point configurations. Ensure Python 3 is installed.

```bash
python3 docs/local-observability-stack/test-webhook-server.py
```

--------------------------------

### Install mcp-publisher

Source: https://github.com/tolgee/tolgee-platform/blob/main/docs/mcp-server/README.md

Use Homebrew to install the mcp-publisher tool if it is not already installed.

```bash
brew install mcp-publisher
```

--------------------------------

### Install and Build Tolgee Storybook Addon

Source: https://github.com/tolgee/tolgee-platform/blob/main/library/README.md

Navigate to the 'storybook-tolgee-addon' directory and run these commands to install its dependencies and build the addon.

```shell
cd storybook-tolgee-addon
npm ci
npm run build
```

--------------------------------

### Install Storybook and Library Dependencies

Source: https://github.com/tolgee/tolgee-platform/blob/main/library/README.md

Run this command in the 'library' directory to install dependencies for Storybook and the Tolgee library.

```shell
cd library
npm ci
```

--------------------------------

### Start Docker Observability Stack for Development

Source: https://github.com/tolgee/tolgee-platform/blob/main/docs/local-observability-stack/1_Setting_Up_the_Tracing_Stack.md

Starts the observability services (Grafana, Tempo, Loki, etc.) in Docker, intended for use with local Tolgee development. Ensure you are in the 'docker' directory.

```bash
cd docker && docker compose -f docker-compose.local-observability-stack-dev.yaml up -d
```

--------------------------------

### Open Storybook Instance

Source: https://github.com/tolgee/tolgee-platform/blob/main/library/README.md

Execute this command in the 'library' directory to start the Storybook server and open the Tolgee UI components in your browser.

```shell
cd library
npm run storybook
```

--------------------------------

### Install @tolgee/vue Package

Source: https://github.com/tolgee/tolgee-platform/blob/main/webapp/src/views/projects/integrate/guides/Vue.mdx

Use npm to install the necessary package for Tolgee Vue integration.

```sh
npm install @tolgee/vue
```

--------------------------------

### Run All E2E Tests

Source: https://github.com/tolgee/tolgee-platform/blob/main/e2e/README.md

Execute the main Gradle task to run all E2E tests. This task handles dependency installation and setup.

```shell
./gradlew runE2e
```

--------------------------------

### Start Local Observability Stack

Source: https://github.com/tolgee/tolgee-platform/blob/main/docs/observability/README.md

Navigate to the local observability stack directory and start the stack using Docker Compose. This command is for local development purposes.

```bash
cd docker && docker compose -f docker-compose.local-observability-stack.yaml up -d
```

--------------------------------

### Install Storybook Addon

Source: https://github.com/tolgee/tolgee-platform/blob/main/storybook-tolgee-addon/README.md

Use npx to add the @tolgee/storybook-addon package to your existing Storybook project.

```bash
npx storybook add @tolgee/storybook-addon
```

--------------------------------

### Install @tolgee/svelte Package

Source: https://github.com/tolgee/tolgee-platform/blob/main/webapp/src/views/projects/integrate/guides/Svelte.mdx

Use npm to install the necessary package for Tolgee Svelte integration.

```sh
npm i @tolgee/svelte
```

--------------------------------

### Install Tolgee NPM Package

Source: https://github.com/tolgee/tolgee-platform/blob/main/webapp/src/views/projects/integrate/guides/Js.mdx

Install the Tolgee web package using NPM. This is the first step to integrate Tolgee into your project.

```sh
npm install @tolgee/web
```

--------------------------------

### Install Tolgee Angular Package

Source: https://github.com/tolgee/tolgee-platform/blob/main/webapp/src/views/projects/integrate/guides/Angular.mdx

Use npm to install the necessary Tolgee package for Angular.

```sh
npm install @tolgee/ngx
```

--------------------------------

### Install @tolgee/react package

Source: https://github.com/tolgee/tolgee-platform/blob/main/webapp/src/views/projects/integrate/guides/Next.mdx

Install the necessary package for using Tolgee components and hooks in your React application.

```sh
npm install @tolgee/react
```

--------------------------------

### Build Docker Image

Source: https://github.com/tolgee/tolgee-platform/blob/main/docs/local-observability-stack/1_Setting_Up_the_Tracing_Stack.md

Builds the Docker image for the Tolgee application. This is the first step for the full Docker stack setup.

```bash
./gradlew docker
```

--------------------------------

### PromQL Time Series Examples

Source: https://github.com/tolgee/tolgee-platform/blob/main/docs/local-observability-stack/4_Metrics_From_Traces.md

Illustrates how Prometheus creates unique time series based on metric names and label values. Each example shows a specific combination of metric and labels.

```text
// total number of GET /v2/projects calls with status OK
traces_spanmetrics_calls_total{span_name="GET /v2/projects", status_code="OK"}     -> time series #1

// total number of GET /v2/projects calls with status ERROR
traces_spanmetrics_calls_total{span_name="GET /v2/projects", status_code="ERROR"}  -> time series #2

// total number of POST /v2/keys calls with status OK
traces_spanmetrics_calls_total{span_name="POST /v2/keys", status_code="OK"}        -> time series #3
```

--------------------------------

### Install Tolgee CLI

Source: https://github.com/tolgee/tolgee-platform/blob/main/webapp/src/views/projects/integrate/guides/Cli.mdx

Install the Tolgee CLI globally using npm. This command is required before using any other Tolgee CLI commands.

```sh
npm install --global @tolgee/cli
```

--------------------------------

### Tolgee Local Development Configuration

Source: https://context7.com/tolgee/tolgee-platform/llms.txt

Example configuration file for local development. This file, `application-dev.yaml`, sets up SQL logging, frontend URL, file storage URL, and authentication details.

```yaml
spring:
  jpa:
    show-sql: true

tolgee:
  front-end-url: http://localhost:3000
  file-storage-url: http://localhost:8080
  authentication:
    enabled: true
    initial-username: admin
    initial-password: admin123

  machine-translation:
    google:
      api-key: your-google-api-key
    deepl:
      auth-key: your-deepl-auth-key
    aws:
      access-key-id: your-aws-key
      secret-access-key: your-aws-secret
      region: us-east-1
```

--------------------------------

### Run Tolgee Backend with Docker

Source: https://context7.com/tolgee/tolgee-platform/llms.txt

Alternatively, run the Tolgee backend using Docker. This is a quick way to get the server up and running on port 8080.

```bash
docker run -p 8080:8080 tolgee/tolgee
```

--------------------------------

### Run Tolgee with Observability (Local Dev)

Source: https://github.com/tolgee/tolgee-platform/blob/main/docs/observability/README.md

Use this command for local development to run the Tolgee server with observability enabled. It starts the local observability stack and then runs the application with development profiles.

```bash
docker compose -f docker-compose.local-observability-stack-dev.yaml up -d && ./gradlew server-app:bootRunWithObservability --args='--spring.profiles.active=dev'
```

--------------------------------

### Setup NgModule with Tolgee

Source: https://github.com/tolgee/tolgee-platform/blob/main/webapp/src/views/projects/integrate/guides/Angular.mdx

Import NgxTolgeeModule and configure the TOLGEE_INSTANCE provider in your AppModule.

```typescript
import {
  DevTools,
  NgxTolgeeModule,
  Tolgee,
  TOLGEE_INSTANCE,
  FormatSimple
} from '@tolgee/ngx';

... // Other imports
@NgModule({
  declarations: [
    ...
  ],
  imports: [
    NgxTolgeeModule,
    ...
  ],
  providers: [
    {
      provide: TOLGEE_INSTANCE,
      useFactory: () => {
        return Tolgee()
          .use(DevTools())
          .use(FormatSimple())
          .init({
            language: 'en'

            // for development
            apiUrl: environment.tolgeeApiUrl,
            apiKey: environment.tolgeeApiKey,

            // for production
            staticData: {
              ...
            }
          });
      },
    },
  ],
  ...
})
export class AppModule {}
```

--------------------------------

### Ngrok Configuration for Multi-Workspace Slack Setup

Source: https://github.com/tolgee/tolgee-platform/wiki/Slack-integration-development

This YAML configuration is used with ngrok to expose your Tolgee backend and frontend to the internet, which is required for Slack's OAuth and event subscriptions. Ensure you replace placeholders with your actual tokens and desired domains. This setup typically requires a paid ngrok plan.

```yaml
version: 2
authtoken: <your token>
tunnels:
  backend:
    proto: http
    addr: 8080
    domain: tolgee-backend-<name>.ngrok.dev
  frontend:
    proto: http
    addr: 8081
    domain: tolgee-frontend-<name>.ngrok.dev
```

--------------------------------

### Run Tolgee with Observability (Docker Full Stack)

Source: https://github.com/tolgee/tolgee-platform/blob/main/docs/observability/README.md

This command is used for testing the full stack of Tolgee, suitable for CI or production-like environments. It starts the local observability stack.

```bash
docker compose -f docker-compose.local-observability-stack.yaml up -d
```

--------------------------------

### Clone Tolgee Repository

Source: https://context7.com/tolgee/tolgee-platform/llms.txt

Clone the Tolgee platform repository to start development. Use the `--depth 1` flag for a shallow clone.

```bash
git clone --depth 1 git@github.com:tolgee/tolgee-platform.git
cd tolgee-platform
```

--------------------------------

### Install E2E Dependencies

Source: https://github.com/tolgee/tolgee-platform/blob/main/e2e/README.md

Install Node.js dependencies required for the E2E tests using npm. Ensure you are in the 'e2e' directory.

```shell
npm --prefix e2e ci
```

--------------------------------

### Run Frontend with E2E Settings

Source: https://github.com/tolgee/tolgee-platform/blob/main/e2e/README.md

Start the frontend development server with specific E2E configurations, including API URL, port, and host settings. This command is used for testing the UI interaction with the backend.

```shell
VITE_APP_API_URL=http://localhost:8201 npm --prefix webapp run start -- --port 8081 --host --no-open
```

--------------------------------

### Initialize Tolgee with React Provider

Source: https://github.com/tolgee/tolgee-platform/blob/main/webapp/src/views/projects/integrate/guides/React.mdx

Initialize Tolgee with necessary plugins and configuration, then wrap your App component with TolgeeProvider. This setup is for development using environment variables.

```typescript jsx
import { Tolgee, DevTools, TolgeeProvider, FormatSimple } from "@tolgee/react";

const tolgee = Tolgee()
  .use(DevTools())
  .use(FormatSimple())
  .init({
    language: 'en',

    // for development
    apiUrl: import.meta.env.VITE_APP_TOLGEE_API_URL,
    apiKey: import.meta.env.VITE_APP_TOLGEE_API_KEY,

    // for production
    staticData: {
      ...
    }
  });

... 

<TolgeeProvider
  tolgee={tolgee}
  fallback="Loading..." // loading fallback
>
  <App />
</TolgeeProvider>
```

--------------------------------

### Run Backend with E2E Profile

Source: https://github.com/tolgee/tolgee-platform/blob/main/e2e/README.md

Start the backend application with the 'e2e' Spring profile activated. This allows for E2E testing and debugging.

```shell
./gradlew server-app:bootRun --args='--spring.profiles.active=e2e'
```

--------------------------------

### Run E2E Docker Services

Source: https://github.com/tolgee/tolgee-platform/blob/main/e2e/README.md

Start the necessary Docker services for E2E testing, such as a fake SMTP server. This is part of the environment preparation.

```shell
./gradlew runDockerE2eDev
```

--------------------------------

### Configure Tolgee Development Settings

Source: https://github.com/tolgee/tolgee-platform/blob/main/DEVELOPMENT.md

Create an `application-dev.yaml` file to override default Spring Boot and Tolgee configurations for local development. This example shows how to enable SQL logging and set frontend and file storage URLs, along with initial authentication credentials.

```yaml
spring:
  jpa:
    show-sql: true
tolgee:
  front-end-url: http://localhost:3000
  file-storage-url: http://localhost:8080
  authentication: # to see "Server administration", "Organization settings" etc.
    enabled: true
    initial-username: admin
    initial-password: 123123
```

--------------------------------

### Get Projects with Statistics

Source: https://context7.com/tolgee/tolgee-platform/llms.txt

Retrieves projects along with their associated statistics, using pagination. Ensure your API key is included.

```bash
curl -X GET "https://app.tolgee.io/v2/projects/with-stats?page=0&size=10" \
  -H "X-API-Key: tgpat_xxxxxxxxxxxxxxxxxxxx"
```

--------------------------------

### Export Project Data with Curl

Source: https://github.com/tolgee/tolgee-platform/blob/main/webapp/src/views/projects/integrate/guides/Rest.mdx

This example demonstrates how to export project data using curl, save it to a zip file, and then unzip it. Ensure you replace placeholders with your actual API URL and key.

```shell
curl "{{{apiUrl}}}/v2/projects/export?ak={{{apiKey}}}" \
--output data.zip
unzip data.zip
rm data.zip
```

--------------------------------

### TraceQL Basic Filters

Source: https://github.com/tolgee/tolgee-platform/blob/main/docs/local-observability-stack/6_Practical_Reference.md

Examples of basic filtering in TraceQL, including service name, HTTP route, duration, and status.

```traceql
# Basic filters
{resource.service.name="tolgee-platform"}
{span.http.route="/v2/projects/{projectId}"}
{duration > 500ms}
{status=error}
```

--------------------------------

### Open E2E Development Environment

Source: https://github.com/tolgee/tolgee-platform/blob/main/e2e/README.md

Launch the E2E testing environment in development mode. This task typically starts the necessary services and prepares for test execution.

```shell
./gradlew openE2eDev
```

--------------------------------

### Example Database Operation

Source: https://github.com/tolgee/tolgee-platform/blob/main/docs/local-observability-stack/2_Understanding_Traces_and_Spans.md

This format indicates a database span, showing the SQL operation and the schema/table involved. It helps in identifying the specific database activity.

```text
SELECT tolgee.project
```

--------------------------------

### Run Batch MT Job with Multiple Pods and Redis

Source: https://github.com/tolgee/tolgee-platform/blob/main/e2e/scripts/batch/readme.md

This script tests the batch job orchestration mechanism. It builds the JAR, starts Redis and multiple Tolgee instances, initiates a NO_OP batch job, monitors its progress, and reports the total execution time. Use this script to test multi-instance coordination overhead.

```bash
./e2e/scripts/batch/run-batch-mt-job-with-2-pods-and-redis.sh [-k NUM_ITEMS] [-n NUM_INSTANCES] [-C CONCURRENCY] [-p START_PORT] [-c POSTGRES_CONTAINER] [-r REDIS_CONTAINER] [-P POSTGRES_PORT] [-R REDIS_PORT]
```

```bash
./e2e/scripts/batch/run-batch-mt-job-with-2-pods-and-redis.sh -k 10000 -n 3 -C 20
```

```bash
./e2e/scripts/batch/run-batch-mt-job-with-2-pods-and-redis.sh
```

```bash
./e2e/scripts/batch/run-batch-mt-job-with-2-pods-and-redis.sh -n 3
```

```bash
./e2e/scripts/batch/run-batch-mt-job-with-2-pods-and-redis.sh -n 3 -k 1000
```

```bash
./e2e/scripts/batch/run-batch-mt-job-with-2-pods-and-redis.sh -n 5
```

--------------------------------

### Prometheus Histogram Buckets Example

Source: https://github.com/tolgee/tolgee-platform/blob/main/docs/local-observability-stack/4_Metrics_From_Traces.md

Illustrates how Prometheus histograms track observations by counting values within defined buckets, using the 'le' label for upper bounds.

```text
latency_bucket{le="0.1"}   = 2   <- 2 requests were <=100ms
latency_bucket{le="0.5"}   = 4   <- 4 requests were <=500ms
latency_bucket{le="1"}     = 5   <- 5 requests were <=1s
latency_bucket{le="+Inf"}  = 5   <- 5 requests total
```

--------------------------------

### Get Streaming Machine Translation Suggestions

Source: https://context7.com/tolgee/tolgee-platform/llms.txt

Use this endpoint for real-time machine translation suggestions. Ensure the 'Accept' header is set to 'application/x-ndjson'.

```bash
curl -X POST "https://app.tolgee.io/v2/projects/1/suggest/machine-translations-streaming" \
  -H "X-API-Key: tgpak_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: application/x-ndjson" \
  -d '{
    "keyId": 100,
    "targetLanguageId": 2
  }'
```

--------------------------------

### Start Batch Pre-translate by Translation Memory Job

Source: https://context7.com/tolgee/tolgee-platform/llms.txt

Begin a batch job to pre-translate keys using matches found in the translation memory. This helps in efficiently translating content based on existing translations.

```bash
curl -X POST "https://app.tolgee.io/v2/projects/1/start-batch-job/pre-translate-by-tm" \
  -H "X-API-Key: tgpak_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "keyIds": [100, 101, 102],
    "targetLanguageIds": [2, 3]
  }'
```

--------------------------------

### Typed React Query Hooks

Source: https://github.com/tolgee/tolgee-platform/blob/main/AGENTS.md

Use typed React Query hooks from `useQueryApi.ts` for API communication in the frontend. This example shows a GET query and a POST mutation.

```typescript
// Query example
const { data, isLoading } = useApiQuery({
  url: '/v2/projects/{projectId}/languages',
  method: 'get',
  path: { projectId: project.id },
});

// Mutation example
const mutation = useApiMutation({
  url: '/v2/projects/{projectId}/languages',
  method: 'post',
  invalidatePrefix: '/v2/projects',
});

const handleSubmit = (data) => {
  mutation.mutate({
    path: { projectId: project.id },
    content: data,
  });
};
```

--------------------------------

### Initialize Tolgee Instance

Source: https://github.com/tolgee/tolgee-platform/blob/main/webapp/src/views/projects/integrate/guides/Web.mdx

Set up the Tolgee instance using the imported modules. Ensure you replace placeholder API keys and URLs with your actual credentials. This configuration includes essential modules like InContextTools, FormatSimple, and BackendFetch.

```javascript
// index.js
const { Tolgee, InContextTools, FormatSimple, BackendFetch } =
  window['@tolgee/web'];

const tolgee = Tolgee()
  .use(InContextTools())
  .use(FormatSimple())
  .use(BackendFetch())
  .init({
    // ############################################################
    // ## you should never leak your API key                     ##
    // ## remove it in for production publicly accessible site   ##
    // ############################################################
    apiKey: '{{{apiKey}}}',
    apiUrl: '{{{apiUrl}}}',
    defaultLanguage: 'en',
    observerType: 'text',
    observerOptions: { inputPrefix: '{{', inputSuffix: '}}' },
  });

tolgee.run();
```

--------------------------------

### Get Translations with Keys (Paginated)

Source: https://context7.com/tolgee/tolgee-platform/llms.txt

Get detailed translation data with key information, states, and metadata.

```APIDOC
## GET /v2/projects/{projectId}/translations

### Description
Get detailed translation data with key information, states, and metadata.

### Method
GET

### Endpoint
/v2/projects/{projectId}/translations

### Parameters
#### Path Parameters
- **projectId** (integer) - Required - The ID of the project.

#### Query Parameters
- **languages** (string) - Required - A comma-separated list of language tags (e.g., "en,de").
- **page** (integer) - Optional - The page number for pagination (default is 0).
- **size** (integer) - Optional - The number of items per page (default is 50).
- **filterState** (string) - Optional - Filter translations by their state (e.g., "UNTRANSLATED").
- **filterKeyName** (string) - Optional - Filter translations by key name pattern (e.g., "home.*", supports glob patterns).

### Response
#### Success Response (200)
- **_embedded.keys** (array of objects) - A list of key objects, each containing key details and translations.
  - **keyId** (integer) - The ID of the key.
  - **keyName** (string) - The name of the key.
  - **keyNamespace** (string) - The namespace of the key.
  - **translations** (object) - An object containing translations for different languages.
    - **(language_tag)** (object) - Translation details for a specific language.
      - **id** (integer) - The ID of the translation.
      - **text** (string) - The translated text.
      - **state** (string) - The state of the translation (e.g., "REVIEWED", "TRANSLATED").
      - **auto** (boolean) - Indicates if the translation was automatically generated.

### Response Example
```json
{
  "_embedded": {
    "keys": [
      {
        "keyId": 100,
        "keyName": "home.welcome.title",
        "keyNamespace": "common",
        "translations": {
          "en": { "id": 200, "text": "Welcome!", "state": "REVIEWED", "auto": false },
          "de": { "id": 201, "text": "Willkommen!", "state": "TRANSLATED", "auto": true }
        }
      }
    ]
  }
}
```
```

--------------------------------

### Initialize Tolgee SDK

Source: https://github.com/tolgee/tolgee-platform/blob/main/webapp/src/views/projects/integrate/guides/AndroidJetpackCompose.mdx

Initialize the Tolgee SDK in your Application class. Configure content delivery with your CDN URL and storage provider.

```kotlin
class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        Tolgee.init {
            contentDelivery {
                url = "https://cdn.tolg.ee/your-cdn-url-prefix"
                storage = TolgeeStorageProviderAndroid(this@MyApplication, BuildConfig.VERSION_CODE)
            }
        }
    }
}
```

--------------------------------

### Get Translation Flow

Source: https://github.com/tolgee/tolgee-platform/blob/main/webapp/src/views/projects/integrate/guides/AndroidJetpackCompose.mdx

Access the underlying translation Flow directly to get translated strings with fallback to Android resources.

```kotlin
// Get a translation with fallback to Android resources as a Flow
val textFlow = tolgee.tFlow(context, R.string.string_key)
```

--------------------------------

### Create Project

Source: https://context7.com/tolgee/tolgee-platform/llms.txt

Create a new localization project within an organization, specifying initial languages and the base language tag. Requires a PAT for authentication.

```bash
curl -X POST "https://app.tolgee.io/v2/projects" \
  -H "X-API-Key: tgpat_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mobile App",
    "organizationId": 1,
    "languages": [
      {"tag": "en", "name": "English", "originalName": "English"},
      {"tag": "de", "name": "German", "originalName": "Deutsch"},
      {"tag": "fr", "name": "French", "originalName": "Français"}
    ],
    "baseLanguageTag": "en"
  }'

# Response:
# {
#   "id": 1,
#   "name": "Mobile App",
#   "slug": "mobile-app",
#   "baseLanguage": { "id": 1, "tag": "en", "name": "English" },
```

--------------------------------

### Initialize Tolgee with VueTolgee

Source: https://github.com/tolgee/tolgee-platform/blob/main/webapp/src/views/projects/integrate/guides/Vue.mdx

Initialize Tolgee with necessary plugins and configure it with environment variables or static data. Then, use VueTolgee to make it available throughout your Vue app.

```ts
import { Tolgee, DevTools, VueTolgee, FormatSimple } from '@tolgee/vue';

const tolgee = Tolgee()
  .use(DevTools())
  .use(FormatSimple())
  .init({
    language: 'en',

    // for development
    apiUrl: process.env.VITE_APP_TOLGEE_API_URL,
    apiKey: process.env.VITE_APP_TOLGEE_API_KEY,

    // for production
    staticData: {
      ...
    }
  });

...app.use(VueTolgee, { tolgee });
...
```

--------------------------------

### Monitor p95 Latency for GET /v2/projects

Source: https://github.com/tolgee/tolgee-platform/blob/main/docs/local-observability-stack/6_Practical_Reference.md

Use this PromQL query to track the 95th percentile latency for the GET /v2/projects endpoint over a 5-minute rate window. Useful for identifying slowdowns.

```promql
histogram_quantile(0.95, sum(rate(traces_spanmetrics_latency_bucket{span_name="GET /v2/projects"}[5m])) by (le))
```

--------------------------------

### Run Backend Tests with Gradle

Source: https://github.com/tolgee/tolgee-platform/blob/main/DEVELOPMENT.md

Use the Gradle wrapper to execute all backend unit and integration tests.

```shell
./gradlew test
```

--------------------------------

### Get Translations using Extension Functions

Source: https://github.com/tolgee/tolgee-platform/blob/main/webapp/src/views/projects/integrate/guides/AndroidViews.mdx

Utilize extension functions for a more concise way to get translations, which also fall back to Android string resources. These functions simplify translation retrieval.

```kotlin
// Get a translation with fallback to Android resources
val text = context.getStringT(R.string.string_key)

// Get a translation with fallback to Android resources with parameters
val textWithParams = context.getStringT(R.string.string_with_params, "param1", "param2")
```

--------------------------------

### Alert on High Error Rate for GET /v2/projects

Source: https://github.com/tolgee/tolgee-platform/blob/main/docs/local-observability-stack/6_Practical_Reference.md

This PromQL alert expression triggers if the error rate for the GET /v2/projects endpoint exceeds 5% over a 5-minute window. Useful for catching error spikes early.

```promql
sum(rate(traces_spanmetrics_calls_total{span_name="GET /v2/projects", status_code="STATUS_CODE_ERROR"}[5m]))
/
sum(rate(traces_spanmetrics_calls_total{span_name="GET /v2/projects"}[5m]))
> 0.05
```

--------------------------------

### Set up environment variables for Tolgee

Source: https://github.com/tolgee/tolgee-platform/blob/main/webapp/src/views/projects/integrate/guides/Next.mdx

Configure development environment variables for Tolgee API key and URL in your .env.development.local file.

```dotenv
NEXT_PUBLIC_TOLGEE_API_KEY={{{apiKey}}}
NEXT_PUBLIC_TOLGEE_API_URL={{{apiUrl}}}
```

--------------------------------

### Alert on High p95 Latency for GET /v2/projects

Source: https://github.com/tolgee/tolgee-platform/blob/main/docs/local-observability-stack/6_Practical_Reference.md

This PromQL alert expression triggers if the 95th percentile latency for the GET /v2/projects endpoint exceeds 1 second for 5 minutes. Use to catch slowdowns before users notice.

```promql
histogram_quantile(0.95, sum(rate(traces_spanmetrics_latency_bucket{span_name="GET /v2/projects"}[5m])) by (le)) > 1
```

--------------------------------

### Get Organization

Source: https://context7.com/tolgee/tolgee-platform/llms.txt

Retrieve organization details by ID or slug.

```APIDOC
## Get Organization

### Description
Retrieve organization details by ID or slug.

### Method
GET

### Endpoint
/v2/organizations/{organizationIdOrSlug}

### Parameters
#### Path Parameters
- **organizationIdOrSlug** (string or integer) - Required - The ID or slug of the organization to retrieve.

### Request Example
```bash
# Get by ID
curl -X GET "https://app.tolgee.io/v2/organizations/1" \
  -H "X-API-Key: tgpat_xxxxxxxxxxxxxxxxxxxx"

# Get by slug
curl -X GET "https://app.tolgee.io/v2/organizations/my-company" \
  -H "X-API-Key: tgpat_xxxxxxxxxxxxxxxxxxxx"
```

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier of the organization.
- **name** (string) - The name of the organization.
- **slug** (string) - The unique slug of the organization.
- **description** (string) - The description of the organization.
- **basePermissions** (object) - The base permissions for the organization.
- **currentUserRole** (string) - The role of the current user within the organization.

#### Response Example
```json
{
  "id": 1,
  "name": "My Company",
  "slug": "my-company",
  "description": "Organization for all company projects",
  "basePermissions": { "type": "VIEW" },
  "currentUserRole": "OWNER"
}
```
```

--------------------------------

### Get All Translations

Source: https://context7.com/tolgee/tolgee-platform/llms.txt

Retrieve all translations for specified languages, structured by key name.

```APIDOC
## GET /v2/projects/{projectId}/translations/{languages}

### Description
Retrieve all translations for specified languages, structured by key name.

### Method
GET

### Endpoint
/v2/projects/{projectId}/translations/{languages}

### Parameters
#### Path Parameters
- **projectId** (integer) - Required - The ID of the project.
- **languages** (string) - Required - A comma-separated list of language tags (e.g., "en,de,fr").

#### Query Parameters
- **structureDelimiter** (string) - Optional - The delimiter to use for nested structures. If empty, a flat structure is returned.
- **ns** (string) - Optional - Filter translations by namespace.
- **filterTag** (string) - Optional - Filter translations by tag. Can be specified multiple times.

### Response
#### Success Response (200)
- **(object)** - An object where keys are language tags and values are translation objects, potentially nested.

### Response Example
```json
{
  "en": {
    "home": {
      "welcome": {
        "title": "Welcome to our app!"
      }
    },
    "button": {
      "submit": "Submit"
    }
  },
  "de": {
    "home": {
      "welcome": {
        "title": "Willkommen in unserer App!"
      }
    }
  }
}
```
```

--------------------------------

### Understanding Counters and rate() in PromQL

Source: https://github.com/tolgee/tolgee-platform/blob/main/docs/local-observability-stack/4_Metrics_From_Traces.md

Explains how to use the `rate()` function in PromQL to calculate the per-second increase of counter metrics over a specified time window. This is essential for understanding current behavior from cumulative metrics.

```promql
rate(traces_spanmetrics_calls_total[5m])   -> 300  (requests per second, averaged over last 5 minutes)
```

--------------------------------

### Create Tolgee Instance

Source: https://github.com/tolgee/tolgee-platform/blob/main/webapp/src/views/projects/integrate/guides/Js.mdx

Initialize a Tolgee instance with essential plugins like DevTools, FormatSimple, and BackendFetch. Ensure API keys are kept secret and not exposed in production.

```javascript
import { Tolgee, FormatSimple, DevTools, BackendFetch } from '@tolgee/web';

const tolgee = Tolgee()
  .use(DevTools())
  .use(FormatSimple())
  .use(BackendFetch())
  .init({
    // ############################################################
    // ## you should never leak your API key                     ##
    // ## remove it in for production publicly accessible site   ##
    // ############################################################
    apiKey: '{{{apiKey}}}',
    apiUrl: '{{{apiUrl}}}',
    defaultLanguage: 'en',
    observerType: 'text',
    observerOptions: { inputPrefix: '{{', inputSuffix: '}}' },
  });

tolgee.run();
```

--------------------------------

### POST /v2/projects/{projectId}/suggest/translation-memory

Source: https://context7.com/tolgee/tolgee-platform/llms.txt

Get suggestions from previously translated similar texts.

```APIDOC
## POST /v2/projects/{projectId}/suggest/translation-memory

### Description
Get suggestions from previously translated similar texts.

### Method
POST

### Endpoint
https://app.tolgee.io/v2/projects/1/suggest/translation-memory

### Parameters
#### Header Parameters
- **X-API-Key** (string) - Required - Your API key.
- **Content-Type** (string) - Required - Should be `application/json`.

#### Request Body
Either `keyId` or `baseText` is required.
- **keyId** (integer) - Optional - The ID of the key for which to get suggestions.
- **baseText** (string) - Optional - The base text to find similar translations for.
- **targetLanguageId** (integer) - Required - The ID of the target language.

### Request Example (by keyId)
```json
{
  "keyId": 100,
  "targetLanguageId": 2
}
```

### Request Example (by baseText)
```json
{
  "baseText": "Welcome to our application",
  "targetLanguageId": 2
}
```

### Response
#### Success Response (200)
- **_embedded.translationMemoryItems** (array) - A list of translation memory items.
  - **baseTranslation** (string) - The original translation.
  - **targetTranslation** (string) - The translated text.
  - **keyName** (string) - The name of the key.
  - **similarity** (number) - The similarity score.

### Response Example
```json
{
  "_embedded": {
    "translationMemoryItems": [
      {
        "baseTranslation": "Welcome to the app",
        "targetTranslation": "Willkommen in der App",
        "keyName": "app.welcome",
        "similarity": 0.85
      }
    ]
  }
}
```
```

--------------------------------

### Configure Local Development Environment for Tolgee App Translations

Source: https://github.com/tolgee/tolgee-platform/blob/main/DEVELOPMENT.md

Create a `.env.development.local` file in the `webapp` directory to specify the API URL and API key for connecting to the Tolgee app for using current translations.

```properties
VITE_APP_TOLGEE_API_URL=https://app.tolgee.io
VITE_APP_TOLGEE_API_KEY=your-tolgee-api-key
```

--------------------------------

### Configure Development Environment Variables

Source: https://github.com/tolgee/tolgee-platform/blob/main/webapp/src/views/projects/integrate/guides/Svelte.mdx

Add your Tolgee API URL and key to the .env.development.local file for development environments.

```dotenv
VITE_TOLGEE_API_URL={{{apiUrl}}}
VITE_TOLGEE_API_KEY={{{apiKey}}}
```

--------------------------------

### Get Organization Details

Source: https://context7.com/tolgee/tolgee-platform/llms.txt

Retrieve organization details by its ID or slug. Requires a PAT for authentication.

```bash
# Get by ID
curl -X GET "https://app.tolgee.io/v2/organizations/1" \
  -H "X-API-Key: tgpat_xxxxxxxxxxxxxxxxxxxx"

# Get by slug
curl -X GET "https://app.tolgee.io/v2/organizations/my-company" \
  -H "X-API-Key: tgpat_xxxxxxxxxxxxxxxxxxxx"
```

--------------------------------

### Get Translation History

Source: https://context7.com/tolgee/tolgee-platform/llms.txt

Retrieve the history of changes for a specific translation, including previous texts, states, timestamps, and authors.

```APIDOC
## GET /v2/projects/{projectId}/translations/{translationId}/history

### Description
View the history of changes for a specific translation.

### Method
GET

### Endpoint
/v2/projects/{projectId}/translations/{translationId}/history

### Parameters
#### Path Parameters
- **projectId** (integer) - Required - The ID of the project.
- **translationId** (integer) - Required - The ID of the translation.

#### Query Parameters
- **page** (integer) - Optional - The page number for pagination (default: 0).
- **size** (integer) - Optional - The number of items per page (default: 20).

### Response
#### Success Response (200)
- **_embedded.revisions** (array) - An array of revision objects.
  - **text** (string) - The translation text at the time of the revision.
  - **state** (string) - The state of the translation at the time of the revision.
  - **timestamp** (integer) - The Unix timestamp when the revision occurred.
  - **author** (object) - Information about the author of the revision.
    - **id** (integer) - The ID of the author.
    - **name** (string) - The name of the author.

#### Response Example
```json
{
  "_embedded": {
    "revisions": [
      {
        "text": "Welcome aboard!",
        "state": "REVIEWED",
        "timestamp": 1704153600000,
        "author": { "id": 1, "name": "John Doe" }
      },
      {
        "text": "Welcome to our app!",
        "state": "TRANSLATED",
        "timestamp": 1704067200000,
        "author": { "id": 2, "name": "Jane Smith" }
      }
    ]
  }
}
```
```

--------------------------------

### Run Tolgee Backend with Development Profile

Source: https://github.com/tolgee/tolgee-platform/blob/main/DEVELOPMENT.md

Execute the Gradle wrapper to run the backend application with the 'dev' Spring profile, enabling development-specific configurations.

```shell
./gradlew server-app:bootRun --args='--spring.profiles.active=dev'
```

--------------------------------

### Use Tolgee Service for Translation in TypeScript

Source: https://github.com/tolgee/tolgee-platform/blob/main/webapp/src/views/projects/integrate/guides/Angular.mdx

Inject the translate service to get translations programmatically in your component's TypeScript code.

```typescript
this.translateService
  .get('hello_world')
  .subscribe((r) => (this.helloWorld = r));
```

--------------------------------

### TraceQL Query with Regex Negation

Source: https://github.com/tolgee/tolgee-platform/blob/main/docs/local-observability-stack/3_Navigating_Grafana_Tempo.md

Employ the `!~` operator to exclude traces matching a specific pattern, like routes that do not start with '/v2/public'.

```traceql
{span.http.route!~"/v2/public.*"}
```

--------------------------------

### Create Organization

Source: https://context7.com/tolgee/tolgee-platform/llms.txt

Create a new organization to group projects and manage team members. Requires a PAT for authentication.

```bash
curl -X POST "https://app.tolgee.io/v2/organizations" \
  -H "X-API-Key: tgpat_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Company",
    "slug": "my-company",
    "description": "Organization for all company projects"
  }'

# Response:
# {
#   "id": 1,
#   "name": "My Company",
#   "slug": "my-company",
#   "description": "Organization for all company projects",
#   "basePermissions": { "type": "VIEW" },
#   "currentUserRole": "OWNER"
# }
```

--------------------------------

### TraceQL Query with Regex Matching

Source: https://github.com/tolgee/tolgee-platform/blob/main/docs/local-observability-stack/3_Navigating_Grafana_Tempo.md

Use the `=~` operator for pattern matching in trace attributes, such as finding routes that start with '/v2/projects'.

```traceql
{span.http.route=~"/v2/projects.*"}
```

--------------------------------

### List Projects with Pagination

Source: https://context7.com/tolgee/tolgee-platform/llms.txt

Retrieves a paginated list of all projects accessible by the authenticated user. Use 'sort' to order the results.

```bash
curl -X GET "https://app.tolgee.io/v2/projects?page=0&size=20&sort=name" \
  -H "X-API-Key: tgpat_xxxxxxxxxxxxxxxxxxxx"
```

--------------------------------

### TraceQL Database Filtering

Source: https://github.com/tolgee/tolgee-platform/blob/main/docs/local-observability-stack/6_Practical_Reference.md

Examples of filtering database spans in TraceQL by system and duration, useful for diagnosing database-related performance issues.

```traceql
# Database
{span.db.system="postgresql"}
{span.db.system="postgresql" && duration > 50ms}
```

--------------------------------

### TraceQL Query for Nested Attributes

Source: https://github.com/tolgee/tolgee-platform/blob/main/docs/local-observability-stack/6_Practical_Reference.md

Query nested attributes using dot notation. This example filters for spans that have an authorization header.

```traceql
{span.http.request.header.authorization != ""}
```

--------------------------------

### Login to Tolgee CLI

Source: https://github.com/tolgee/tolgee-platform/blob/main/webapp/src/views/projects/integrate/guides/Cli.mdx

Authenticate with your Tolgee project using your API key. Replace {{{apiKey}}} with your actual API key.

```sh
tolgee login "{{{apiKey}}}"
```

--------------------------------

### Get All Translations for Specified Languages

Source: https://context7.com/tolgee/tolgee-platform/llms.txt

Retrieve all translations for specified languages, structured by key name. You can control the structure delimiter and filter by namespace or tags.

```bash
# Get translations for multiple languages
curl -X GET "https://app.tolgee.io/v2/projects/1/translations/en,de,fr" \
  -H "X-API-Key: tgpak_xxxxxxxxxxxxxxxxxxxx"
```

```json
# Response (with default '.' delimiter for nested structure):
# {
#   "en": {
#     "home": {
#       "welcome": {
#         "title": "Welcome to our app!"
#       }
#     },
#     "button": {
#       "submit": "Submit"
#     }
#   },
#   "de": {
#     "home": {
#       "welcome": {
#         "title": "Willkommen in unserer App!"
#       }
#     }
#   }
# }
```

```bash
# Get flat structure (no nesting)
curl -X GET "https://app.tolgee.io/v2/projects/1/translations/en?structureDelimiter=" \
  -H "X-API-Key: tgpak_xxxxxxxxxxxxxxxxxxxx"
```

```bash
# Filter by namespace
curl -X GET "https://app.tolgee.io/v2/projects/1/translations/en?ns=common" \
  -H "X-API-Key: tgpak_xxxxxxxxxxxxxxxxxxxx"
```

```bash
# Filter by tags
curl -X GET "https://app.tolgee.io/v2/projects/1/translations/en?filterTag=homepage&filterTag=important" \
  -H "X-API-Key: tgpak_xxxxxxxxxxxxxxxxxxxx"
```

--------------------------------

### Configure Tolgee Provider in Storybook

Source: https://github.com/tolgee/tolgee-platform/blob/main/storybook-tolgee-addon/README.md

Set up the Tolgee provider in your `.storybook/preview.js` file. Configure message format, locales, and standard Tolgee options.

```javascript
import { withTolgeeProvider } from '@tolgee/storybook-addon';
import { LocalizationProvider } from '@mui/x-date-pickers';

export default {
  decorators: [
    withTolgeeProvider({
      messageFormat: 'icu',
      locales: {
        en: { name: 'English', flag: '🇬🇧' },
        cs: { name: 'Čeština', flag: '🇨🇿' },
      },
      LocalizationProvider: LocalizationProvider,
      tolgee: {
        language: 'en',
        apiUrl: 'https://app.tolgee.io',
        apiKey: '<your API key>',
      },
    }),
  ],
};
```

--------------------------------

### Start Batch Tag Keys Job

Source: https://context7.com/tolgee/tolgee-platform/llms.txt

Perform a batch operation to add tags to multiple translation keys at once. This is useful for organizing and categorizing keys.

```bash
curl -X POST "https://app.tolgee.io/v2/projects/1/start-batch-job/tag-keys" \
  -H "X-API-Key: tgpak_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "keyIds": [100, 101, 102],
    "tags": ["reviewed", "v2.0"]
  }'
```

--------------------------------

### List All Keys in Project

Source: https://context7.com/tolgee/tolgee-platform/llms.txt

Retrieves all translation keys within a project, supporting pagination and sorting. Branch filtering is available if the feature is enabled.

```bash
curl -X GET "https://app.tolgee.io/v2/projects/1/keys?page=0&size=100&sort=name" \
  -H "X-API-Key: tgpak_xxxxxxxxxxxxxxxxxxxx"
```

```bash
# Filter by branch (if branching feature enabled)
curl -X GET "https://app.tolgee.io/v2/projects/1/keys?branch=feature-x" \
  -H "X-API-Key: tgpak_xxxxxxxxxxxxxxxxxxxx"
```

--------------------------------

### Export Translations as JSON

Source: https://context7.com/tolgee/tolgee-platform/llms.txt

Export translations from a project. This example shows exporting as JSON, which is the default format. Specify languages and optionally a structure delimiter.

```bash
# Export as JSON (default)
curl -X GET "https://app.tolgee.io/v2/projects/1/export?format=JSON&languages=en,de" \
  -H "X-API-Key: tgpak_xxxxxxxxxxxxxxxxxxxx" \
  -o translations.zip
```

```bash
# Export as nested JSON for specific languages
curl -X GET "https://app.tolgee.io/v2/projects/1/export?format=JSON&structureDelimiter=.&languages=en" \
  -H "X-API-Key: tgpak_xxxxxxxxxxxxxxxxxxxx" \
  -o en.json
```

--------------------------------

### Publish New MCP Server Version

Source: https://github.com/tolgee/tolgee-platform/blob/main/docs/mcp-server/README.md

Log in to GitHub using mcp-publisher and then publish the new server version. Ensure your GitHub organization membership is public.

```bash
mcp-publisher login github && mcp-publisher publish
```

--------------------------------

### List All Tags in Project

Source: https://context7.com/tolgee/tolgee-platform/llms.txt

Retrieve a list of all tags currently used within a specific project. Pagination parameters 'page' and 'size' can be used to manage the results.

```bash
curl -X GET "https://app.tolgee.io/v2/projects/1/tags?page=0&size=100" \
  -H "X-API-Key: tgpak_xxxxxxxxxxxxxxxxxxxx"
```

--------------------------------

### Start Batch Delete Keys Job

Source: https://context7.com/tolgee/tolgee-platform/llms.txt

Initiate a batch operation to delete multiple translation keys simultaneously. Ensure you have the correct key IDs before proceeding.

```bash
curl -X POST "https://app.tolgee.io/v2/projects/1/start-batch-job/delete-keys" \
  -H "X-API-Key: tgpak_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "keyIds": [100, 101, 102]
  }'
```

--------------------------------

### Create Project

Source: https://context7.com/tolgee/tolgee-platform/llms.txt

Create a new localization project within an organization with initial languages.

```APIDOC
## Create Project

### Description
Create a new localization project within an organization with initial languages.

### Method
POST

### Endpoint
/v2/projects

### Parameters
#### Request Body
- **name** (string) - Required - The name of the project.
- **organizationId** (integer) - Required - The ID of the organization to which the project belongs.
- **languages** (array of objects) - Required - An array of initial languages for the project. Each object should have `tag`, `name`, and `originalName` properties.
- **baseLanguageTag** (string) - Required - The tag of the base language for the project.

### Request Example
```json
{
  "name": "Mobile App",
  "organizationId": 1,
  "languages": [
    {"tag": "en", "name": "English", "originalName": "English"},
    {"tag": "de", "name": "German", "originalName": "Deutsch"},
    {"tag": "fr", "name": "French", "originalName": "Français"}
  ],
  "baseLanguageTag": "en"
}
```

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier of the project.
- **name** (string) - The name of the project.
- **slug** (string) - The unique slug of the project.
- **baseLanguage** (object) - Information about the base language.
  - **id** (integer) - The ID of the base language.
  - **tag** (string) - The tag of the base language (e.g., "en").
  - **name** (string) - The name of the base language (e.g., "English").

#### Response Example
```json
{
  "id": 1,
  "name": "Mobile App",
  "slug": "mobile-app",
  "baseLanguage": {"id": 1, "tag": "en", "name": "English"}
}
```
```

--------------------------------

### TraceQL Query Combining Conditions

Source: https://github.com/tolgee/tolgee-platform/blob/main/docs/local-observability-stack/6_Practical_Reference.md

Combine multiple conditions to refine trace queries. Examples include filtering by HTTP method and duration, or by status codes.

```traceql
{span.http.request.method="GET" && duration > 100ms}
```

```traceql
{span.http.response.status_code=404 || span.http.response.status_code=500}
```

```traceql
{span.http.route=~"/v2/projects.*" && status=error}
```

--------------------------------

### PromQL Selectors and Label Matchers

Source: https://github.com/tolgee/tolgee-platform/blob/main/docs/local-observability-stack/4_Metrics_From_Traces.md

Demonstrates how to filter metrics using label matchers in PromQL. Includes exact matches, regex matches, and negative matches.

```promql
# Exact match
traces_spanmetrics_calls_total{span_name="GET /v2/projects"}

# Regex match (=~ operator)
traces_spanmetrics_calls_total{span_name=~"GET.*"}

# Not equal
traces_spanmetrics_calls_total{status_code!="STATUS_CODE_ERROR"}

# Negative regex match
traces_spanmetrics_calls_total{span_name!~"SELECT.*"}
```