🔄 Automatic Translation Sync

The i18n library automatically syncs JSON translation files to embedded TypeScript before every build.

How It Works

Developer edits JSON files
         ↓
    Runs ANY serve/build command
         ↓
    NX detects app depends on i18n library
         ↓
    NX builds i18n library first
         ↓
    i18n build depends on: sync-translations
         ↓
    Automatically runs: sync-embedded-translations.js
         ↓
    Flattens JSON → embedded-translations.ts
         ↓
    Proceeds with library build
         ↓
    App builds/serves with updated translations ✅

Configuration

File: libs/libs-foundational/i18n/project.json

{
  "targets": {
    "sync-translations": {
      "executor": "nx:run-commands",
      "options": {
        "command": "node tools/scripts/translation/sync-embedded-translations.js"
      },
      "cache": false
    },
    "build": {
      "executor": "nx:run-commands",
      "dependsOn": ["sync-translations", "^build"],  // ← Runs sync first!
      "options": {
        "command": "node tools/scripts/build/build-angular-library.js libs-foundational/i18n"
      }
    }
  }
}

Works With ALL Commands

✅ All Development Commands

# GoGrab Space
yarn dev:gograb                           # ✅ Auto-syncs
yarn serve:gograb-space                    # ✅ Auto-syncs
yarn serve:gograb-space --port 5701        # ✅ Auto-syncs (custom port)
nx serve gograb-space                     # ✅ Auto-syncs
nx serve-only gograb-space                # ✅ Auto-syncs

# Space Admin
yarn dev:space-admin                      # ✅ Auto-syncs (if uses i18n)
nx serve space-admin                      # ✅ Auto-syncs (if uses i18n)

# Atlas Admin
yarn dev:atlas-admin                      # ✅ Auto-syncs (if uses i18n)
nx serve atlas-admin                      # ✅ Auto-syncs (if uses i18n)

# Full Stack
yarn dev:full-stack                       # ✅ Auto-syncs
yarn serve:backend                          # ⚠️ No i18n (backend only)

# Entire Ecosystem
yarn dev:ecosystem                        # ✅ Auto-syncs for all frontend apps

✅ All Build Commands

# GoGrab Space
yarn build:gograb                         # ✅ Auto-syncs
yarn build:gograb:fast                    # ✅ Auto-syncs
yarn build:gograb:optimized               # ✅ Auto-syncs
nx build gograb-space                     # ✅ Auto-syncs

# Space Admin
yarn build:space-admin                    # ✅ Auto-syncs (if uses i18n)
nx build space-admin                      # ✅ Auto-syncs (if uses i18n)

# Ecosystem
yarn build:ecosystem                      # ✅ Auto-syncs for all apps
yarn build:all                            # ✅ Auto-syncs for everything

# Library Only
nx build i18n                             # ✅ Auto-syncs
yarn build:libs:auto                      # ✅ Auto-syncs (includes i18n)

✅ CI/CD Commands

# Production builds (CI)
NODE_ENV=production nx build gograb-space # ✅ Auto-syncs
nx run-many -t build --all                # ✅ Auto-syncs

Why It Works Everywhere

NX Dependency Resolution

NX automatically detects that:

1. gograb-space imports from @libs-foundational/i18n
2. Before serving gograb-space, build i18n first
3. Before building i18n, run sync-translations first

yarn serve:gograb-space --port 5701
    ↓
nx serve-only gograb-space --port 5701
    ↓
Detect dependency: @libs-foundational/i18n
    ↓
nx build i18n
    ↓
Detect dependsOn: sync-translations
    ↓
nx sync-translations i18n
    ↓ (runs sync script)
Translations synced ✅
    ↓
i18n library built
    ↓
gograb-space serves with latest translations

Works With Any Flags

The sync happens before NX processes flags, so these all work:

nx serve gograb-space --port 5701        # ✅ Custom port
nx serve gograb-space --open             # ✅ Auto-open browser
nx serve gograb-space --host 0.0.0.0     # ✅ Network access
nx serve gograb-space --ssl              # ✅ HTTPS
nx serve gograb-space --verbose          # ✅ Verbose output
nx build gograb-space --skip-nx-cache    # ✅ Skip cache
nx build gograb-space --configuration=production # ✅ Prod mode

Developer Workflow

Normal Development (Automatic)

# 1. Edit translations
# Edit: libs/libs-foundational/i18n/src/assets/i18n/en.json

# 2. Start dev server with ANY command
yarn serve:gograb-space --port 5701
# ✅ Automatically syncs translations before build

# OR
yarn dev:gograb
# ✅ Automatically syncs translations before build

# OR
yarn dev:ecosystem
# ✅ Automatically syncs translations for ALL apps

No manual sync needed! The dependsOn: ["sync-translations"] ensures sync runs before every build.

Manual Sync (Optional)

# Only if you want to sync without building
yarn translate:sync

# OR
nx sync-translations i18n

Benefits

✅ Zero Manual Steps

• Edit JSON → run any serve/build → translations updated
• No need to remember to run sync script
• Reduces developer cognitive load

✅ Always In Sync

• Build depends on sync, so translations are always current
• No stale embedded translations
• Impossible to forget to sync

✅ Works With ALL Commands

• Development: serve, serve-only, dev:*
• Production: build, build:*
• Custom flags: --port, --open, --ssl, etc.
• CI/CD: Any automated build command

✅ CI/CD Friendly

• Build process is self-contained
• No manual pre-build steps in CI
• Works in any environment

✅ Performance Optimized

• Sync runs only when building i18n library
• NX caches sync results (when possible)
• Parallel execution with other tasks

