CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-formatjs--cli

A comprehensive CLI for internationalization workflows with message extraction, compilation, and verification capabilities.

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

verification.mddocs/

Translation Verification

Comprehensive verification system for translation files that checks for missing keys and structural compatibility between source and target locales, ensuring translation completeness and consistency.

Note: Verification functionality is only available via the CLI command interface and is not exported for programmatic use.

Capabilities

Verify Command

Runs verification checks on translation files to ensure quality and completeness.

/**
 * Verify translation files for completeness and consistency
 * @param translation_files - Glob patterns for translation files to verify
 * @param --source-locale - The source locale to compare against
 * @param --missing-keys - Check for missing keys in target locales
 * @param --structural-equality - Check structural consistency between locales
 * @param --ignore - Glob patterns to ignore
 */
formatjs verify [translation_files...] --source-locale <locale> [options]

Verification Options

interface VerifyOpts {
  /** The source locale of the translation files */
  sourceLocale: string;
  /** Whether to check for missing keys in target locale */
  missingKeys: boolean;
  /** Whether to check for structural equality between locales */
  structuralEquality: boolean;
  /** List of glob paths to ignore */
  ignore?: string[];
}

Missing Keys Check

Verifies that all keys present in the source locale are also present in target locales.

Structural Equality Check

Verifies that message structures (plurals, selects, arguments) are consistent between locales.

CLI Usage

Basic Verification

# Verify all translations against English source
formatjs verify 'translations/*.json' --source-locale en --missing-keys --structural-equality

# Verify with specific source locale format
formatjs verify 'locales/*.json' --source-locale en-US --missing-keys --structural-equality

Missing Keys Check Only

# Check only for missing translation keys
formatjs verify 'translations/*.json' --source-locale en --missing-keys

# With ignore patterns
formatjs verify 'translations/*.json' --source-locale en --missing-keys --ignore 'translations/test-*.json'

Structural Equality Check Only

# Check only structural consistency
formatjs verify 'translations/*.json' --source-locale en --structural-equality

Advanced Verification Options

# Verify with multiple ignore patterns
formatjs verify 'translations/**/*.json' \
  --source-locale en-US \
  --missing-keys \
  --structural-equality \
  --ignore 'translations/draft-*.json' 'translations/**/test-*.json'

# Verify specific file patterns
formatjs verify 'locales/production/*.json' \
  --source-locale en \
  --missing-keys \
  --structural-equality

Verification Types

Missing Keys Verification

Ensures that every message key present in the source locale file is also present in all target locale files. This guarantees that no messages are left untranslated.

Example Issues Detected:

  • Key "welcome.title" exists in en.json but missing from fr.json
  • Source has 150 keys, target has only 147 keys

Structural Equality Verification

Ensures that the ICU MessageFormat structure of messages is consistent between locales. This catches issues where:

  • Plural rules are missing or incorrect
  • Select options don't match
  • Message arguments are missing or misnamed
  • HTML tags are incorrectly structured

Example Issues Detected:

Source (en.json):

{
  "cart.items": "{count, plural, one {# item} other {# items}}"
}

Target (fr.json) - Invalid:

{
  "cart.items": "{count} éléments"
}

The French translation is missing the plural structure.

Error Reporting

When verification fails, the CLI exits with code 1 and provides detailed error information:

$ formatjs verify 'translations/*.json' --source-locale en --missing-keys --structural-equality

[@formatjs/cli] [ERROR] Missing keys found:
  fr.json missing: welcome.subtitle, navigation.home
  es.json missing: welcome.subtitle

[@formatjs/cli] [ERROR] Structural equality issues found:
  fr.json: cart.items - Missing plural structure
  es.json: profile.settings - Missing select options: [theme, language]

Process exited with code 1

Best Practices

Translation Workflow Integration

# In CI/CD pipeline - fail build on verification issues
formatjs verify 'translations/*.json' --source-locale en --missing-keys --structural-equality
if [ $? -ne 0 ]; then
  echo "Translation verification failed - blocking deployment"
  exit 1
fi

Staged Verification

# Check only missing keys during active development
formatjs verify 'translations/*.json' --source-locale en --missing-keys

# Full verification before release
formatjs verify 'translations/*.json' --source-locale en --missing-keys --structural-equality

File Organization

Organize translation files for effective verification:

translations/
├── en.json          # Source locale
├── fr.json          # Target locales
├── es.json
├── de.json
└── draft/           # Ignored development files
    ├── experimental-en.json
    └── experimental-fr.json

Use ignore patterns to exclude development files:

formatjs verify 'translations/*.json' --source-locale en --missing-keys --ignore 'translations/draft/*'

docs

compilation.md

extraction.md

formatters.md

index.md

verification.md

tile.json