Skip to content

usage.md

Latest commit

 

History

History
269 lines (182 loc) · 7.76 KB

usage.md

File metadata and controls

269 lines (182 loc) · 7.76 KB

Usage Guide

Basic Workflow

1. Scan your locale directory

locale-sync scan ./locales
locale-sync scan                 # auto-discover locale directories from CWD
locale-sync scan ./my-project    # searches subdirectories if no locale files at root

Output:

📂 Locale files in: /path/to/locales

  Discovered 3 locale file(s)
┌──────┬─────────┬─────────────┐
│ #    │ File    │ Locale Code │
├──────┼─────────┼─────────────┤
│ 1    │ de.json │ de          │
│ 2    │ en.json │ en          │
│ 3    │ pl.json │ pl          │
└──────┴─────────┴─────────────┘

2. Check for missing keys

locale-sync check ./locales

Returns exit code 0 if all files are complete, 1 if missing keys are found.

3. Sync missing keys

locale-sync sync ./locales

Fills missing keys with source language text. Existing translations are never overwritten by default.

4. Translate missing keys

locale-sync translate ./locales

Detects missing keys and translates their values into the correct target language for each file.

How target language is resolved: The target language is derived from the filename stem — pl.json → Polish (pl), de.json → German (de), fr.json → French (fr).

How translate differs from sync:

  • sync copies the English source text into target files (useful when you want to manually translate later)
  • translate fills missing keys AND translates values into the target language

Translation providers:

translate uses Google Translate by default. Placeholders like {name}, {{count}}, ${amount} are automatically protected during translation via the PlaceholderAwareTranslator wrapper.

locale-sync translate ./locales                    # Google Translate (default)
locale-sync translate ./locales --provider demo    # Offline dictionary (5 languages, ~250 phrases)

A built-in DemoTranslator is available for offline and testing scenarios (--provider demo). It covers Polish, German, French, Spanish, and Italian with ~250 common i18n phrases.

Fallback behavior:

  • Translation available → real target-language translation
  • Translation unavailable (demo dictionary miss) → source text used as fallback (reported as FALLBACK in the sync report)
  • Translation failure (network error) → reported as failed, source text used as fallback

Progress and cancellation:

During translation, a live progress bar shows the current file, percentage, keys done/total, elapsed time, estimated time remaining, and how many languages have been processed:

⠋ ar.json ━━━━━━━━━━━━ 34%  94/279  0:00:13  ETA 0:00:28  [1/19 languages]

Press Ctrl+C at any time to cancel translation gracefully. When all target files are already complete, LocaleSync shows ✅ All N locale file(s) are already up to date — nothing to do. and exits immediately.

5. Preview changes

locale-sync sync ./locales --dry-run

Shows exactly what would change without modifying any files.

Auto-Discovery

LocaleSync can automatically find locale directories when the exact path doesn't exist or contains no locale files:

# Direct path — uses it if locale files are found there
locale-sync scan ./locales

# Project root — searches subdirectories for locale file groups
locale-sync scan .

# Non-existent path — searches from current working directory
locale-sync scan ./i18n

How it works:

  1. If the path contains locale JSON files → use it directly
  2. If the path exists but has no locale files → search its subdirectories
  3. If the path doesn't exist → search from CWD

Directories like node_modules/ and hidden directories (.git/, .next/) are automatically skipped. A directory qualifies as a locale directory if it contains at least 2 JSON files with valid locale code filenames.

Locale Code Validation

Files are only recognized as locale files if their name (without .json) matches a valid locale code:

✅ Valid ❌ Ignored
en.json, pl.json package.json, tsconfig.json
en-US.json, zh-Hans.json manifest.chrome.json
sr-Latn.json, pt-BR.json angular.json, translations.json

Pattern: 2–3 letter language code, optional region/script suffix (- or _ separator).

Source and Target Selection

Auto-detection

By default, LocaleSync:

  • Prefers en.json as the source file (falls back to the first file found)
  • Uses all other locale files as targets

Explicit selection

# Specify source
locale-sync check ./locales --source en-US.json

# Specify targets
locale-sync sync ./locales --target pl.json --target de.json

# Combine both
locale-sync sync ./locales --source en.json --target fr.json

Update Strategies

fill_missing (default)

Only adds keys that don't exist in the target file. Existing translations (even empty strings) are never touched.

locale-sync sync ./locales --strategy fill_missing

fill_empty

Adds missing keys AND fills values that are empty strings.

locale-sync sync ./locales --strategy fill_empty

force_overwrite

Overwrites all values from source. Use with caution — this will replace existing translations.

locale-sync sync ./locales --strategy force_overwrite

Key Ordering

By default, LocaleSync uses automatic key ordering:

  • Small files (≤200 keys): sorted alphabetically — keeps things tidy, minimal diff noise
  • Large files (>200 keys): insertion order preserved, new keys appended at end — avoids huge diffs from resorting

Override with explicit flags:

locale-sync sync ./locales --sort-keys      # always sort alphabetically
locale-sync sync ./locales --no-sort-keys   # never sort, new keys at end

Output Formats

Human-readable (default)

Rich-formatted terminal output with tables and colors.

JSON

Machine-readable JSON for CI/CD pipelines and tooling:

locale-sync check ./locales --format json
locale-sync sync ./locales --format json --dry-run

Safety Features

Dry Run

Preview all changes without modifying files:

locale-sync sync ./locales --dry-run

Backups

Create .bak backup files before modifying:

locale-sync sync ./locales --backup

Atomic Writes

File writes use temp-file-then-rename to prevent corruption on failure.

CI/CD Integration

GitHub Actions

name: Check Translations
on: [push, pull_request]

jobs:
  check-translations:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install locale-sync
      - run: locale-sync check ./locales

Exit Codes

Code Meaning When
0 Success Check passes, sync completes
1 Validation failure Missing keys found (check command)
2 Input error Bad directory, malformed JSON, missing source file
3 Runtime error Unexpected failure

Verbose Mode

Enable debug logging:

locale-sync -v check ./locales

5. Generate the Translations Dashboard

locale-sync dashboard ./locales                 # generates HTML and opens in browser
locale-sync dashboard ./locales --no-open       # generate without opening
locale-sync dashboard ./locales -o report.html  # custom output path
locale-sync dashboard ./locales -s en           # specify source locale

This generates a self-contained HTML dashboard with full translation management capabilities. See the Dashboard Guide for details.