Skip to content
Saimul Islam

translation-facts: translation quality assurance for numbers, prices and placeholders

Translation quality assurance for the facts in a string: check that numbers, prices, percentages, URLs, emails and {placeholders} survive translation.

Install
npm install translation-facts

Overview

A machine or AI translation can read fine and still change $49.99 to $59.99, drop 20%, translate {name} to {nom} or point a link at the wrong page. translation-facts is a translation checker for exactly that. It pulls the facts out of each source string (numbers, prices, percentages, URLs, emails, {placeholders} and terms you want kept) and checks that every one of them is still in the translation.

Tools such as i18next-cli and i18n-check compare keys and placeholders, but not whether the numbers, prices and links inside the text survived. translation-facts has no dependencies and works on JSON message files (flat or nested, i18next and next-intl style) or on single strings, so it fits localization QA in CI.

Examples

Compare translation files with a source file
npx translation-facts en.json de.json fr.json --keep Acme
Sample output
de.json: 6 problems
  pricing.title: missing Acme (term)
  pricing.standard: changed $49.99 -> 49,99 € (price)
  pricing.discount: missing 20% (percent)
  pricing.contact: changed https://acme.example/pricing -> https://acme.example/preise (url)
  pricing.contact: changed [email protected] -> [email protected] (email)
  cart.greeting: changed {name} -> {nom} (token)
fr.json: ok (6 keys checked)

6 problems in 1 of 2 files.
Check one string
import { compareFacts } from 'translation-facts';

compareFacts('Only $7 for 2 seats, save 20%', 'Nur $8 für 2 Plätze');
// {
//   missing: [{ kind: 'percent', value: '20%', key: 'percent:20%' }],
//   changed: [{ kind: 'price', from: { value: '$7', ... }, to: { value: '$8', ... } }],
//   extra: [],
// }
Check a whole file from code
import { readFileSync } from 'node:fs';
import { checkTranslations } from 'translation-facts';

const source = JSON.parse(readFileSync('en.json', 'utf8'));
const target = JSON.parse(readFileSync('de.json', 'utf8'));

const { ok, problems } = checkTranslations(source, target, { keepTerms: ['Acme'] });

Features

01Numbers in any notation
1,000, 1.000, 1 000 and 1000 are one fact, and so are 7.50 and 7,5. Bengali, Thai, Devanagari and Arabic-Indic digits are read as Latin ones.
02Prices with currency
A symbol or ISO code before or after the amount, so $49.99, 49,99 $ and 49.99 USD are one fact. The currency is part of the fact, so a silent conversion shows up as a change.
03Percentages, URLs and emails
20%, 20 % and 12,5% are percentages. URLs compare by host, path, query and hash, and emails compare case-insensitively.
04Placeholders
{name}, {{name}}, { name } and {{ user.name }} compare by bare name, so a translated placeholder such as {nom} is caught.
05Terms to keep
Pass product names with --keep. They must appear unchanged, matched as whole words in any script. keepTermsFrom() reads them from a style guide line such as Keep in English: Acme, Free.
06JSON message files
Flat and nested files can be mixed, and each target file is checked key by key against the source. The exit code is 1 when there are problems, so it fits CI.

CLI usage

Usage
translation-facts <source.json> <target.json> [more targets...] [--keep term,term] [--extra] [--json]
--keep <terms>
Terms that must appear unchanged, such as product names. Comma separated, can be repeated.
--extra
Also report facts a translation adds that the source does not have.
--json
Print the result as JSON instead of text.
-v, --version
Print the version.
-h, --help
Print the usage.

Limits

  • It checks facts, not meaning or grammar. A translation can pass and still be wrong.
  • Facts are compared as a set. How often a fact appears and where are not checked.
  • A last group of exactly three digits after a separator reads as grouping, so 3.141 is read as 3141.
  • Prices are recognised by symbol or ISO code only. Currency words and abbreviations such as kr or zł are not, so 49,99 zł is read as the number 49.99.
  • Only {name} and {{name}} style placeholders are recognised. %s, %d, {0} and ICU message syntax are not parsed.
  • Dates, times and phone numbers have no special handling, so a reformatted date such as 2026-11-20 to 20.11.2026 is reported as a problem.
  • The CLI reads JSON files only. For other formats, parse them yourself and call checkTranslations.

Frequently asked questions

How do I check that a machine translation kept my prices and numbers?

Run npx translation-facts en.json de.json. For every key it compares the numbers, prices, percentages, URLs, emails and placeholders in the source string with the translation, and lists what is missing or changed.

Does it find missing translations?

No. Keys that are missing or empty in a target file are skipped, because that is a question for a key-parity tool. translation-facts checks the facts inside the strings that are there.

Can I use it for localization QA in CI?

Yes. The CLI exits 0 when there are no problems, 1 when it finds any and 2 for a usage or file error, and --json prints the problems in a structured form. It works on i18next and next-intl style JSON files.

Does it work as i18n testing for AI translations?

Yes, that is the use case it was built for: it was extracted from Sitessa, where it checks translations before they are saved. It does not judge fluency or meaning, so keep a human review for that.

  • Web QA

    static-preflight

    A broken link checker and launch checklist for a static site build: SEO basics, links and assets, redirects, share cards, icons, JSON-LD and old-URL coverage.

  • AI agents

    mcp-guardrails

    AI agent guardrails for MCP servers: dry run and confirm, signed preview tokens, optimistic concurrency, revision undo and errors that teach the agent.

See all 9 open-source packages

Author

Built by Saimul Islam

Saimul Islam is a Forward Deployed Engineer and Solutions Architect. Several of these packages run in production on DeveloperLook, the Bundlewise CRM and Sitessa.