Kur „Lovable“ skaito i18n taisykles? Žinios, įgūdžiai ir AGENTS.md

„Lovable“ i18n taisykles skaito iš trijų vietų: darbo srities ir projekto žinių, kurios visada yra kontekste; įgūdžių, kurie įkeliami tik tada, kai užklausa atitinka jų aprašą; ir instrukcijų failų prijungtoje saugykloje, kur šakninis AGENTS.md skaitomas nepaisant to, kiek ilgai trunka pokalbis. Jei taisykles padėsite ne ten, praėjusią savaitę išversta programa kitą funkcionalumą išleis angliškai. globalize.now yra dirbtinio intelekto varoma lokalizavimo infrastruktūra, todėl šios klaidos pasekmes matome daugelyje „Lovable“ saugyklų; sprendimas daugiausia — žinoti, kuris šaltinis kada skaitomas.

Kodėl išversta „Lovable“ programa grįžta prie anglų kalbos?

Todėl, kad instrukcijos, padariusios programą daugiakalbę, nebuvo agento akiratyje, kai jis rašė kitą komponentą. „Lovable“ sprendžia tą užklausą, kuri matoma ekrane. Jei užklausa sako „pridėk atsiliepimų skiltį“, o kontekste nėra nieko, kas sakytų „kiekviena vartotojui matoma eilutė turi eiti per <Trans>“, antraštė atsiduria kaip literalas — lygiai taip pat, kaip naujame projekte.

Tai ne ta pati problema, kai katalogai atsilieka nuo kodo — tą sinchronizavimo klaidą nagrinėjame straipsnyje kodėl „Lovable“ programos vertimai sulūžta kaskart išleidus naują versiją. Sinchronizavimas perkelia apgaubtas eilutes į lokalės failus. Jis negali perkelti eilutės, kuri niekada nebuvo apgaubta. Pagrindinis klausimas — ką „Lovable“ skaitė tą akimirką, kai rašė kodą, o „Lovable“ dokumentacija šiuo klausimu neįprastai tiksli.

Ką „Lovable“ iš tikrųjų skaito prieš redaguodama?

Pagal jos žinių dokumentaciją, agentą kartu su projekto kodu nukreipia projekto žinios, darbo srities žinios ir instrukcijų failai „Git“ saugykloje, pavyzdžiui, AGENTS.md ar CLAUDE.md. Įgūdžiai yra atskiri ir įkeliami pagal poreikį.

i18n požiūriu jie skiriasi trimis svarbiais aspektais.

Kada jie skaitomi. Žinios įtraukiamos į kiekvieną žinutę. Įgūdis įtraukiamas tik tada, kai užklausa atitinka jo aprašą. Šakninis AGENTS.md, pasak „Lovable“, skaitomas visada, nepaisant sesijos trukmės.

Kiek jie patvarūs ilgame pokalbyje. „Lovable“ dokumentacijoje yra aiški išlyga: labai ilguose pokalbiuose, kuriuose daug konteksto, žinių instrukcijos ne visada vykdomos nuosekliai. Tame pačiame puslapyje apie šakninį AGENTS.md teigiama priešingai. Būtent ši asimetrija ir yra viso šio įrašo priežastis.

Kas gali juos redaguoti. Darbo srities žinias gali redaguoti tik savininkas ir administratoriai. Projekto žinias gali redaguoti kiekvienas, turintis projekto redagavimo teises. Saugyklos failą redaguoja kiekvienas, galintis atlikti push, įskaitant patį „Lovable“ agentą.

Kiekvienas žinių lygis talpina iki 10 000 simbolių. To pakanka nuorodai, bet per mažai visam taisyklių rinkiniui, jei ten norite dar ir architektūros pastabų, duomenų bazės schemos bei prekės ženklo balso.

Tad kur dėti i18n taisykles?

Į saugyklą, o žiniose palikti trumpą nuorodą. Tai išplaukia iš aukščiau pateiktos lentelės.

Saugyklos šaknyje esantis AGENTS.md talpina visas taisykles. Jis skaitomas su kiekviena žinute nepaisant sesijos trukmės, gyvena „Git“, todėl išlieka naujame pokalbyje, atėjus naujam bendradarbiui ar persikėlus prie kito agento, ir neturi simbolių limito, konkuruojančio su likusiu projekto kontekstu. Kai lovable-i18n įgūdis atlieka sąranką, jo trečiasis etapas parašo būtent šį failą: Lingui taisyklių bloką tarp <!-- lovable-i18n:rules:start --> ir <!-- lovable-i18n:rules:end --> žymių — sukuriamą, jei failo nėra, pridedamą, jei jis yra, ir pakeičiamą tarp žymių pakartotinai paleidus, kad niekas nesidubliuotų.

