Cross-Project Integration Guide

LocaleSync is a Python CLI tool, but it is designed to work with any repository that contains locale JSON files — including Angular, React, Vue, Node.js, Go, Ruby, and mixed/monorepo environments.

This guide explains how to install, configure, and use LocaleSync from non-Python projects.

Core Principle
Installation Models
Recommended Model by Context
Using From Non-Python Projects
NPM / package.json Integration
CI/CD for Non-Python Repositories
Standalone vs Embedded Architecture
Frontend Team Onboarding
Troubleshooting

Core Principle

LocaleSync operates on a directory of locale files. It does not care about the surrounding project structure, build system, or programming language. You point it at a directory containing .json locale files, and it works.

# Point directly at locale directory
locale-sync check /path/to/any/locales/directory

# Or let auto-discovery find locale files from project root
locale-sync check .

The tool makes no assumptions about:

what framework you use,
where your locale files live,
what build system manages your project.

All it needs is a path containing JSON locale files — or a parent directory to search. LocaleSync auto-discovers locale directories by finding groups of JSON files whose names match valid locale codes (e.g., en.json, pl.json). Non-locale files like package.json or tsconfig.json are ignored automatically.

Installation Models

1. From the LocaleSync repository (development)

git clone https://github.com/polprog-tech/LocaleSync.git
cd LocaleSync
pip install -e ".[dev]"

Best for: Contributors and developers working on LocaleSync itself.

2. From GitHub (direct install)

pip install git+https://github.com/polprog-tech/LocaleSync.git

Best for: CI pipelines, quick installs, teams that pin to a specific commit or tag.

Pin to a specific version:

pip install git+https://github.com/polprog-tech/LocaleSync.git@v1.1.0

Pin to a specific commit:

pip install git+https://github.com/polprog-tech/LocaleSync.git@abc1234

3. Via pipx (isolated CLI tool)

pipx install git+https://github.com/polprog-tech/LocaleSync.git

Best for: Developer machines where you want locale-sync available globally without polluting system Python or requiring a project-level virtual environment.

This is the recommended approach for frontend/non-Python developers who just want the CLI available on their machine.

4. Future: PyPI

pip install locale-sync
# or
pipx install locale-sync

Best for: Production usage once LocaleSync is published to PyPI.

Not yet available. PyPI publishing will be added when the project reaches a stable release.

Recommended Model by Context

Context	Recommended Installation	Why
Python project (own repo)	`pip install -e ".[dev]"`	Standard Python dev workflow
Angular/Node project (local dev)	`pipx install git+...`	Isolated, no venv needed
Angular/Node project (CI)	`pip install git+...`	Fast, cacheable, pinnable
Monorepo with Python	`pip install -e path/to/localesync`	Workspace install
Monorepo without Python	`pipx install git+...` or `pip install git+...`	Same as standalone
Developer machine (any project)	`pipx install git+...`	Global CLI, no per-project setup

Using From Non-Python Projects

Prerequisites

LocaleSync requires Python 3.12+. Most developer machines and CI environments already have Python available.

Check if Python is available:

python3 --version   # Should print 3.12+

If Python is not installed:

macOS: brew install python@3.12
Ubuntu/Debian: sudo apt install python3.12
CI (GitHub Actions): Use actions/setup-python@v5
Any OS: Download from python.org

Install pipx (recommended for non-Python projects):

# macOS
brew install pipx
pipx ensurepath

# Linux
python3 -m pip install --user pipx
python3 -m pipx ensurepath

# Then install LocaleSync
pipx install git+https://github.com/polprog-tech/LocaleSync.git

Basic Usage

Once installed, locale-sync is available as a system command:

# Point it at your locale directory — any project structure
locale-sync scan src/assets/i18n
locale-sync check src/assets/i18n
locale-sync sync src/assets/i18n --dry-run
locale-sync sync src/assets/i18n

NPM / package.json Integration

LocaleSync is not an npm package and does not need to be published to npm. It is invoked as an external CLI tool from npm scripts.

