DEV Community

HarmanPreet-Singh-XYT
HarmanPreet-Singh-XYT

Posted on AI-assisted

Agentic Localization, Low to no cost for tokens.

#ai #llm #agents #architecture

Hackathon Submission Disclosure:

I created this piece of content for the purposes of entering the Google Cloud Agentic Hackathon. It details the architecture, real-world benchmarks, and cloud infrastructure behind **langPeanut.

If you have ever tried using an LLM to localize an existing app, you probably noticed the same frustrating pattern: you feed a prompt 500 lines of React, Flutter, or Swift code, ask it to extract strings and replace them with localization hooks, and get back code that looks convincing at first glance—until you run the compiler.

Quotes get escaped incorrectly, JSX children trees get mangled, ICU plural syntax breaks, and comments silently vanish.

When we set out to build langPeanut, our goal wasn’t to build another "AI code generator." It was to solve localization as an AST boundary problem, not a text generation problem.

Here is how we built a multi-agent localization and SEO platform in Go, powered by Gemini 3.7 Flash, and deployed reliably to Google Cloud Compute Engine (GCE) with Google Cloud Pub/Sub.

1. The "Zero-Generation" Principle

The fundamental flaw with single-prompt LLM refactoring is giving the model write-access to the entire file structure.

In langPeanut, the LLM is never allowed to rewrite a full source file. Instead, we split the workflow into strict deterministic boundaries and narrow AI judgment:

[ Deterministic Tree-Sitter AST ] ──► Extracts string literals & byte-offsets
               │
               ▼
[ Gemini 3.7 Flash Judgment ]    ──► Disambiguates context & translates (ICU-safe)
               │
               ▼
[ Deterministic Patch Engine ]   ──► Slices & splices exact byte ranges
               │
               ▼
[ 4-Tier Critic & Compiler ]     ──► Syntax, key-parity, & AST validation
Enter fullscreen mode Exit fullscreen mode
  1. AST Scout (Deterministic): Uses tree-sitter grammars (Go, TypeScript, TSX, Dart, Swift, Kotlin) to pinpoint exact byte-ranges of user-facing strings at 0 token cost.
  2. Context & Cultural Translation (Gemini 3.7 Flash): We call Gemini via the official Go GenAI SDK (google.golang.org/genai) only for linguistic judgment:
    • Disambiguation: Is "Close" a button verb or an adjective?
    • ICU Preservation: Ensuring complex plural tags ({count, plural, one {# item} other {# items}}) remain syntactically identical across locales.
  3. AST Patch Engine (Deterministic): Slices the original file by exact byte offsets and injects the localized hook (t('key') or AppLocalizations.of(context)). Whitespace, comments, and un-targeted code remain 100% untouched.

On our 10-case adversarial benchmark (nested JSX expressions, Dart string interpolation, SwiftUI view modifiers), this approach achieved a 100% AST compilation pass rate with 0% formatting drift.

2. The Three-System Architecture

Rather than a single monolithic script, langPeanut coordinates three specialized systems that share a single on-disk project state:

  • System A — Localization Engine: The core 6-agent pipeline with a self-correcting 4-tier verifier and a bounded ReAct repair loop for edge-case compiler errors.
  • System B — Central AI Copilot (langPeanut chat): A conversational control plane equipped with 19 registered tools. If network access drops, it automatically falls back to a deterministic keyword router.
  • System C — SEO & Growth Studio (langPeanut seo): A 5-agent pipeline (SERP Scout → Keyword Intelligence → Copy Weaver → SERP Simulator → Growth Critic) that optimizes translated copy for local search engine visibility directly against the same locale files.

3. Production Deployment: Google Cloud Compute Engine & Pub/Sub

Locally, langPeanut runs as a zero-dependency CLI, TUI (Bubble Tea), or a zero-build Web Studio. But for team workflows, we built langPeanut Cloud—a hosted GitHub App that monitors repositories, extracts strings on push, and automatically opens clean Pull Requests.

Running an automated agentic bot against arbitrary user repositories introduces two major infrastructure challenges: webhook reliability and execution sandboxing.

Challenge 1: The "Dropped Webhook" Problem (Solved by Cloud Pub/Sub)

GitHub delivers push webhooks with a very short timeout and minimal retry persistence. If a cloud server restarts during a deployment, hits a database lock, or receives a sudden burst of commits across multiple repositories, incoming webhooks can get dropped silently.

To guarantee zero dropped events, we placed Google Cloud Pub/Sub between our webhook ingestion gateway and our worker queue:

[ GitHub Push Webhook ]
        │ (verified HMAC signature)
        ▼
[ Ingestion API Handler ]
        │
        ▼
[ Google Cloud Pub/Sub Topic ]
        │
        ▼
[ Subscription Pull Worker ] ──► Acks only after job is safely persisted in SQLite
        │
        ▼
[ Ephemeral Sandboxed Docker Runner ] ──► AST patch → Gemini translation → Opens PR
Enter fullscreen mode Exit fullscreen mode
  • When a webhook arrives, the ingestion handler validates the HMAC signature and immediately publishes the raw event to a Google Cloud Pub/Sub topic (langpeanut-webhooks).
  • Our Go worker pulls messages from the subscription. If a job fails unexpectedly, the message is nacked and redelivered according to our GCP backoff policy.
  • The event is only acknowledged once the job state is safely committed.

Challenge 2: Sandboxed Execution on Google Compute Engine (GCE)

We host the stack on an e2-medium Google Cloud Compute Engine instance running Ubuntu 24.04 LTS.

To keep the host clean and secure:

  • The core server runs as a lightweight Go binary managing an embedded SQLite database in WAL mode.
  • Each localization job dynamically spawns an ephemeral Docker runner container with restricted CPU/memory limits and limited network privileges.
  • Once the AST patching, translation, verification, and branch push complete, the container is destroyed immediately.

4. Live Verification & Hands-On Demo

For judges and developers wanting to test this live without cloning or configuring infrastructure:

- Verified Test Repository: HarmanPreet-Singh-XYT/pingroute-web (a production Next.js 15 app you can fork or import to test full AST extraction and PR generation in under 30 seconds)

5. Key Takeaways from Building Agentic Workflows

  1. Don't use LLMs where deterministic tools already excel. Tree-sitter parsers are fast, free, and 100% accurate at syntax analysis. Save LLM tokens for nuance, tone, and cultural translation.
  2. Constrain the mutation surface. If an agent only has the power to return a localized string replacement rather than rewrite a file, 90% of hallucinations and syntax breakages disappear.
  3. Queue everything at the edge. Combining Google Cloud Pub/Sub with Compute Engine gave our agentic worker resilience against network hiccups and deployment restarts without complex multi-node cluster overhead.

Top comments (1)

Collapse
 
marcusykim profile image
Marcus Kim •

The byte-offset patching boundary is the strongest design choice here: Tree-sitter finds the exact user-facing strings, while Gemini handles disambiguation and ICU-safe translation without getting permission to rewrite the surrounding TSX, Dart, or Swift. Acknowledging Pub/Sub messages only after the job reaches SQLite, then running each patch in an ephemeral constrained Docker container, gives the hosted path a sensible failure boundary. The production detail I'd add is an idempotency key built from the GitHub delivery ID and commit SHA, because redelivery is expected and "no dropped events" matters only if the same push cannot open.