# General Translation Integrations: Quickstart
URL: https://generaltranslation.com/en-US/docs/integrations/paraglide/quickstart.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Translate your Paraglide JS message files with General Translation and keep them updated in CI.

Keep Paraglide JS as your i18n library. The CLI translates your message files, such as `messages/en.json` into `messages/de.json`, and Paraglide JS compiles them into the same typed message functions you already call. Translations stay in your repository.

## How it works [#how-it-works]

- [`gt translate`](/docs/cli/reference/commands/translate) reads your base-locale message file and writes a translated file for each target locale next to it.
- Only the text is translated. Message keys, placeholders such as `{count}`, [markup](https://paraglidejs.com/markup), nested message objects, and [variants](https://paraglidejs.com/variants) such as plurals keep their structure.
- Translations follow the Glossary and Custom Prompts in the [Context Groups](/docs/platform/dashboard/guides/defining-context-for-translations) assigned to your project, so product names and terminology stay consistent.
- Run it again whenever your source messages change, locally or in CI. With [`saveLocal`](/docs/cli/reference/config#save-local), edits you make to [supported message strings](#supported-messages) are kept on later runs.
- Your app's code and Paraglide JS configuration stay unchanged.

```json title="messages/en.json"
{
  "$schema": "https://inlang.com/schema/inlang-message-format",
  "title": "Welcome back, {name}!",
  "nav": {
    "account": {
      "settings": "Settings",
      "sign_out": "Sign out"
    }
  },
  "cart_items": [
    {
      "declarations": ["input count", "local countPlural = count: plural"],
      "selectors": ["countPlural"],
      "match": {
        "countPlural=one": "You have {count} item in your cart",
        "countPlural=*": "You have {count} items in your cart"
      }
    }
  ]
}
```

```json title="messages/de.json"
{
  "$schema": "https://inlang.com/schema/inlang-message-format",
  "title": "Willkommen zurück, {name}!",
  "nav": {
    "account": {
      "settings": "Einstellungen",
      "sign_out": "Abmelden"
    }
  },
  "cart_items": [
    {
      "declarations": ["input count", "local countPlural = count: plural"],
      "selectors": ["countPlural"],
      "match": {
        "countPlural=one": "Sie haben {count} Artikel in Ihrem Warenkorb",
        "countPlural=*": "Sie haben {count} Artikel in Ihrem Warenkorb"
      }
    }
  ]
}
```

## Before you start [#before-start]

You need:

- Node.js 20 or later.
- A Paraglide JS project whose messages use the inlang message format (`plugin.inlang.messageFormat` in `project.inlang/settings.json`), such as `messages/en.json`.
- A General Translation account. A free Organization draws from a rolling allowance of platform credits, so you can start without a payment method. (See [Managing billing](/docs/platform/dashboard/guides/managing-billing)).

## Quickstart [#quickstart]

Set up the CLI, add the rules for your message files, then translate and check the results.

### 1. Set up the CLI

Install `gt` as a development dependency:

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm install --save-dev gt
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add --dev gt
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add --dev gt
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add --save-dev gt
    ```
  </Tab>
</Tabs>

Then run [`gt init`](/docs/cli/reference/commands/init):

```bash
npx gt init --no-react-setup --file-patterns "json=messages/[locale].json" --dev-credentials
```

Follow the prompts to sign in and choose your languages. Use the `baseLocale` from `project.inlang/settings.json` as the default locale, and choose target locales from its `locales`. If your messages have plurals, check [Supported messages](#supported-messages) first.

- `--no-react-setup` leaves your app's code unchanged. If setup suggests installing `gt-react`, skip it: Paraglide JS keeps rendering your messages.
- `--file-patterns` points the CLI at your message files. It matches the `pathPattern` in `project.inlang/settings.json`, with `[locale]` in place of `{locale}`; change it if your messages live elsewhere.
- `--dev-credentials` creates or selects a project and saves its ID to `.env.local`.

<Callout type="info">
  **Coding agents:** [`gt init`](/docs/cli/reference/commands/init) needs a signed-in user. Run [`gt login --no-browser`](/docs/cli/reference/commands/login) and ask the user to approve the sign-in link it prints. Add `--json` to the [`gt init`](/docs/cli/reference/commands/init) command above for structured output and non-interactive setup, along with `--default-locale` and `--locales`. Reuse an existing project with `--project-id`; use `--create-project --project-name <name>` only when a new project is needed (with `--org-id` when the user belongs to more than one Organization). [`gt init`](/docs/cli/reference/commands/init) lists any options it still needs.
</Callout>

### 2. Configure your message files

Merge the `options` block below into the `gt.config.json` that [`gt init`](/docs/cli/reference/commands/init) created. Keep its `defaultLocale`, `locales`, and `files`.

If your messages live elsewhere, change the `jsonSchema` key to match their paths too. For example, `json=locales/[locale].json` needs `"locales/*.json"` in place of `"messages/*.json"` below. The rule only protects files whose paths match its key.

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["de", "fr"],
  "files": {
    "json": {
      "include": ["messages/[locale].json"]
    }
  },
  "options": {
    "saveLocal": true,
    "jsonSchema": {
      "messages/*.json": {
        "include": [
          "$..[?(typeof @ === 'string' && @property !== '$schema' && !(typeof @property === 'number' && (@parentProperty === 'declarations' || @parentProperty === 'selectors')))]"
        ]
      }
    }
  }
}
```

- `jsonSchema` selects the text of every message for translation, including nested messages and each variant. It skips the `$schema` URL and the `declarations` and `selectors` of variants, so message structure stays unchanged.
- [`saveLocal`](/docs/cli/reference/config#save-local) keeps edits you make to [supported message strings](#supported-messages) on later runs.

<Callout type="warn">
  Keep the `jsonSchema` rule for inlang message files. Without it, the declarations and selectors of variants, such as `input count`, can be translated, and Paraglide JS can no longer compile the translated files.
</Callout>

### 3. Translate your messages

<Callout type="warn">
  The first run rewrites each target-locale file from your source messages, including translations already in it. Commit your message files first, then review the diff and restore any existing translations you want to keep.
</Callout>

Run [`gt translate`](/docs/cli/reference/commands/translate):

```bash
npx gt translate
```

The CLI writes a message file for each target locale, such as `messages/de.json`, and a `gt-lock.json` file that records the downloaded translations so later runs can detect your edits. Paraglide JS compiles the new files like any other message file.

Check the translated files with the inlang CLI, version 3.4.0 or later:

```bash
npx @inlang/cli check --project ./project.inlang
```

The check reports missing translations, missing variables, and unused messages. Commit your message files and `gt-lock.json`.

### 4. Translate in CI

Run [`gt translate`](/docs/cli/reference/commands/translate) before your build so new and changed messages are translated on every push. Add two secrets to your CI provider:

- `GT_API_KEY`: a [project API key](/docs/platform/dashboard/reference/api-keys#create-project-keys) with **Files > Write**, **Translation queue > Enabled**, and **Context > Write** permissions. The development key in `.env.local` cannot run translations. (See [Use an explicit key for CI](/docs/cli/guides/configuring#credentials)).
- `GT_PROJECT_ID`: the project ID that [`gt init`](/docs/cli/reference/commands/init) saved to `.env.local`.

```yaml title=".github/workflows/build.yml"
- run: npx gt translate
  env:
    GT_API_KEY: ${{ secrets.GT_API_KEY }}
    GT_PROJECT_ID: ${{ secrets.GT_PROJECT_ID }}
- run: npx @inlang/cli check --project ./project.inlang
```

Run this step only in workflows that can read your secrets, such as pushes to your main branch, not pull requests from forks. Commit the updated message files and `gt-lock.json` through a pull request so you can review translations before they ship.

## Supported messages [#supported-messages]

The CLI translates messages in the inlang message format:

- Plain messages and messages with placeholders
- [Markup](https://paraglidejs.com/markup), such as links and emphasis
- Nested message objects
- [Variants](https://paraglidejs.com/variants), such as plurals

End each plural variant in your source messages with a `*` branch, such as `countPlural=*`, instead of `countPlural=other`. When a target language uses a plural form your source messages lack, such as the form French and Spanish use for large round numbers, Paraglide JS falls back to the `*` branch.

### Languages with more plural forms

Plural messages that need more forms in the target language than in your source language are not supported yet. For example, Russian, Ukrainian, Polish, Czech, and Arabic use extra forms for everyday numbers that English does not. The CLI does not create those forms or keep ones you add by hand, so these messages use the wrong grammar for some numbers and fail `inlang check`.

If your message files contain plurals, leave these languages out of `locales` in `gt.config.json` for now. If they contain no plurals, these languages work like any other.

## Next steps

- /docs/integrations/paraglide/guides/adding-source-context
- /docs/integrations/paraglide/guides/resolving-imports
- /docs/integrations/paraglide/guides/adding-file-formats

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.
