---
title: "Tolgee"
description: "Use Tolgee for MainSDK translations - project and API key, main.yaml, locales, missing strings caught by the check, testing and swapping."
section: "integrations"
canonical: "https://mainsdk.dev/docs/integrations/tolgee"
updated: "2026-10-28"
---

# Tolgee

> Use Tolgee for MainSDK translations - project and API key, main.yaml, locales, missing strings caught by the check, testing and swapping.

Canonical: https://mainsdk.dev/docs/integrations/tolgee · Updated: 2026-10-28

Tolgee is an open-source localization platform with in-context translation, available as a cloud service or self-hosted. Behind [`i18n`](https://mainsdk.dev/docs/interfaces/i18n), it holds your translations while your code keeps calling `t()`. Pick it when you want an open-source tool your team can host.

> **Note:** `i18n` has no spec yet. The options on this page are provisional and may change when the spec lands.

## Interfaces it serves

### Languages and formats (`i18n`)

- Status: Preview · ships as a beta API
- Driver: `tolgee` (Tolgee)
- Docs: https://mainsdk.dev/docs/interfaces/i18n.md

```yaml
i18n:
  driver: tolgee
```

Swap to another provider: `files`, `crowdin`, `lokalise`, `ai-draft`.

## Before you start

1. Create a Tolgee project, on Tolgee Cloud or your own instance, with the languages you ship.
2. Create a project API key.
3. Store the key in your secrets manager.

## Configure

```yaml title="main.yaml"
i18n:
  driver: tolgee
  locales: [en-IN, hi-IN, ta-IN]
  # [TBD] instance URL, and the API key as secret:TOLGEE_API_KEY
```

## Use it

```ts title="app/orders/heading.ts"
import { t } from "mainsdk";

export function heading(orders: unknown[]) {
  return t("orders.count", { count: orders.length });
}
```

## Local development and testing

Build with the default `files` driver and switch to `tolgee` when translators join. In tests, `createTestApp()` from `@mainsdk/testing` runs `i18n` without a network, and `chaos.on("i18n", { outage: true })` simulates Tolgee being unreachable.

## What MainSDK adds on top

- A missing translation fails the check, not the user.
- Formats from Unicode CLDR, and the locale from the user's choice first, never guessed from IP alone.

See [Languages and formats](https://mainsdk.dev/docs/interfaces/i18n).

## Limits and notes

- Planned driver from the product requirements; `i18n` has no spec yet.
- How strings sync between your repo and Tolgee is not defined yet [TBD].

## Swap to or from it

```yaml title="main.yaml"
i18n:
  driver: tolgee   # was files
```

> **Warning:** Translations live in Tolgee. Export them before you switch to another driver; how strings move between drivers is not decided yet [TBD].

## FAQ

**Can I self-host Tolgee?** Yes, Tolgee can be self-hosted. How the driver is pointed at your instance is [TBD].

## Next

- [Languages and formats](https://mainsdk.dev/docs/interfaces/i18n) and [Translate your app](https://mainsdk.dev/docs/guides/i18n)
- [Crowdin](https://mainsdk.dev/docs/integrations/crowdin) and [Lokalise](https://mainsdk.dev/docs/integrations/lokalise)