Engineering in the Field

I run systems as a Head of Cloud and playful engineer in the trenches. Most people use AI coding assistants to write trivial five-line snippets. In complex cloud and distributed environments, snippets are low-leverage toys.

I treat Google Antigravity AI as an autonomous field engineer with direct sandboxed CLI, shell execution, test suites, and git authority. This page is my personal notebook of battle-tested, high-leverage prompts that automate end-to-end engineering tasks without human babysitting.

Have a prompt that saved you dozens of hours or solved a nasty distributed edge case? Bookmark this page and check back as I push more production directives straight from my daily deployments.

Browser i18n & Translation Header Resolution Architecture

⚠️ Tech Ahead: The sections below dive into RFC 9110 language quality weighting (q=...), SSR <html lang> synchronization, Chrome Translate DOM race conditions, non-destructive expand-and-contract database gates, and self-healing CI/CD prompt specifications.


1. Full-Stack i18n & Browser Translation Audit + Release Pipeline

The Architecture & Root Cause

In production multilingual deployments—such as mondar.ch—browser translation engines (like Google Chrome Translate) break when client state and DOM headers de-synchronize.

Critical Failure Modes

  1. Hardcoded SSR Root <html lang>: Server-side layout hardcodes <html lang="de">. Chrome inspects raw markup before client hydration and permanently locks the detected page language.
  2. Client DOM De-sync: Language switchers update React state but fail to synchronize document.documentElement.lang, <meta http-equiv="content-language">, and document.title.
  3. Naive Substring Matching vs. RFC 9110: Using header.includes("en") breaks multilingual requests (e.g. de-CH,de;q=0.9,en;q=0.8). The server forces English despite German having higher priority (q=0.9).
  4. Mangled Switcher Badges: Missing translate="no" and className="notranslate" causes Chrome to translate ISO language codes (DE translated to preposition "of/from").

The Master Prompt

Perform an internationalization (i18n) and browser translation audit on this project, fix any detected bugs, and run the complete release pipeline:

1. **i18n & Browser Translation Audit**:
   - **Root `<html lang>`**: Ensure `<html lang="...">` is NEVER hardcoded. It must dynamically match the active locale on server-side rendering (reading cookies, URL parameters, and `Accept-Language` headers).
   - **RFC-Compliant Header Parsing**: Verify `Accept-Language` header parsing does NOT use naive substring matching (e.g. `header.includes('en')`). It must parse RFC 9110 quality weights (`q=...`) and primary language subtags so users with fallback languages aren't incorrectly mapped to the wrong language.
   - **Client-Side DOM Sync**: Whenever the user switches language in the UI, reactively synchronize:
      - `document.documentElement.lang`
      - `<meta http-equiv="content-language" content="...">`
      - `document.title`
      This prevents Chrome / Google Translate from misdetecting the source language and offering incorrect translation popups.
   - **Switcher Protection**: Ensure language switcher badges (`DE`, `EN`, `PT`, `FR`, etc.) have `translate="no"` and `className="notranslate"` to prevent auto-translation tools from translating language codes.
   - **SEO Alternates**: Ensure `metadata.alternates.languages` (hreflang links) are configured for all supported locales.

2. **Code Assessment & Testing**:
   - Check for regressions, edge cases, and type safety.
   - Run unit tests and linting (`npm test`, `npm run lint`, `npm run build`).

3. **Delivery & Deployment Pipeline**:
   - Create a dedicated fix branch (`fix/i18n-lang-sync`).
   - PR to `develop`, wait for CI checks to pass, and merge.
   - Bump release version in `package.json`, PR from `develop` to `master`, wait for CI checks to pass, and merge.
   - Tag the release version (e.g. `vX.Y.Z`).
   - Monitor the CI/CD production deployment until complete and verify live HTTP response headers and `<html lang="...">`.

2. Dedicated Deep-Dive Pipeline Guides

For focused operational pipelines, I have extracted dedicated directives into standalone articles:


