Angular Integration Guide

This guide shows how to integrate LocaleSync into an Angular project for automated locale file management.

Typical Angular i18n Structure
Setup
package.json Scripts
Common Workflows
CI/CD for Angular Projects
Team Setup Guide
Advanced Configuration

Typical Angular i18n Structure

Angular applications using translation libraries like @ngx-translate/core or @angular/localize typically store locale files under src/assets/i18n/:

my-angular-app/
├── src/
│   ├── app/
│   ├── assets/
│   │   └── i18n/
│   │       ├── en.json       ← Source language (English)
│   │       ├── pl.json       ← Polish translations
│   │       ├── de.json       ← German translations
│   │       └── fr.json       ← French translations
│   └── environments/
├── angular.json
├── package.json
└── tsconfig.json

LocaleSync works directly with this structure. No configuration changes needed.

Auto-discovery: You can also just run locale-sync scan . from the project root — LocaleSync will find src/assets/i18n/ automatically.

Setup

Prerequisites

Python 3.12+ and pipx installed on developer machines
See Integration Guide for installation instructions

Install LocaleSync

# Recommended: isolated system-wide install
pipx install git+https://github.com/polprog-tech/LocaleSync.git

# Verify
locale-sync --version

Verify It Works With Your Project

cd your-angular-project

# Auto-discover locale files from project root
locale-sync scan .

# Or point directly
locale-sync scan src/assets/i18n

# Check for missing keys
locale-sync check src/assets/i18n --source en.json

package.json Scripts

Add these scripts to your Angular project's package.json:

