Deliver translation updates to your app.

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
• Flutter OTA setup
• DartNative delivery
• React Native delivery
• Compare integrations
• Bring your agent’s wording through MCP

Try it in the browser

Open the file checker, paste plain text, flat JSON, nested ICU JSON, native i18next JSON, or a Flutter ARB file, and choose your languages. You can use the included example.

CLI

Install the CLI in your app. Requires Node.js 22.16 or later.

npm install --save-dev @translocale/cli

Plan a translation:

npx translocale plan \
  --file examples/app_en.arb \
  --format arb \
  --source en \
  --targets fr,de \
  --json

Check a translated file:

npx translocale check \
  --source examples/app_en.arb \
  --target examples/app_fr.arb \
  --format arb \
  --json

Suggest a source language before planning:

npx translocale detect \
  --file welcome.txt \
  --format text \
  --api https://translocale.io \
  --json

Confirm or correct the suggestion before passing it to plan. Short, ambiguous, or detected mixed-language samples return an uncertain result. Detection does not consume translation allowance.

Connect a project through your browser:

npx translocale login \
  --api https://translocale.io \
  --scope translate

npx translocale usage \
  --api https://translocale.io \
  --project PROJECT_ID \
  --json

npx translocale logout --api https://translocale.io

Login lets you choose a project and approve its permissions. It saves a credential for 30 days in your local TransLocale configuration. Use read access for inspection or translate access to start jobs. Logout revokes the saved credential. For CI, set TRANSLOCALE_TOKEN in your secret store instead.

The CLI runs checks locally by default. Add --api https://translocale.io to send the specified content to this service. A failing check exits with code 1.

TypeScript SDK

Typed client with ESM and CommonJS exports.

npm install @translocale/client

import { TransLocaleClient } from "@translocale/client";

const client = new TransLocaleClient({
  baseUrl: "https://translocale.io",
});

const plan = await client.plan({
  content: JSON.stringify({
    welcome: "Hello {name}",
  }),
  format: "json",
  sourceLocale: "en",
  targetLocales: ["fr"],
});

Saved project operations use a project credential in server or CI configuration. The SDK supports jobs, approved reuse, reviews, and pinned exports. Job creation requires an explicit character cap and idempotency key. Keep authoring credentials out of browser and mobile application bundles.

Saved project context

Create a project, set its languages, and add your product description, tone, and glossary. Generate a project credential and store it as TRANSLOCALE_TOKEN in your shell or tool's secret settings.

npx translocale projects list --api https://translocale.io --json

npx translocale projects get \
  --id PROJECT_ID \
  --api https://translocale.io \
  --json

With CLI 0.7.0 or later and write access, add a target language to an existing cloud project:

npx translocale projects add-language --api https://translocale.io --id PROJECT_ID --locale fr-CA

The command checks the current project version and preserves existing languages. Projects have no fixed language-count limit. Adding a language uses no translation allowance; update your app's locale configuration separately.

To replace context, save a JSON file with description, tone, and glossary. Use the latest version returned by projects get:

npx translocale projects context \
  --id PROJECT_ID \
  --file context.json \
  --expected-version 1 \
  --api https://translocale.io \
  --json

A read-only credential cannot edit context. A conflicting version returns CONFLICT; read the current project and reconcile your changes before retrying. Credentials work with one project, expire within 90 days, and can be revoked from its web page.

Translate a project

Choose Edit and translate when creating a project credential. Review the file first, then authorize the maximum number of characters the job can use.

npx translocale translate \
  --project PROJECT_ID \
  --file examples/app_en.arb \
  --format arb \
  --dry-run

npx translocale translate \
  --project PROJECT_ID \
  --file examples/app_en.arb \
  --format arb \
  --max-characters 1000

npx translocale jobs get \
  --project PROJECT_ID \
  --id JOB_ID \
  --watch

npx translocale jobs export \
  --project PROJECT_ID \
  --id JOB_ID \
  --locale fr \
  --out app_fr.arb

Set TRANSLOCALE_API_URL to your endpoint. The CLI prints an idempotency key and project version before submission. Retry with the same input plus --idempotency-key and --expected-project-version to reuse that request. Downloads never overwrite existing files.

Characters count source text that needs translation, including spaces and message syntax, for each target language. Failed or cancelled jobs return their reserved allowance. Translation execution must be enabled on the service before these commands can start a job.

Review and correct translations

Open Review from a completed job to edit its wording. Each save keeps a separate revision, checks keys and placeholders, and preserves source ARB metadata. Manual corrections use no translation allowance.

npx translocale reviews get \
  --project PROJECT_ID \
  --job JOB_ID \
  --locale fr \
  --api https://translocale.io

npx translocale reviews save \
  --project PROJECT_ID \
  --job JOB_ID \
  --locale fr \
  --file app_fr.arb \
  --expected-revision 0 \
  --api https://translocale.io

npx translocale reviews export \
  --project PROJECT_ID \
  --job JOB_ID \
  --locale fr \
  --revision 1 \
  --out app_fr_reviewed.arb \
  --api https://translocale.io

Use the revision number from a fresh read when saving. A conflict keeps the existing revision. CLI saves default to draft; add --approve when approval is intended. Revision 0 and jobs export return the original job output. MCP provides get_translation_review and save_translation_revision for the same workflow.

Update an existing source file

