Check translation keys and placeholders before deployment

A translated file can be valid JSON and still break a screen. A message may be missing, or a translator may have changed a parameter that your app supplies. Put a source-to-target check before the application build so those mistakes fail the same pipeline as a type error.

This guide uses TransLocale's CLI with two small flat JSON files. The check runs locally unless you explicitly supply an API endpoint. It does not need an account, upload these files, or start a translation job.

Reproduce a placeholder failure

Save this source as locales/en.json:

{
  "welcome": "Hello, {name}",
  "save": "Save changes"
}

Now save this target as locales/fr.json:

{
  "welcome": "Bonjour, {firstName}",
  "save": "Enregistrer les modifications"
}

The French greeting uses firstName, while the app supplies name. Both files parse as JSON, but the messages disagree about their input.

From your application directory, install the CLI and compare the files. It requires Node.js 22.16 or later.

npm install --save-dev @translocale/cli
npx translocale check --source locales/en.json --target locales/fr.json --format json

The command reports the parameter mismatch and exits with status 1. Change {firstName} to {name} and run it again. The corrected pair passes. Removing the save message from the target also produces a validation failure.

Put the check before the build

Add a script to your existing package.json, preserving its other scripts:

{
  "scripts": {
    "check:translations": "translocale check --source locales/en.json --target locales/fr.json --format json"
  }
}

Commit the dependency lockfile and both catalogs. In your existing CI job, run the check after installation and before the app build:

npm ci
npm run check:translations
npm run build

Configure these as normal sequential CI steps so a nonzero exit stops the job. Avoid continue-on-error for the translation check. For several target languages, compare each target with the source, or use your framework package's command to check its configured catalogs.

This catches structural mistakes before deployment. It does not tell you whether the French wording is natural, whether a button fits, or whether the wrong but structurally valid catalog was selected for release. Those need review and application testing.

Match the checker to the message format

The .json extension does not identify the message syntax. Our example is a flat map with brace placeholders. A next-intl app should use icu-json; native i18next catalogs need i18next plus the source and target locale flags. Vue I18n uses vue-i18n, and Flutter catalogs use arb.

When the app already uses a TransLocale framework package, these commands read its local configuration:

# React / i18next
npx translocale-i18next check

# Next.js / next-intl
npx translocale-next check

# Vue or Nuxt
npx translocale-vue check

# SvelteKit
npx translocale-svelte check

Run the command for your installed integration. For Flutter, dart run translocale_flutter:translocale check invokes flutter gen-l10n and can regenerate local Dart output. Use the generic ARB comparison as well when you need an explicit source-to-target check.

Keep translation outside normal builds

A build should consume reviewed catalog files. Run translation as a separate, intentional operation with an explicit character cap, then review and save the output before adding it to the application.

Start with the format examples if you are unsure which adapter applies. The framework guides cover configuration and package-specific limits. If you only have a source file, try the browser checker; comparing an existing target requires the CLI or the validation MCP tool.