Verification

Check Dependency Chain

# See what i18n depends on
nx show project i18n --json | grep -A 5 dependsOn

# Expected output:
# "dependsOn": ["sync-translations", "^build"]

Verify Sync Runs

# Build with verbose output
nx build i18n --verbose 2>&1 | grep sync-translations

# Expected output:
# Running target sync-translations for project i18n
# Successfully ran target sync-translations

Test With Your Command

# Edit a translation
echo '{"test": {"key": "New Value"}}' > libs/libs-foundational/i18n/src/assets/i18n/en.json

# Run your command
yarn serve:gograb-space --port 5701

# Check if embedded translations updated
cat libs/libs-foundational/i18n/src/lib/translations/embedded-translations.ts | grep "New Value"
# Should show: "test.key": "New Value"

Troubleshooting

Translations not updating in app

Problem: Changed JSON files but app shows old translations

Solution:

# 1. Clear NX cache
nx reset

# 2. Force rebuild
nx build i18n --skip-nx-cache

# 3. Restart dev server
yarn serve:gograb-space --port 5701

Sync not running

Problem: Build doesn't seem to run sync

Verify configuration:

# Check if sync-translations target exists
nx show project i18n --web

# Look for: "sync-translations" in targets
# And: "dependsOn": ["sync-translations"] in build target

Port conflicts

Problem: Default port is in use

Solution:

# Use custom port (sync still works!)
yarn serve:gograb-space --port 5701
nx serve gograb-space --port 6000

Manual sync needed

When: You want to see sync results without building

# Run sync manually
yarn translate:sync

# Check output
cat libs/libs-foundational/i18n/src/lib/translations/embedded-translations.ts

Architecture Details

Why Automatic Sync?

Before (Manual):

1. Edit en.json
2. Remember to run yarn translate:sync
3. Build library
4. Hope you didn't forget step 2

After (Automatic):

1. Edit en.json
2. Run ANY serve/build command
3. Sync happens automatically

NX Dependency Graph

ANY serve/build command
    ↓ detects import
gograb-space (app)
    ↓ depends on
i18n (library)
    ↓ depends on
sync-translations (task)
    ↓ executes
sync-embedded-translations.js (script)
    ↓ reads
JSON files (assets/i18n/*.json)
    ↓ generates
embedded-translations.ts

NX automatically resolves this chain and runs tasks in correct order.

Cache Strategy

• sync-translations: cache: false - Always runs (files might have changed)
• i18n build: cache: true - Caches build output for performance
• app serve: Uses cached i18n if inputs haven't changed

This ensures sync always runs but build can be cached for speed.

Examples

Example 1: Custom Port Development

# Edit translation
vim libs/libs-foundational/i18n/src/assets/i18n/en.json

# Serve with custom port
yarn serve:gograb-space --port 5701
# ✅ Syncs automatically before serve
# ✅ App runs on http://localhost:5701
# ✅ Translations are up-to-date

Example 2: Full Stack Development

# Edit translations
vim libs/libs-foundational/i18n/src/assets/i18n/es.json

# Start full stack
yarn dev:full-stack
# ✅ Backend starts (no i18n needed)
# ✅ Frontend starts after 3s
# ✅ Syncs translations before frontend build
# ✅ Both services running with latest translations

Example 3: Production Build

# Edit translations
vim libs/libs-foundational/i18n/src/assets/i18n/en.json
vim libs/libs-foundational/i18n/src/assets/i18n/es.json

# Build for production
yarn build:gograb
# ✅ Syncs translations automatically
# ✅ Builds with optimizations
# ✅ Production bundle includes latest translations

Example 4: CI/CD Pipeline

# .github/workflows/build.yml
- name: Install dependencies
  run: yarn install

- name: Build application
  run: yarn build:gograb
  # ✅ No need to run yarn translate:sync manually
  # ✅ Happens automatically during build

Advanced Usage

Skip Sync (Not Recommended)

If you absolutely need to skip sync (e.g., debugging):

# Build library directly without dependencies
nx build i18n --skip-nx-cache --skipNxCache

# Serve app without rebuilding libraries
nx serve gograb-space --skip-nx-cache

⚠️ Warning: This may cause stale translations!

Multiple Languages

Add new languages to JSON directory:

# 1. Create file
cp libs/libs-foundational/i18n/src/assets/i18n/en.json \
   libs/libs-foundational/i18n/src/assets/i18n/fr.json

# 2. Translate content in fr.json

# 3. Run any serve/build (auto-syncs all JSON files)
yarn serve:gograb-space --port 5701

Sync script automatically detects and processes all *.json files in the directory.

Watch Mode (Future Enhancement)

Currently, sync only runs on build. To get live sync during development:

# Terminal 1: Watch for JSON changes
npx nodemon --watch "libs/libs-foundational/i18n/src/assets/i18n/*.json" \
  --exec "yarn translate:sync"

# Terminal 2: Serve app
yarn serve:gograb-space --port 5701

This gives you instant translation updates without rebuilding.

Related Documentation

• i18n Library README
• Translation Plan
• gograb-ai Integration
• AI Agent Workflow

Summary

✅ Edit JSON files → Run ANY command → Done

# ALL of these auto-sync translations:
yarn dev:gograb
yarn serve:gograb-space
yarn serve:gograb-space --port 5701  # ← Your command
yarn dev:full-stack
yarn dev:ecosystem
yarn build:gograb
yarn build:all
nx serve gograb-space
nx build gograb-space
# ... and any other serve/build command!

No manual sync needed! The build system handles everything automatically, regardless of which command you use or which flags you pass.