Adding Scripts to package.json

{
  "scripts": {
    "locales:scan": "locale-sync scan src/assets/i18n",
    "locales:check": "locale-sync check src/assets/i18n",
    "locales:check:json": "locale-sync check src/assets/i18n --format json",
    "locales:sync": "locale-sync sync src/assets/i18n --source en.json",
    "locales:sync:preview": "locale-sync sync src/assets/i18n --dry-run",
    "locales:sync:backup": "locale-sync sync src/assets/i18n --backup",
    "locales:translate": "locale-sync translate src/assets/i18n --source en.json",
    "locales:translate:preview": "locale-sync translate src/assets/i18n --dry-run"
  }
}

Usage

npm run locales:check          # Validate translations
npm run locales:sync:preview   # Preview sync changes
npm run locales:sync           # Sync missing keys

Important Notes

npm does not install LocaleSync. It invokes it as an external command.
LocaleSync must be installed separately via pip or pipx before running npm scripts.
Do not add LocaleSync to devDependencies. It is not an npm package.
npm scripts simply delegate to the locale-sync CLI — they are convenience aliases.

Alternative: npx-style Wrapper (Not Recommended)

You could theoretically create an npm wrapper package that installs Python and LocaleSync automatically, but this adds complexity, fragility, and cross-platform issues. The direct pipx install approach is simpler and more reliable.

CI/CD for Non-Python Repositories

GitHub Actions (Angular/Node Project)

name: Translation Check

on:
  push:
    paths:
      - 'src/assets/i18n/**'
  pull_request:
    paths:
      - 'src/assets/i18n/**'

jobs:
  check-translations:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Install LocaleSync
        run: pip install git+https://github.com/polprog-tech/LocaleSync.git

      - name: Check translations
        run: locale-sync check src/assets/i18n --source en.json --format json

      - name: Sync translations (dry run)
        if: failure()
        run: locale-sync sync src/assets/i18n --source en.json --dry-run

Key CI Design Points

Trigger only on locale file changes — Use paths filter to avoid running on every push.
setup-python adds ~5 seconds — Negligible overhead in CI.
Pin LocaleSync version — Use @v1.1.0 or @commitsha for reproducibility.
Exit code 1 = missing keys — The check command naturally fails the CI step when translations are incomplete.
JSON output for automation — Use --format json when you need to parse results programmatically.

GitLab CI

