# TransLocale developer quick start

Bring your translations, review them, and deliver compatible wording updates to your app. Work through the dashboard, CLI, MCP server, or REST API.

Canonical page: https://translocale.io/docs

## Deliver updates to your app

TransLocale lets solo developers and teams publish approved wording to compatible installed apps without compiling a new build for each update. Bring translations from your AI agent, a translator, or existing language files. Using TransLocale’s AI translation service is optional.

First, add a supported delivery integration to your app, bundle its fallback translations, and ship that build. Configure the project, release schema, app version, and read-only delivery credential using your framework’s guide. An app that has not integrated delivery needs a build before it can receive updates.

In your project, open Catalogs → Import files. Import source and translated files, inspect the preview, and apply it. Review and approve the wording in the editor. A solo project owner can do this without inviting a team. Imports and manual edits do not start translation jobs.

Open Releases to create a snapshot of approved wording. Publish it to Preview and verify it in your connected app, then promote that release to Production. Compatible apps fetch it on their next delivery check. Offline apps retain bundled or cached wording; rollback selects a previous compatible release.

OTA delivers translation data. It does not change app code or add screens. New keys, locales, or parameter contracts can require a matching schema and a new app build. Framework catalog tooling does not automatically include OTA support; check the integration’s delivery instructions.

- [First project, keys, and app credentials](https://translocale.io/docs/getting-started)
- [Flutter OTA setup](https://translocale.io/integrations/flutter#ota)
- [DartNative delivery](https://translocale.io/integrations/dartnative)
- [React Native delivery](https://translocale.io/integrations/react-native)
- [Compare integrations](https://translocale.io/integrations)
- [Bring your agent’s wording through MCP](https://translocale.io/docs/mcp#bring-your-own-translations)

## Install and check locally

Requires Node.js 22.16 or later. Run these commands from your application directory. Planning and validation do not start translation jobs.

```bash
npm install --save-dev @translocale/cli
```

```bash
npx translocale plan --file app_en.arb --format arb --source en --targets fr --json
npx translocale check --source app_en.arb --target app_fr.arb --format arb --json
```

## JSON translation examples: choose the right format

The .json extension does not identify a translation format. Choose the format your application's localization library reads. A plain string map, an ICU plural expression, and i18next plural keys follow different rules.

Flat JSON uses a top-level map of message strings. Choose json in the CLI or Flat JSON in the browser. This example has a name placeholder to preserve in the target file.

Flat JSON example:

```json
{
  "welcome": "Hello, {name}"
}
```

Nested ICU JSON supports namespace objects and ICU expressions. Choose icu-json in the CLI or Nested ICU JSON in the browser for next-intl catalogs.

Nested ICU JSON example:

```json
{
  "Cart": {
    "greeting": "Hello, {name}",
    "items": "{count, plural, =0 {Your cart is empty} one {# item} other {# items}}"
  }
}
```

i18next JSON v4 uses {{name}} interpolation and plural suffix keys. Choose i18next and provide the source locale. For the service's combined document, wrap messages in a namespace such as checkout; local package files keep namespaces in separate files.

Combined i18next document:

```json
{
  "checkout": {
    "items_one": "{{count}} item",
    "items_other": "{{count}} items"
  }
}
```

Vue I18n JSON uses its own message syntax, including pipe-separated plural choices. Choose vue-i18n in the CLI or Vue I18n JSON in the browser for the supported Vue and Nuxt integration.

Vue I18n JSON example:

```json
{
  "cart": {
    "items": "No items | One item | {count} items"
  }
}
```

Flutter ARB adds locale and message metadata to JSON. Choose arb for .arb files, keeping placeholder metadata with the message. The Flutter and DartNative guides explain their respective app setup.

ARB example:

```json
{
  "@@locale": "en",
  "welcome": "Hello, {name}",
  "@welcome": {
    "placeholders": {
      "name": {
        "type": "String"
      }
    }
  }
}
```

Paste one example into the source checker and select its format. A successful check means the file passes the planning rules. To compare existing source and target files for missing keys or placeholder changes, use the CLI check command with the same format.

- [Try the source file checker](https://translocale.io/app)
- [React and i18next plural checks](https://translocale.io/integrations/i18next#pluralization)
- [Next.js and next-intl ICU checks](https://translocale.io/integrations/nextjs#pluralization)
- [Vue and Nuxt setup](https://translocale.io/integrations/vue)
- [SvelteKit with i18next](https://translocale.io/integrations/sveltekit)
- [Flutter ARB setup](https://translocale.io/integrations/flutter)
- [DartNative ARB setup](https://translocale.io/integrations/dartnative)

## Continue with your workflow

- [Full CLI and API documentation](https://translocale.io/docs)
- [MCP localization guide](https://translocale.io/docs/mcp)
- [Source file checker](https://translocale.io/app)
- [React Native & Expo](https://translocale.io/integrations/react-native)
- [DartNative](https://translocale.io/integrations/dartnative)
- [SvelteKit](https://translocale.io/integrations/sveltekit)
- [Next.js](https://translocale.io/integrations/nextjs)
- [React & i18next](https://translocale.io/integrations/i18next)
- [Vue & Nuxt](https://translocale.io/integrations/vue)
- [Flutter](https://translocale.io/integrations/flutter)