Select a completed job to compare added, changed, removed, and unchanged keys. Enable approved reuse to copy unchanged wording from each language’s latest approved revision. A newer draft or changed project context prevents reuse.

npx translocale translate \
  --project PROJECT_ID \
  --file updated_en.arb \
  --format arb \
  --base-job PREVIOUS_JOB_ID \
  --reuse-approved \
  --dry-run

Review the estimate, then start with --max-characters. Confirm source removals with --allow-removed-keys. Fully reused exports accept --max-characters 0 and need no translation allowance. Previous jobs and corrections stay available.

Submission diagnostics also include expectedReuseVersion. Preserve it with --expected-reuse-version when retrying the same request. REST and MCP take baseJobId, reuseApproved, expectedReuseVersion, and allowRemovedKeys for the same workflow.

Framework integrations

Start with the integration directory for framework-specific setup guides, tested versions, and current compatibility limits.

Current file support is plain text, flat JSON, nested ICU JSON, native i18next JSON v4, Vue I18n JSON, and ARB. See the framework guides for package installation, tested versions, and compatibility notes.

For i18next, choose format i18next. Target plural variants are included in usage estimates and review. The current adapter uses default JSON v4 separators, native interpolation, static nested references, and markup. Custom separators and nested reference options are not supported yet.

translocale check \
  --source en.json \
  --target ar.json \
  --format i18next \
  --source-locale en \
  --target-locale ar

For Vue I18n, choose vue-i18n. Named and list placeholders, linked messages, and literal interpolations retain their structure. Plural messages use Vue's default two- or three-form rule. The Vue package includes Nuxt setup and local Cloudflare rendering verified. Custom pluralRules are not supported yet.

translocale check \
  --source en.json \
  --target fr.json \
  --format vue-i18n

Use exports in Flutter

ARB exports retain placeholder descriptions, types, and formatting metadata. Install the published Flutter tooling as a development dependency and follow the framework guide to initialize your project. Native Dart commands handle sign-in, planning, translation, and pinned downloads:

flutter pub add --dev translocale_flutter:^0.3.2

Flutter ARB setup and sync guide

dart run translocale_flutter:translocale login \
  --scope translate

dart run translocale_flutter:translocale plan

dart run translocale_flutter:translocale check

The Dart package uses Flutter’s default use-escaping: falsemode. Strict-mode imports are not supported. Catalog sync previews a three-way merge and requires an explicit plan hash to apply it. The main CLI has a separate flutter-exportconversion for strict-mode output. Review wording in your app before release.

React Native and Expo

Connect an existing i18next app with @translocale/react-native. Deliver approved wording, keep bundled translations available at startup, and restore a saved release offline.

Follow the React Native and Expo guide for installation, native Intl setup, a recorded demo, and verification limits.

DartNative

Use translocale_dartnative for native iOS and Android apps built with DartNative. Bundle ARB translations for offline use, switch languages, and optionally download approved wording updates.

Add these entries to your app's pubspec.yaml, keeping its existing DartNative dependencies:

dependencies:
  dartnative_system: ^1.0.0
  dartnative_path_provider: ^1.0.0
  translocale_dartnative:
    hosted: https://dartpub.dev
    version: ^0.2.2

dn pub get

Follow the DartNative setup guide for a working app example, OTA configuration, and a narrated demo. Bundled translations work without an account. OTA delivery needs a published release and a read-only delivery token; keep authoring credentials out of the app.

Using Codex or Claude Code? Install the TransLocale AI skill and share the DartNative guide with your assistant.

HTTP API

GET  /api/v1/capabilities
POST /api/v1/language-detection
POST /api/v1/plans
POST /api/v1/validation
GET  /api/v1/projects
GET  /api/v1/projects/:id
PUT  /api/v1/projects/:id/context
POST /api/v1/projects/:id/plans
POST /api/v1/projects/:id/jobs
GET  /api/v1/projects/:id/jobs
GET  /api/v1/projects/:id/jobs/:jobId
POST /api/v1/projects/:id/jobs/:jobId/cancel
GET  /api/v1/projects/:id/jobs/:jobId/exports/:locale

Planning accepts content, format, sourceLocale, and targetLocales. Validation accepts source, target, and format. Both return structured JSON and do not persist files or start AI jobs.

Saved project endpoints require an Authorization: Bearer credential header or a browser session. Context updates accept context and expectedVersion. Cookie-authenticated writes also require the application Origin header.

MCP

Connect your assistant to check catalogs, plan capped translation jobs, and review changes before publishing.

Follow the MCP localization guide for Codex and Claude Code skills, browser sign-in, a read-only validation example, and connection troubleshooting.

Supported files

Plain text, flat JSON string maps, nested ICU JSON, native i18next JSON v4, Vue I18n JSON, and ARB files with metadata. Up to 100 KB, and 200 messages per source document. Locale identifiers use BCP 47 notation, such as fr-CA.

Plain text accepts pasted wording or a .txt file. Each nonempty line is translated separately; exports preserve line breaks, blank lines, and indentation. Braces and markup are literal text. Split long paragraphs into lines before starting a job; each serialized line must fit within the 6 KB message limit.

Checks cover message syntax, missing keys, and placeholder mismatches. They do not certify translation quality. Word counts include message syntax and are estimates, not billing quotes.

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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "@@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
• React and i18next plural checks
• Next.js and next-intl ICU checks
• Vue and Nuxt setup
• SvelteKit with i18next
• Flutter ARB setup
• DartNative ARB setup