Kuidas takistada AI-koodiagentidel kasutajaliidese tekste ümber kirjutamast

Palusite Claude Code’il sisselogimisvormile laadimisoleku lisada. Laadimisolek töötab. Nüüd ütleb nupp aga „Log in” asemel „Sign in”, veateade muutus sõbralikumaks ja üks pealkiri on järsku lausekujuline. Keegi ei palunud seda, kõik testid läbivad ning kui keegi kogu diff’i sõna-sõnalt läbi ei loe, jõuab muudatus tootmisse.

See postitus käsitleb konkreetset tõrget: olemasoleva, heakskiidetud copy vaikset ümber sõnastamist AI-koodiagendi poolt ning töövoogu, mis seda ennetab. Stringid, mille agendid ise loovad hardcoded ja võtmeteta kujul, on teine probleem, mida käsitleb miks AI-kooditööriistad lisavad pidevalt hardcoded string’e. Küsimus, kus toote copy üldiselt paiknema peaks, on arhitektuuriküsimus, mida käsitleb koodipõhine toote-copy. See postitus keskendub juhtumile – esmaspäeva hommikule, mil sõnastus oli muutunud, kuigi keegi polnud seda otsustanud. globalize.now on koodipõhine copy-haldussüsteem, millesse lokaliseerimine on sisse ehitatud, ning see juhtum on üks põhjustest, miks see olemas on.

Miks kirjutavad AI-koodiagendid kasutajaliidese tekste ümber?

AI-koodiagendid kirjutavad kasutajaliidese tekste ümber, sest näevad komponentides otse olevat proosat. Kui tekst asub lähtekoha lokaalifailis võtmete taga, muutub selle muutmine selgesõnaliseks ja ülevaadatavaks muudatuseks, mitte mõne muu ülesande kõrvalmõjuks.

Komponendi sees pole „Sign in” kuidagi eristaatuses. See on JSX-atribuudis olev stringliteral, mida ei saa eristada className’ist ega testi ID-st. Agent on treenitud miljonite diff’ide põhjal, kus lähedalasuva koodi parandamine oli hea käitumine, ning mudeli jaoks on sildi „selgemaks” tegemine sama liigutus mis muutuja ümbernimetamine. Ei ole tüübiviga, mis ootaks avastamist, läbikukkuvat testi ega sõnadele lisatud omanikumärget. Ümber sõnastamine ei maksa agendile midagi.

Muudatus läbib ülevaatuse samal põhjusel. Ülevaatajad loevad loogikat. Sõnastuse muutus paikneb laadimisolekut õigustatult käsitleva diff’i keskel, kood kompileerub ja renderdub ning kui snapshot-test kaebab, on tavapärane vastus snapshot’i uuendamine – nii salvestatakse uus sõnastus, nagu oleks see heaks kiidetud.

Kas reeglifailid, näiteks AGENTS.md, tõesti peatavad selle?

Agendireeglite failid vähendavad juhtumite sagedust, kuid ei muuda kasutajaliidese copy’d kirjutuskaitstuks. Muudatuse nähtavaks teeb arhitektuur.

Reeglifail tasub igal juhul lisada – see on odavaim kiht ja töötab piisavalt sageli, et selleks kulutatud kolmkümmend sekundit end ära tasuks. See plokk töötab AGENTS.md-is, CLAUDE.md-is ja Cursori reeglites (.cursorrules või .cursor/rules/):

## UI copy policy — do not modify user-facing text

- Never change user-visible strings (button labels, headings, empty states,
  error messages, tooltips, placeholder text) unless the task explicitly
  asks for a copy change.
- User-visible text lives in the source locale file (e.g. locales/en.json).
  Reference it by key. Never inline a new user-facing string in a component.
- If a task needs new user-facing text, add a key to the source locale file,
  reference it, and list the new key in your summary for copy review.
- Any diff to the source locale file is a copy change. Call it out
  separately — it needs its own approval, apart from code review.

Nüüd aus osa. Reegel on kontekst ja kontekst konkureerib. Pika ülesande puhul on juhis üks rida tuhandete kooditokenite seas ning mõnikord jääb see alla – tihendamisele, alam-agendile, kes seda kunagi ei näinud, või ümbritsevas failis tugevalt kinnistunud mustrile. Veel hullem, reeglit rikkuv agent ei anna sellest teada. Te ei saa teadet, et sõnastus muutus; saate diff’i, milles see lihtsalt on muutunud. Konventsioon ei ole kontroll.

Seega on reeglifail esimene kiht, kuid kiht, mida ei tohiks üksinda usaldada.

Kuidas muuta copy muudatus vaikse asemel nähtavaks?

Viige kõik kasutajale nähtavad stringid komponentidest välja ja lähtekoha lokaalifailis võtmete taha. Pärast seda peab agent, kes soovib teie sõnastust muuta, redigeerima faili, mille kogu eesmärk ongi sõnastus.