{
  "scripts": {
    "start": "ng serve",
    "build": "ng build",
    "test": "ng test",

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

Note: These scripts call locale-sync as an external system command. LocaleSync is not an npm package and should not be added to devDependencies.

Usage

# Day-to-day development
npm run locales:check              # Are translations complete?
npm run locales:sync:preview       # What would sync change?
npm run locales:sync               # Fill missing keys

# Before a release
npm run locales:check              # Ensure everything is in order

# After adding new source keys
npm run locales:sync               # Propagate to all targets

Common Workflows

Workflow 1: Developer Adds New UI Text

Developer adds new keys to en.json:

{
  "dashboard": {
    "welcome": "Welcome back, {name}!",
    "new_feature_banner": "Try our new analytics dashboard"
  }
}

Run sync to propagate to all targets:

npm run locales:sync:preview   # Review first
npm run locales:sync           # Apply

Target files now have the new key (with English fallback):

// pl.json — new key added with source text
{
  "dashboard": {
    "welcome": "Witaj ponownie, {name}!",
    "new_feature_banner": "Try our new analytics dashboard"
  }
}

Translators can now find and translate the English fallback values.

Workflow 2: Pre-commit / Pre-push Check

# Quick check before pushing
npm run locales:check

# Exit code 0 = all good
# Exit code 1 = missing translations found

Workflow 3: Translate Missing Keys (Demo)

# Preview what would be translated
npm run locales:translate:preview

# Apply translation (uses Google Translate by default)
npm run locales:translate

Note: The translate command uses Google Translate by default (free, no API key, 100+ languages). Use --provider demo for offline/testing scenarios. See Extensibility for adding custom providers.

Workflow 4: Selective Target Sync

# Sync only specific locales
locale-sync sync src/assets/i18n --source en.json --target pl.json --target de.json

CI/CD for Angular Projects

GitHub Actions

Create .github/workflows/translations.yml in your Angular project:

name: Translation Check

on:
  push:
    branches: [main, develop]
    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 are complete
        run: locale-sync check src/assets/i18n --source en.json

      - name: Report missing translations (on failure)
        if: failure()
        run: locale-sync check src/assets/i18n --source en.json --format json

Combined Angular + Translation CI

name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  # Standard Angular CI
  build-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm run build
      - run: npm test -- --watch=false --browsers=ChromeHeadless

  # Translation check (runs in parallel)
  check-translations:
    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 src/assets/i18n --source en.json

Key Points for CI

Python setup adds ~5 seconds — negligible overhead.
Path filtering avoids unnecessary runs. Only trigger on src/assets/i18n/** changes.
Parallel jobs — Translation check runs alongside Angular build/test, not blocking it.
Exit code 1 naturally fails the CI step when translations are incomplete.
Pin the version with @v1.1.0 or @commitsha for reproducible builds.

Team Setup Guide

First-time Setup for the Team

Document the prerequisite in your Angular project's README:

## Prerequisites

- Node.js 20+
- Angular CLI
- LocaleSync (for translation management):
  ```bash
  pipx install git+https://github.com/polprog-tech/LocaleSync.git

Add package.json scripts (see above).
Add CI workflow (see above).
Add to your project's .gitignore (if not already present):
```
# LocaleSync backups
src/assets/i18n/*.bak
```

Team Conventions

Recommended conventions for teams:

en.json is always the source of truth. All new keys go there first.
Run npm run locales:check before creating a PR that touches locale files.
CI enforces completeness. PRs with missing translations fail the check.
Use sync, then hand-translate. Run locales:sync to fill gaps with English text, then have translators replace the English values.
Never manually delete keys from target files. Let LocaleSync manage structure.

Advanced Configuration

Custom Locale Directory

If your locale files are not in src/assets/i18n/, adjust the path:

{
  "scripts": {
    "locales:check": "locale-sync check src/locales"
  }
}

Multiple Locale Directories (Monorepo / Libraries)

{
  "scripts": {
    "locales:check:app": "locale-sync check src/assets/i18n --source en.json",
    "locales:check:lib": "locale-sync check projects/shared-lib/assets/i18n --source en.json",
    "locales:check": "npm run locales:check:app && npm run locales:check:lib"
  }
}

Custom Source Language

If your source language is not English:

{
  "scripts": {
    "locales:check": "locale-sync check src/assets/i18n --source de.json"
  }
}

Specific Targets Only

{
  "scripts": {
    "locales:sync:pl": "locale-sync sync src/assets/i18n --source en.json --target pl.json"
  }
}

Custom Indentation

Match your project's JSON formatting:

{
  "scripts": {
    "locales:sync": "locale-sync sync src/assets/i18n --indent 4"
  }
}

FAQ

Does LocaleSync need to be added to package.json dependencies?

No. LocaleSync is a system-level CLI tool, not an npm package. Install it via pipx or pip separately.

Does LocaleSync modify angular.json or any Angular config?

No. It only reads and writes locale JSON files. It has no awareness of Angular configuration.

Can LocaleSync handle Angular's ICU message format?

LocaleSync preserves all string values as-is, including ICU message syntax like {count, plural, one {# item} other {# items}}. It treats them as opaque strings when syncing.

For the translate command, placeholders like {name} are protected during translation. Full ICU expression handling would require a custom translation provider.

What about @angular/localize (XLIFF)?

LocaleSync currently supports JSON locale files. XLIFF/XMB support could be added as a new parser/writer — see Extensibility. The architecture is designed to support this.

Can I use this with @ngx-translate/core?

Yes. @ngx-translate/core uses exactly the JSON structure LocaleSync is designed for. This is the ideal integration.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Angular Integration Guide

Table of Contents

Typical Angular i18n Structure

Setup

Prerequisites

Install LocaleSync

Verify It Works With Your Project

package.json Scripts

Usage

Common Workflows

Workflow 1: Developer Adds New UI Text

Workflow 2: Pre-commit / Pre-push Check

Workflow 3: Translate Missing Keys (Demo)

Workflow 4: Selective Target Sync

CI/CD for Angular Projects

GitHub Actions

Combined Angular + Translation CI

Key Points for CI

Team Setup Guide

First-time Setup for the Team

Team Conventions

Advanced Configuration

Custom Locale Directory

Multiple Locale Directories (Monorepo / Libraries)

Custom Source Language

Specific Targets Only

Custom Indentation

FAQ

Does LocaleSync need to be added to package.json dependencies?

Does LocaleSync modify angular.json or any Angular config?

Can LocaleSync handle Angular's ICU message format?

What about @angular/localize (XLIFF)?

Can I use this with @ngx-translate/core?

FilesExpand file tree

angular-guide.md

Latest commit

History

angular-guide.md

File metadata and controls

Angular Integration Guide

Table of Contents

Typical Angular i18n Structure

Setup

Prerequisites

Install LocaleSync

Verify It Works With Your Project

package.json Scripts

Usage

Common Workflows

Workflow 1: Developer Adds New UI Text

Workflow 2: Pre-commit / Pre-push Check

Workflow 3: Translate Missing Keys (Demo)

Workflow 4: Selective Target Sync

CI/CD for Angular Projects

GitHub Actions

Combined Angular + Translation CI

Key Points for CI

Team Setup Guide

First-time Setup for the Team

Team Conventions

Advanced Configuration

Custom Locale Directory

Multiple Locale Directories (Monorepo / Libraries)

Custom Source Language

Specific Targets Only

Custom Indentation

FAQ

Does LocaleSync need to be added to package.json dependencies?

Does LocaleSync modify angular.json or any Angular config?

Can LocaleSync handle Angular's ICU message format?

What about @angular/localize (XLIFF)?

Can I use this with @ngx-translate/core?