3. Non-Destructive Database, Migration & Rollback Policy (NON-NEGOTIABLE)

For any database-aware platform, this directive prevents destructive schema changes, accidental record overwrites during runtime seeding, and unverified migrations:

## NON-DESTRUCTIVE DATABASE, MIGRATION & ROLLBACK POLICY (NON-NEGOTIABLE)

1. **Strictly Additive Schema Evolution (Expand-and-Contract)**:
   - Every schema migration, runtime seed, and production update MUST be 100% non-destructive.
   - NEVER include `DROP TABLE`, `DROP COLUMN`, `TRUNCATE`, `DELETE FROM`, or `ADD/MODIFY COLUMN ... NOT NULL` without a `DEFAULT` value in any SQL migration.
   - NEVER invoke destructive ORM commands (`db push`, `migrate reset`, `--force-reset`, `--accept-data-loss`) outside isolated local ephemeral test databases.

2. **Additive-Only Runtime Seeding**:
   - Runtime seeders/bootstrappers MUST strictly follow `CREATE IF NOT EXISTS` semantics.
   - NEVER overwrite, `.update()`, or `.delete()` existing records in runtime code.
   - Dev/CI reset seeders MUST verify the DB host is `localhost`/`127.0.0.1` AND require explicit `ALLOW_DESTRUCTIVE_SEED=true`.

3. **5-Gate Automated Verification (`db:verify-safe` & `test:non-destructive`)**:
   - **Static DDL & Seed Audit**: Scan all migration files, ORM schemas, and seeders for destructive statements.
   - **Git State-Transition Diff (`origin/master -> HEAD`)**: Verify zero deleted models/tables, zero deleted fields/columns, zero incompatible column type mutations, and 100% SHA-256 checksum immutability of already-published migrations.
   - **Live Full-DB Snapshot Preservation Test**: Snapshot every row and column across all tables before migration/seeding, execute the transition, and assert 100% of pre-existing rows and field values remain identical.
   - **3-Tier Rollback Planner & `UP -> DOWN -> RE-UP` Round-Trip Test**: Synthesize compensating DOWN SQL for every migration, verify Tier-1 Code-Only Rollback compatibility, and test the live `Migrate UP -> Rollback DOWN -> Re-Migrate UP` cycle against a real test database in CI.
   - **Pre-Migration Backup in CI/CD**: Always capture a compressed logical database dump immediately before running production migrations.

4. Quick Targeted i18n Audit (No Git Overhead)

For localized debugging or small repositories where git release cycles are handled out-of-band:

Inspect the i18n setup to make sure the page language is correctly declared to browsers:

1. Check that the root `<html lang>` attribute dynamically reflects the active locale during SSR (via cookie, query param, or RFC 9110 `Accept-Language` header parsing with `q` weights).
2. Ensure client-side language switching dynamically updates `document.documentElement.lang`, `meta[http-equiv="content-language"]`, and `document.title`.
3. Add `translate="no"` and `className="notranslate"` to language switchers so Google Translate doesn't mangle language codes.
4. Run tests and verify with a curl test that different `Accept-Language` headers and cookies return the matching `<html lang="...">`.

The Engineering Formula: 4 Pillars of Agentic Directives

Pillar Technical Rationale Operational Rule
1. Technical Specificity Prevents heuristic guessing by the LLM. Name RFC standards, DOM attributes, and exact HTTP headers.
2. Self-Healing Gates Ensures verified functionality before turn completion. Enforce npm test, npm run lint, and build exits.
3. Operational Scope Maintains repository discipline automatically. Route changes strictly through branch -> develop -> CI -> master -> tag.
4. Invariant Protection Prevents unintended collateral damage. State explicitly what must remain untouched or protected.
— FINIS • PRINTED IN THE ZÜRICH ARCHIVE —
NR

Nuno Ribeiro

Head of Cloud, Systems Architect (C++, Rust, TypeScript), and visual artist based in Zürich. Writing on distributed architectures, low-latency execution pipelines, and visual discipline.