Seda sammu reeglifail teha ei saa ja mehhanism on lihtne. Kui komponendid viitavad t('auth.signIn')-ile, selle asemel et „Sign in” uuesti välja kirjutada, muutub korraga kaks asja. Komponentide diff’id ei sisalda enam copy’d, mistõttu laadimisoleku kallal töötaval agendil pole seal midagi ümber sõnastada. Ning iga copy muudatus – agendi või inimese tehtud – jõuab ühte faili, kus muudetud rida ongi sündmus, millest hoolite, mitte selle ümber olev müra. Lokaalifaili diff’i saab läbi vaadata sekunditega. Halva ümber sõnastuse tagasivõtmine tähendab ühe rea taastamist.

Täpsustuseks, mida see annab: agent saab endiselt lokaalifaili muuta. Mõte pole selles, et sõnad muutuksid puutumatuks, vaid selles, et nende puudutamine ei ole enam kõrvalmõju, vaid selgelt loetav ja ülevaadatav tegevus. See on erinevus selle vahel, kas saate muutusest teada diff’i või kliendi kaudu.

Täielik põhjendus, miks hoida tõeallikat koodibaasis, mitte sellega sünkroonitavas disainitööriistas, on teemas koodipõhine toote-copy. Selle postituse jaoks piisab ühest tagajärjest: võtmetega copy muudab teie reeglifaili palvest millekski, mida saab kontrollida.

Milline näeb ülevaatusvärav välja?

Käsitlege iga lähtekoha lokaalifaili diff’i copy muudatusena ja suunake see sõnade eest vastutavale inimesele.

Praktiliselt: lisage lokaalide kataloog CODEOWNERS-i, et copy eest vastutav inimene kaasataks iga selle muudatuse puhul. Lisage PR-i mallile üks rida: „Kas see PR muudab kasutajale nähtavat sõnastust ja kas see oli ülesande eesmärk?” Säilitage ka reeglifaili nõue, et agent loetleks kokkuvõttes muudetud võtmed; kui ta seda teeb, on ülevaatus hetkeline, ja kui ei tee, püüab CODEOWNERS-i konks selle ikkagi kinni.

Väikeses tiimis on see lihtsam, kui kõlab. Lokaalifaili diff on lühike, seda saab lugeda tavakeeles ning küsimus „Kas see nupp peaks nüüd ütlema „Log in”?” on otsus, mille saab teha viie sekundiga – eeldusel, et küsimus üldse inimeseni jõuab. Just see ongi värava kogu ülesanne.

Mis siis, kui agent on teie copy juba ümber kirjutanud?

Taastage esmalt heakskiidetud sõnastus ja pange stringid seejärel võtmete taha, et järgmine ümber sõnastamine ilmuks diff’is.

Kahju leidmine on git’i töö: võrrelge mõjutatud komponente viimase usaldusväärse commit’iga ja lugege ainult stringliteraale. Taastage muutunud tekst. Kui te ei saa kindlalt öelda, milline sõnastus oli heaks kiidetud – nupp ütleb „Log in”, turundusleht „Sign in” ja ükski artefakt ei näita, kumb on õige –, olete jõudnud sügavama seisundini, mida see juhtum paljastab. Copy triiv tähendab, et kasutajale nähtav tekst erineb eri pindadel ja aja jooksul heakskiidetud allikast, ilma et oleks ühtainsat tõeallikat, millest triivida. See termin, selle põhjused ja tagajärjed on eraldi teema: mis on copy triiv.

Seejärel pange võtmete taha see, mille taastasite, alustades stringidest, mida agent puudutas. Need on tõendatult tulejoonel.

Kuhu lokaliseerimine siia sobitub?

Vaikne ümber sõnastamine on ühes keeles tüütus, kümnes keeles aga risk: iga vana sõnastuse põhjal tehtud tõlge on nüüd aegunud ja miski ei anna teile märku, et see tuleks uuesti tõlkida.

Siin hakkab agendi juhtum kuhjuma. Avaldate ümber sõnastatud ingliskeelse teksti, kuid saksa, jaapani ja hispaania keel ütlevad endiselt vana asja – nüüd on keeled omavahel vastuolus, mitte ainult ekraanid. Kataloogide sünkroonist väljalangemine on omaette tõrkerežiim oma lahendustega, mida käsitleb sünkroonist väljas tõlkefailid.

Võtmetega copy sulgeb ka selle ringi, sest muudetud lähtekohatekst on nähtav sündmus, mille külge tõlked kinnituvad, mitte vaikselt liikunud literaal. Sellel põhineb globalize.now: copy elab koodibaasis, on võtmete taga ühest allikast hallatud ning lokaliseerimine on sama toiming, mitte hiljem külge poogitud lisakiht – ühendage hoidla ja iga keel tuletatakse sellest ühest allikast. AI-kooditööriistadega väljalaskeid tegevad tiimid puutuvad selle probleemiga kõige varem kokku, mistõttu kirjutame arendajatele ja inimestele, kes ehitavad AI-tööriistadega.

Järgmine kord, kui agent teie komponentides töötab, on küsimus selles, kas muudetud silt ilmub otsusena või üllatusena. globalize.now haldab teie kasutajale nähtavaid stringe ühest allikast ühendatud hoidlas ning tuletab kogu copy põhjal iga keele.