AI Agent Translation - Quick Start

5-minute guide for AI agents to automate translation workflows

⚡ AI Agent Translation - Quick Start

🎯 For AI Agents (Claude, GPT-4, etc.)

You are an AI agent tasked with automating translations for the GoGrab Space monorepo.

📋 Quick Reference

Your Mission:

Find hardcoded English strings → Extract → Translate to Spanish → Update code → Test

Key Files:

🚀 5-Minute Workflow

Step 1: Add Transloco Key to HTML (10 seconds)

<p>{{ 'dashboard.myNewFeature' | transloco }}</p>

Step 2: Run Automation (30 seconds)

yarn translate:fix

What it does automatically:

🤖 FULLY AUTOMATED TRANSLATION SYSTEM
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔍 Step 1: Scanning for undefined keys...
✅ Found 1 undefined keys

📝 Step 2: Adding to en.json...
✅ English keys added

🤖 Step 3: Calling backend-api AI to translate...
✅ Spanish translations added

🔄 Step 4: Syncing to production format...
✅ Synced to embedded format

🎉 TRANSLATION COMPLETE!

What to look for:

Ignore:

Step 3: Test (30 seconds)

# Serve and test (translations auto-sync!)
nx serve gograb-space

In browser:

Optional: Deep Diagnostics

Want to find ALL hardcoded strings in the monorepo?

yarn translate:scan    # Finds 1,815+ hardcoded strings

Want to validate JSON files manually?

yarn translate:test    # Validates en.json and es.json

In browser:

🎯 Translation Key Format

Namespace Structure:

<namespace>.<feature>.<element>

Examples:

String Key Namespace
"Welcome" dashboard.welcome.title dashboard
"Create Universe" universe.create.button universe
"Save Changes" common.save.button common
"Login failed" errors.auth.loginFailed errors
"Email required" validation.email.required validation

Namespaces:

📝 Translation Templates

Template 1: Button

<!-- Before -->
<button class="primary">Create Universe</button>

<!-- After -->
<button class="primary">{{ 'universe.create.button' | transloco }}</button>

// en.json
{ "universe": { "create": { "button": "Create Universe" } } }

// es.json
{ "universe": { "create": { "button": "Crear Universo" } } }

Template 2: Heading

<!-- Before -->
<h1>My Universes</h1>

<!-- After -->
<h1>{{ 'universe.list.title' | transloco }}</h1>

// en.json
{ "universe": { "list": { "title": "My Universes" } } }

// es.json
{ "universe": { "list": { "title": "Mis Universos" } } }

Template 3: Paragraph with Placeholder

<!-- Before -->
<p>You have {{ count }} universes</p>

<!-- After -->
<p>{{ 'dashboard.stats.universeCount' | transloco: { count: count() } }}</p>

// en.json
{ "dashboard": { "stats": { "universeCount": "You have {{ count }} universes" } } }

// es.json
{ "dashboard": { "stats": { "universeCount": "Tienes {{ count }} universos" } } }

Template 4: Error Message (TypeScript)

// Before
throw new Error('Failed to load data');

// After
throw new Error(this.translationService.translate('errors.data.loadFailed'));

// en.json
{ "errors": { "data": { "loadFailed": "Failed to load data" } } }

// es.json
{ "errors": { "data": { "loadFailed": "Error al cargar datos" } } }

🌐 Standard Translations (Use These!)

English Spanish
Create Crear
Save Guardar
Cancel Cancelar
Delete Eliminar
Edit Editar
View Ver
Update Actualizar
Loading Cargando
Error Error
Success Éxito
Universe Universo
Dashboard Panel de Control
Settings Configuración
Login Iniciar Sesión
Logout Cerrar Sesión

More in: tools/scripts/translation/ai-agent-prompt.md

✅ Checklist

Before marking task complete:

🎯 Real Example

Found String:

File: apps/gograb-space/src/app/components/universe-list/universe-list.component.html
Line: 42
Code: <div class="empty-state">
        <h2>Ready to Build Your Universe?</h2>
        <p>Create your first universe to get started</p>
        <button class="primary">Create Universe</button>
      </div>

Process:

1. Generate keys:

2. Add to libs/libs-foundational/i18n/src/assets/i18n/en.json:

{
  "universe": {
    "emptyState": {
      "title": "Ready to Build Your Universe?",
      "subtitle": "Create your first universe to get started",
      "createButton": "Create Universe"
    }
  }
}

3. Translate to es.json:

{
  "universe": {
    "emptyState": {
      "title": "¿Listo para Construir tu Universo?",
      "subtitle": "Crea tu primer universo para comenzar",
      "createButton": "Crear Universo"
    }
  }
}

4. Update HTML:

<div class="empty-state">
  <h2>{{ 'universe.emptyState.title' | transloco }}</h2>
  <p>{{ 'universe.emptyState.subtitle' | transloco }}</p>
  <button class="primary">{{ 'universe.emptyState.createButton' | transloco }}</button>
</div>

5. Validate & Sync:

yarn translate:ai validate  # ✅ Passed
yarn translate:ai sync      # ✅ Synced

6. Test:

🚨 Common Mistakes

❌ Bad Key Names:

{ "text1": "Welcome" }        // Too generic
{ "welcomeText": "Welcome" }  // No namespace

✅ Good Key Names:

{ "dashboard": { "welcome": { "title": "Welcome" } } }

❌ Missing Placeholders:

// EN: "You have {{ count }} items"
// ES: "Tienes elementos"  // ❌ Lost {{ count }}

✅ Correct:

// EN: "You have {{ count }} items"
// ES: "Tienes {{ count }} elementos"  // ✅ Preserved {{ count }}

❌ Wrong Update:

<!-- Before -->
<h1>Welcome</h1>

<!-- After (WRONG) -->
<h1 transloco="dashboard.welcome">Welcome</h1>  <!-- Old directive syntax -->

✅ Correct Update:

<h1>{{ 'dashboard.welcome.title' | transloco }}</h1>  <!-- Pipe syntax -->

🎓 Advanced: TypeScript Usage

In Components:

import { Component, inject } from '@angular/core';
import { TranslationService } from '@libs-foundational/i18n';

@Component({...})
export class MyComponent {
  private translation = inject(TranslationService);

  // Get translation
  title = this.translation.translate('dashboard.welcome');

  // With parameters
  message = this.translation.translate('errors.generic', { 
    action: 'save' 
  });

  // Reactive (Observable)
  title$ = this.translation.translate$('dashboard.title');

  // Change language
  switchLanguage() {
    this.translation.setLanguage('es');
  }
}

Import TranslocoModule:

import { TranslocoModule } from '@ngneat/transloco';

@Component({
  standalone: true,
  imports: [
    CommonModule,
    TranslocoModule  // ← Required for transloco pipe
  ]
})

📚 Resources

Documentation:

Translation Files:

Scripts:

🎯 Summary

Your workflow is now 100% AUTOMATED:

  1. Add transloco key to your HTML:
    <p>{{ 'my.new.key' | transloco }}</p>

  2. Run ONE command:
    yarn translate:fix

  3. Done! System automatically:

    • Detects undefined keys
    • Adds to en.json
    • Calls backend-api AI to translate
    • Updates es.json
    • Syncs to production format

  4. Test: nx serve gograb-space (verify in browser)

Time: < 1 second ⚡
Manual steps: ZERO 🎉
Cost: $0 💰
Result: Seamless language switching for users 🌐

Last Updated: November 20, 2025
Status: Ready for AI Agents
Next: Run yarn translate:ai to begin!