Skip to content

react-guide.md

Latest commit

 

History

History
401 lines (297 loc) · 9.59 KB

react-guide.md

File metadata and controls

401 lines (297 loc) · 9.59 KB

React Integration Guide

This guide shows how to integrate LocaleSync into a React project for automated locale file management.

Table of Contents

Typical React i18n Structure

React applications using react-i18next typically store locale files under public/locales/:

my-react-app/
├── public/
│   └── locales/
│       ├── en.json       ← Source language (English)
│       ├── pl.json       ← Polish translations
│       ├── de.json       ← German translations
│       └── fr.json       ← French translations
├── src/
│   ├── i18n.ts           ← i18next configuration
│   ├── App.tsx
│   └── ...
├── 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 public/locales/ 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-react-project

# Auto-discover locale files
locale-sync scan .

# Or point directly
locale-sync scan public/locales

# Check for missing keys
locale-sync check public/locales

package.json Scripts

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

{
  "scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test",

    "locales:scan": "locale-sync scan public/locales",
    "locales:check": "locale-sync check public/locales",
    "locales:check:ci": "locale-sync check public/locales --format json",
    "locales:sync": "locale-sync sync public/locales",
    "locales:sync:preview": "locale-sync sync public/locales --dry-run",
    "locales:sync:backup": "locale-sync sync public/locales --backup",
    "locales:translate": "locale-sync translate public/locales",
    "locales:translate:preview": "locale-sync translate public/locales --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:translate          # Propagate and translate to all targets

Common Workflows

Workflow 1: Developer Adds New UI Text

  1. Developer adds new keys to en.json:

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

  2. Run sync to propagate to all targets:

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

  3. 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": "Try our new analytics dashboard"
  }
}

  4. Translators can now find and translate the English fallback values.

Workflow 2: Auto-Translate Missing Keys

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

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

Each target file gets language-specific translations:

  • pl.json → Polish values
  • de.json → German values
  • fr.json → French values

Workflow 3: Pre-commit Check

npm run locales:check

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

CI/CD for React Projects

GitHub Actions

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

name: Translation Check

on:
  push:
    branches: [main, develop]
    paths:
      - 'public/locales/**'
  pull_request:
    paths:
      - 'public/locales/**'

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 public/locales

      - name: Report missing translations (on failure)
        if: failure()
        run: locale-sync check public/locales --format json

Combined React + Translation CI

name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  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 -- --watchAll=false

  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 public/locales

Key Points for CI

  • Python setup adds ~5 seconds — negligible overhead.
  • Path filtering avoids unnecessary runs. Only trigger on public/locales/** changes.
  • Parallel jobs — Translation check runs alongside React 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

  1. Document the prerequisite in your React project's README:

    ## Prerequisites

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

  2. Add package.json scripts (see above).

  3. Add CI workflow (see above).

  4. Add to your project's .gitignore (if not already present):

    # LocaleSync backups
public/locales/*.bak

Team Conventions

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

Advanced Configuration

Vite Projects (alternative locale path)

Some Vite-based React apps store locales differently:

my-vite-app/
├── src/
│   └── locales/
│       ├── en.json
│       ├── pl.json
│       └── de.json

Adjust the path in your scripts:

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

Or let auto-discovery find it:

{
  "scripts": {
    "locales:check": "locale-sync check ."
  }
}

Next.js Projects

Next.js apps often use public/locales/{lang}/ per-language directories with a single common.json per language. LocaleSync expects all locale files in one directory. If your structure is flat (public/locales/en.json, etc.), it works out of the box.

Custom Indentation

Match your project's JSON formatting:

{
  "scripts": {
    "locales:sync": "locale-sync sync public/locales --indent 4"
  }
}

Specific Targets Only

{
  "scripts": {
    "locales:sync:pl": "locale-sync sync public/locales --target pl.json"
  }
}

i18next Configuration Reference

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;

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.

Can I use this with Next.js i18n?

Yes, if your locale files are flat JSON files in a single directory. The per-language-directory structure (locales/en/common.json) is not supported — LocaleSync expects en.json, pl.json, etc. in one directory.

What about react-intl?

LocaleSync works with any JSON-based i18n library. react-intl, react-i18next, i18next, lingui — as long as locale files are flat JSON, LocaleSync handles them.