check-translations:
  image: python:3.12-slim
  stage: test
  script:
    - pip install git+https://github.com/polprog-tech/LocaleSync.git
    - locale-sync check src/assets/i18n --source en.json
  only:
    changes:
      - src/assets/i18n/**

Azure Pipelines

- task: UsePythonVersion@0
  inputs:
    versionSpec: '3.12'

- script: |
    pip install git+https://github.com/polprog-tech/LocaleSync.git
    locale-sync check src/assets/i18n --source en.json
  displayName: 'Check translations'

React Integration

React projects using react-i18next typically store locale files in public/locales/:

my-react-app/
├── public/
│   └── locales/
│       ├── en.json
│       ├── pl.json
│       ├── de.json
│       └── fr.json
├── src/
│   ├── i18n.ts
│   └── ...
└── package.json

package.json scripts

{
  "scripts": {
    "locales:check": "locale-sync check public/locales",
    "locales:sync": "locale-sync sync public/locales",
    "locales:translate": "locale-sync translate public/locales",
    "locales:scan": "locale-sync scan public/locales"
  }
}

CI for React projects

name: Locale Sync Check
on:
  pull_request:
    paths:
      - 'public/locales/**'
jobs:
  locale-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: pip install git+https://github.com/polprog-tech/LocaleSync.git
      - run: locale-sync check public/locales --format json

See examples/react-project/ for a complete working example and React Guide for full CI, team setup, and advanced configuration.

Standalone vs Embedded Architecture

Model A: Standalone Repository (Recommended)

LocaleSync lives in its own Git repository and is consumed as an external tool.

polprog-tech/LocaleSync           ← LocaleSync source code
polprog-tech/angular-frontend     ← Angular project, installs LocaleSync via pip/pipx
polprog-tech/react-dashboard      ← React project, same approach

Pros:

Single source of truth for the tool
Independent versioning and releases
Reusable across all projects
Clear ownership and maintenance
Standard Python packaging and distribution

Cons:

Requires Python on all consuming machines/CI
External dependency to manage

Model B: Embedded in Another Repository

LocaleSync is placed under tools/ or scripts/ inside another project.

polprog-tech/angular-frontend/
├── src/
├── tools/
│   └── localesync/         ← LocaleSync copied/embedded here
│       ├── pyproject.toml
│       └── src/
└── package.json

Usage:

# From the Angular project root
pip install -e tools/localesync
locale-sync check src/assets/i18n

Pros:

No external dependency to manage
Self-contained project

Cons:

Duplicated across projects
Hard to keep in sync across repos
Mixes Python tooling into non-Python repos
No independent versioning

Recommendation

Use Model A (Standalone Repository) as the default.

LocaleSync should be its own package, installed via pip or pipx, and consumed as a CLI tool. This is the standard approach for developer tools (similar to how eslint, prettier, black, ruff are distributed independently from the projects that use them).

Use Model B only if your organization has strict restrictions on external dependencies or network access in CI.

Frontend Team Onboarding

For teams where Python is not part of the stack

Install Python 3.12+ (one-time, system-level):

# macOS
brew install python@3.12

# Ubuntu/Debian
sudo apt install python3.12

# Or download from python.org

Install pipx (one-time, for isolated CLI tools):

brew install pipx   # macOS
# or
python3 -m pip install --user pipx
pipx ensurepath

Install LocaleSync (one-time):

pipx install git+https://github.com/polprog-tech/LocaleSync.git

Verify:
```
locale-sync --version
```

Use from your project:

cd your-angular-project
locale-sync check src/assets/i18n

That's it. No virtual environment needed. No Python project files needed. locale-sync works like any other system command.

Updating LocaleSync

pipx upgrade locale-sync
# or reinstall from a specific version
pipx install --force git+https://github.com/polprog-tech/LocaleSync.git@v0.2.0

Troubleshooting

"locale-sync: command not found"

LocaleSync is not installed, or the installation directory is not in your PATH.

# Check if installed
pip show locale-sync
# or
pipx list | grep locale-sync

# If installed via pipx, ensure pipx bin dir is in PATH
pipx ensurepath
# Then restart your terminal

"pip: command not found" / "pipx: command not found"

Python or pipx is not installed.

# Install Python
brew install python@3.12   # macOS
sudo apt install python3.12 python3-pip  # Ubuntu

# Install pipx
brew install pipx           # macOS
python3 -m pip install --user pipx  # Any OS

npm scripts fail with "locale-sync: not found"

The locale-sync CLI must be installed before running npm scripts. npm does not install it automatically.

# Install first
pipx install git+https://github.com/polprog-tech/LocaleSync.git

# Then npm scripts work
npm run locales:check

CI pipeline fails to find locale-sync

Add Python setup and LocaleSync installation steps to your CI configuration. See CI/CD for Non-Python Repositories above.

`pip install -e .` fails with "does not appear to be a Python project"

ERROR: /path/to/your-project does not appear to be a Python project:
neither 'setup.py' nor 'pyproject.toml' found.

This is expected when running pip install -e . from a non-Python project (e.g., Angular, React, Node.js). It means pip is trying to install the current directory as a Python package — but your project isn't one.

Do not run pip install -e . from your frontend project. Instead, install LocaleSync from its own repository:

# Correct: install LocaleSync from GitHub
pip install git+https://github.com/polprog-tech/LocaleSync.git

# Or with pipx (recommended for non-Python projects)
pipx install git+https://github.com/polprog-tech/LocaleSync.git

The -e . (editable install) is only for developing LocaleSync itself from its own cloned repository.

FilesExpand file tree

integration.md

Latest commit

History