Projekto žinios talpina dviejų eilučių nuorodą. Maždaug tokią:

Localization
- This app is localized with Lingui. Every user-visible string is wrapped
  (<Trans>, t``, msg``) and new strings are appended to src/locales/*/messages.po.
- The full rules are in AGENTS.md at the repo root. Follow them on every edit.

Nuoroda reikalinga tam atvejui, dėl kurio įspėja dokumentacija. Jei ilgas pokalbis praskiedė žinių bloką, agentas vis tiek turi saugyklos failą; jei dėl kokios nors priežasties saugyklos failo kontekste nėra, nuoroda įvardija apribojimą. Dvi vietos, viena taisyklė.

Darbo srities žinios — tik jei visi projektai naudoja tą pačią biblioteką. Darbo srities žinios taikomos visiems darbo srities projektams, o jų rinkinys yra tik vienas. Jei pusė jūsų projektų naudoja Lingui, o kita pusė — ką nors kita, Lingui taisyklė darbo srities lygiu netinka pusei jų, o „Lovable“ konflikto atveju ir taip skatinama teikti pirmenybę projekto žinioms. Darbo srities žinioms palikite taisykles, kurios tinka visur: mygtukai su pirmąja didžiąja raide, jokio console.log, kodo komentarai anglų kalba.

Įgūdis nėra vieta taisyklėms gyventi. Tai nustebina ką tik jį importavusius. Įgūdis įkeliamas, kai užklausa atitinka jo aprašą, todėl lovable-i18n yra kontekste, kai prašote i18n sąrankos, ir jo nėra, kai prašote atsiskaitymo puslapio. Taip ir sumanyta; įgūdis, įkeliamas su kiekviena žinute, tebūtų tiesiog žinios. Įgūdžio užduotis — vieną kartą įrašyti patvarias taisykles į saugyklą ir pasitraukti.

Ką sako AGENTS.md taisyklės?

Jos atsako į klausimus, į kuriuos agentas atsako klaidingai, kai jam tiesiog liepiama „naudoti i18n“. Blokas, kurį įgūdis įrašo, turi šešias dalis.

Kurią makrokomandą naudoti. Sprendimų sąrašas: tekstui, kuris keičiasi pagal skaičių, skirta <Plural> arba ICU daugiskaita; JSX tekstui — <Trans>; atributų reikšmėms ir įvykių tvarkyklių eilutėms, pavyzdžiui, pranešimams (toast), — t, grąžintas iš useLingui(); modulio lygmens konstantoms — msg, kuris išsprendžiamas komponento viduje. Taisyklė taip pat nurodo, iš kokio kelio importuojama kiekviena iš jų, nes neteisingas t importas susieja visuotinį egzempliorių, kurio programa niekada neįkelia.

Interpoliacija. Tik paprastas kintamasis pats įvardija savo vietą ištrauktame pranešime. Bet kuri kita išraiška ištraukiama kaip {0}, su kuriuo vertėjas negali dirbti, todėl taisyklė reikalauja jai pavadinti naudoti ph().

Daugiskaitos. other visada privalomas, kategorijos yra CLDR, o trinaris operatorius tarp dviejų eilučių draudžiamas, nes jis į komponentą įsuka anglų kalbos daugiskaitos taisykles. Jei norite pasiskaityti daugiau, kas yra ICU MessageFormat aprašo sintaksę, į kurią kompiliuojamos daugiskaitos formos.

Skaičiai ir datos. i18n.number() ir i18n.date(), niekada toFixed() ar valiutos simbolis, prijungtas prie reikšmės. „Lovable“ darbo srities žinių pavyzdyje yra lokalizacijos skiltis, nustatanti datos formatą ir skaičių formatavimą pagal Europos įprastus — tai geras instinktas, bet tai formatavimo, o ne eilučių žymėjimo taisyklė. Programa gali ją vykdyti nepriekaištingai ir vis tiek išleisti kiekvieną antraštę angliškai.

Vertėjų komentarai. Trumpos eilutės su keliomis galimomis reikšmėmis, pavieniai veiksmų užrašai ir srities terminai gauna comment=, aprašantį, kur eilutė rodoma. context= skirtas atvejui, kai tas pats tekstas skirtingose vietose turi būti verčiamas skirtingai.

Katalogų priežiūra. Kiekviena nauja eilutė apgaubiama makrokomanda ir pridedama prie kiekvieno src/locales/*/messages.po su tuščiu msgstr, kad Lingui naudotų šaltinio tekstą, kol atkeliaus vertimas. Agentas niekada nevykdo lingui extract, nes „Lovable“ aplinkoje nėra terminalo; tai po sinchronizavimo atlieka „GitHub Action“. Be to, jis niekada nekeičia esamų įrašų #. ir #: komentarų eilučių, nes jas iš naujo sugeneruoja eilučių ištraukimas.

