react-project

React + LocaleSync Integration Example

This example shows how to use LocaleSync in a React project using react-i18next for internationalization.

Project Structure

my-react-app/
├── public/
│   └── locales/
│       ├── en.json      # Source locale (English)
│       ├── pl.json      # Polish (partial)
│       ├── de.json      # German (partial)
│       └── fr.json      # French (partial)
├── src/
│   ├── i18n.ts          # i18next configuration
│   └── ...
├── package.json
└── .github/
    └── workflows/
        └── locale-check.yml

Prerequisites

Install LocaleSync globally (or per-project via pipx):

# Option 1: pipx (recommended for dev machines)
pipx install git+https://github.com/polprog-tech/LocaleSync.git

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

Usage

Check for missing translations

npm run locales:check
# or directly:
locale-sync check public/locales

Sync missing keys (copies English text as placeholder)

npm run locales:sync
# or directly:
locale-sync sync public/locales

Translate missing keys (with language-specific translations)

npm run locales:translate
# or directly:
locale-sync translate public/locales

Scan locale files

npm run locales:scan
# or with auto-discovery from project root:
locale-sync scan .

package.json Scripts

Add these scripts to your package.json:

{
  "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 Integration

The included .github/workflows/locale-check.yml workflow:

1. Triggers on PRs that modify public/locales/**
2. Installs LocaleSync from GitHub
3. Runs locale-sync check to verify all translations are complete
4. Runs locale-sync translate --dry-run to preview what would be added

i18next Configuration

Typical src/i18n.ts setup for react-i18next:

import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import HttpBackend from 'i18next-http-backend';

i18n
  .use(HttpBackend)
  .use(initReactI18next)
  .init({
    fallbackLng: 'en',
    supportedLngs: ['en', 'pl', 'de', 'fr'],
    backend: {
      loadPath: '/locales/{{lng}}.json',
    },
    interpolation: {
      escapeValue: false,
    },
  });

export default i18n;

Translation Workflow

1. Add new keys to en.json during development
2. Run npm run locales:check to see what's missing
3. Run npm run locales:translate to auto-translate missing keys
4. Review generated translations and adjust as needed
5. Commit the updated locale files

For the full React guide with CI examples and team conventions, see docs/react-guide.md.