Būtent paskutinė dalis taisykles paverčia specifinėmis „Lovable“. „Cursor“ ar „Claude Code“ taisyklių failas gali baigtis žodžiais „paleisk linterį“. „Lovable“ taisyklių failas taip baigtis negali, todėl jame turi būti nurodyta, ką daryti rankiniu būdu ir ką palikti CI.

Kas užtikrina taisyklės laikymąsi, kai „Lovable“ negali nieko paleisti?

„GitHub“ darbo eiga ir tik ji. „Lovable“ neturi terminalo, todėl tarp agento parašyto literalo ir pakeitimo sinchronizavimo į jūsų saugyklą nėra jokio lint žingsnio. Tai struktūrinis skirtumas nuo IDE agentų, kur CI lint taisyklė sukelia build klaidą dėl tiesiai kode užrašytos eilutės.

Jei sąrankos metu sutinkate, įgūdis prideda „GitHub Actions“ darbo eigą, kuri vykdoma po push į numatytąją šaką (būtent ten patenka „Lovable“ sinchronizavimas), ištraukia apgaubtas eilutes į katalogus ir įkelia katalogų sinchronizavimo commit atgal. Jei „GitHub“ programa neturi workflows leidimo, įgūdis paprašo failą pridėti rankiniu būdu per „GitHub“. Tai uždaro ciklą visoms eilutėms, kurias agentas apgaubė. Eilutei, kurios agentas neapgaubė, tai niekuo nepadeda, nes ištraukimas mato tik makrokomandas.

Taigi sąžiningas vaizdas toks: AGENTS.md taisyklės sumažina neapgaubtų literalų atsiradimo dažnį, žinių nuoroda jas paremia ilguose pokalbiuose, o likusias klaidas galima pastebėti peržiūrint pakeitimus (diff) „GitHub“. Jei norite, kad likusias pagautų automatika, į tą pačią darbo eigą kaip žingsnį pridėkite eslint-plugin-i18next no-literal-string taisyklę. Ji vykdoma saugykloje — vienintelėje vietoje, kurioje „Lovable“ projektas apskritai gali ką nors paleisti.

Kas nutinka toms eilutėms, kurios sėkmingai apgaubiamos makrokomandomis?

Jas reikia išversti, ir būtent tai verta automatizuoti, o ne spręsti pakartotinėmis užklausomis. Konvertavimas vyksta vieną kartą ir programoje: prijungiate saugyklą, o globalize.now vieną kartą konvertuoja kodo bazę ir pateikia katalogą kaip pull request peržiūrai. Po to push užduotys išverčia naujus katalogo vienetus, kai tik jie atsiranda, todėl antradienį „Lovable“ parašytas <Trans> jau trečiadienį turi vertimus pull request. Jokių veiksmų valdymo skydelyje, jokio eksporto, jokios patvirtinimo eilės; plačiau apie tokį modelį skaitykite straipsnyje „Lovable“ programos lokalizavimas be valdymo skydelio, o tikslus sąrankos kelias, įskaitant „GitHub“ prijungimą ir globalize jungtį, aprašytas „Lovable“ integracijos puslapyje.

Dar viena istorinė pastaba — ji paaiškina, kodėl ši problema kai kuriems „Lovable“ kūrėjams atrodo nauja. „Lovalingo“ vertė „Lovable“ programas vykdymo metu naršyklėje, todėl naujai sugeneruotas angliškas komponentas tiesiog būdavo išverčiamas iš naujo įkėlimo metu ir problema niekada neišryškėdavo. Ji nutraukė veiklą 2026 m. rugpjūčio 31 d., o programos, kurios per migracijos vadovą perėjo prie įrašytų katalogų, su šaltinio kodo klausimu susiduria pirmą kartą. Katalogų modelis yra teisingas kompromisas, nes išversta žymėjimo dalis priklauso jums ir yra indeksuojama, tačiau jis reikalauja, kad agentas rašytų išverčiamą kodą, o tam reikia pasakyti, kur yra taisyklės.

Padėkite taisykles ten, kur „Lovable“ jas skaito

Vieną kartą paleiskite įgūdį, kad AGENTS.md turėtų visą bloką, įklijuokite dviejų eilučių nuorodą į projekto žinias ir leiskite „GitHub“ darbo eigai atlikti ištraukimą, kurio redaktorius atlikti negali. Jei kuriate „Lovable“ ir norite, kad viskas, kas patenka į katalogą, būtų išversta be jūsų pastangų, vibe coders puslapyje rasite apžvalgą, o kainos pateiktos atskirame puslapyje.