Kuidas hoida kasutajaliidese tekstid koodibaasis järjepidevad: üks kataloog, võtmed ja tekstid diffis

Kasutajaliidese tekstid püsivad järjepidevad, kui iga kasutajale nähtav string asub hoidlas ühes kataloogis, sellele viidatakse võtmega ja seda muudetakse ainult ülevaadatud diffi kaudu. See on sama distsipliin, mida te juba loogika puhul rakendate, nüüd sõnastusele. Kõik muu sellel lehel on praktika, mis selle püsima paneb.

See on operatiivne juhend. Arhitektuur selle taga ja argument, miks peaks koodibaas olema toote tekstide tõeallikas, on artiklis koodipõhised toote tekstid. Lugege seda, kui soovite teada, miks. Lugege edasi, kui soovite teada, kuidas.

Kus peaksid kasutajaliidese tekstid asuma?

Ühes kataloogifailis lähtekeele kohta, hoidla sees, selle koodi kõrval, mis tekste kuvab. Mitte arvutustabelis, mitte disainifailis, mitte vikilehel, mis oli märtsis õige. Kataloog on koht, kuhu vaatavad arendaja, ülevaataja, tõlkija ja kodeerimisagent, kui nad tahavad teada, mida ekraan ütleb.

Praktilised reeglid, mis sellest tulenevad:

• Üks kataloog, üks lähtelokaal. Üks en.json (või .po, .ftl, .strings, mida iganes teie i18n-teek loeb) on lõplik tekstiallikas. Kui monorepos on mitu rakendust, saab igaüks oma kataloogi ning jagatud stringid saavad ühise kataloogi, mida mõlemad impordivad. Vältida tuleb kahte faili, mis võivad sisaldada sama sõnumit.
• Grupeerige ekraani või funktsiooni, mitte komponendi järgi. Sellised võtmed nagu checkout.summary.total vananevad paremini kui SummaryCard.totalLabel, sest komponente nimetatakse ümber ja jagatakse, aga ekraan ja sõnum jäävad paigale.
• Nimetage võti sõnumi, mitte sõnastuse järgi. checkout.submit jääb püsima ka siis, kui „Place order“ asendatakse sõnastusega „Buy now“. checkout.placeOrderButton ei jää, ja võtme ning teksti mittevastavus paneb ülevaataja hiljem arvama, et tegu on kahe eri stringiga.
• Hoidke kataloog samas pull request'is koodiga, mis seda kasutab. String, mis lisati ühes PR-is, ja selle komponent teises, on string, mis jääb märkamata, ununeb või dubleeritakse.

Kui teie stringid on endiselt komponentides literaalidena, on kataloog esimene asi, mis luua. Käsitsi on see omaette projekt, mistõttu tasub hoidla ühendada ja lasta konversioon ära teha, millest allpool täpsemalt.

Miks on võtmega viitamine parem kui literaali otsimine?

Sest võti saab viidata ainult ühele stringile, aga literaali saab sisestada nii mitmel viisil, kui on arendajaid. „Sign in“, „Sign In“, „Log in“ ja „Login“ on otsingutööriista jaoks neli stringi ja kasutaja jaoks üks kavatsus. Kui iga komponent kutsub t("auth.signIn"), saab küsimusele, milline sõnastus on õige, vastuse üks kord ühes kohas ja vastus kehtib kõikjal, kus võtit kasutatakse.

Kaks harjumust hoiavad selle toimimas:

• Taaskasutage enne lisamist. Enne võtme loomist otsige kataloogist sõnumit. Kui common.cancel on olemas, on uus dialog.cancelButton sama tekstiga hajumise algus, mitte süütu duplikaat. Need kaks muutuvad sõltumatult, kohe kui keegi ühte neist muudab.
• Ärge liitke stringe. t("cart.items") + " " + count toodab teksti, mida ükski kataloogirida ei kirjelda. Kasutage teegi interpolatsiooni ja mitmusevorme, et kogu lause oleks üks ülevaadatav ühik.

Erand, mille poole inimesed pöörduvad, on „see string esineb ainult üks kord, nii et literaal sobib“. Täna esineb see üks kord. Komponent kopeeritakse, ekraan saab õe ja literaal rändab kaasa ning hakkab erinema.

Kuidas vaadata tekstimuudatusi pull request'is üle?

Käsitlege muudetud kataloogirida nagu muudetud funktsiooni signatuuri: midagi, mida ülevaataja loeb, kahtluse alla seab ja kinnitab. See praktika muudab järjepidevuse mäluprobleemist ülevaatusprobleemiks ja ülevaatus on ainus hetk, mil keegi kindlasti tähelepanelik on.

Mis paneb kataloogi ülevaatuse toimima:

• Sõnastuse muudatus on diffis eraldi rida. See kehtib ainult siis, kui string on kataloogis. Sõnastuse muudatus komponendi sees on samuti diffi rida, kuid see kaob loogikamuudatuste hulka ja jäetakse „lihtsalt tekstina“ kahe silma vahele.
• Suunake kataloogi muudatused tekstide omanikule. CODEOWNERS kirje kataloogi asukohale tähendab, et sõnastuse omanik, olgu see tootejuht, sisudisainer või arendaja, kellele see kõige rohkem korda läheb, määratakse iga muudatuse korral ülevaatajaks. Kõik muu PR-is läbib tavapärase ülevaatuse.
• Esitage iga muudetud rea kohta kolm küsimust. Kas see on selle asja kinnitatud termin? Kas see sobib ümbritsevate stringidega tooni ja suur-/väiketähtede poolest? Kas võtme nimi kirjeldab sõnumit endiselt? Ülevaataja, kes need kolm küsib, püüab kinni suurema osa sellest, mille ärahoidmiseks stiilijuhis olemas on.
• Lükake tagasi vaiksed ümbernimetamised. PR, mis muudab auth.signIn tekstist „Sign in“ tekstiks „Log in“ ilma selgituseta, on tekstiotsus, mille tegi see, kes parajasti muutmisega tegeles. PR-i kirjelduses peab olema lause, mis seletab põhjust, vastasel juhul tuleb muudatus tagasi võtta.

Rikkel, mida see ennetab, on oma nimi. Copy drift ehk tekstide hajumine tähendab, et kasutajale nähtav tekst lahkneb eri pindadel ja ajas oma kinnitatud allikast, kuna puudub ühtne tõeallikas, millega kooskõlas püsida. Mis on copy drift käsitleb põhjuseid; kataloogi ülevaatus diffis on praktika, mis peatab enamiku neist.

Kuidas takistada uute hardcoded stringide sissepääsu?

Pange uus literaal ehituse läbi kukkuma. Reeglid ja ülevaatused püüavad kinni selle, mida inimesed mäletavad otsida. Lint-reegel püüab kinni ülejäänu, igal pull request'il, ilma et keegi peaks meeles pidama.

Seadistus on väike:

• Lülitage sisse no-literal-string reegel. eslint-plugin-i18next sisaldab sellist reeglit JavaScripti ja TypeScripti projektide jaoks. Piirake selle ulatus JSX-tekstide ja kasutajale nähtavate atribuutidega, nagu sisestusvihjed, title, aria-label ja alt, ning jätke testifailid ja Storybooki näited reeglist välja, et reegel püsiks usaldusväärne.
• Käivitage see seal, kus liitmine toimub. Pre-commit hook on mugav; CI samm on see, mis loeb, sest see töötab pull request'il sõltumata sellest, kas autori redaktor oli seadistatud.
• Lisage kasutamata ja puuduvate võtmete kontroll. Enamikul i18n-teekidel on kaastööriist, mis loetleb koodis viidatud, kuid kataloogist puuduvad võtmed ning kataloogis olevad võtmed, millele ei viita miski. Käivitage see samuti CI-s. Just kasutamata võtmetes peituvad aegunud sõnastused.
• Alustage rangelt, seejärel lubage erandeid kommentaariga. Reegel, mis on kogu components/ kaustas välja lülitatud, ei ole reegel. Reegel, mis on välja lülitatud ühel real koos põhjendusega, on dokumentatsioon.

Tehisintellekti kodeerimistööriistadega ehitavad tiimid puutuvad selle probleemiga rohkem kokku, sest tööriistad genereerivad komponendid uuesti kohaliku konteksti põhjal ja toovad literaalid tagasi. Miks Cursor AI lisab pidevalt hardcoded stringe käsitleb lint-reeglit üksikasjalikult, sealhulgas kolmekihilist seadistust: reeglifail, linter ja CI.

Mis kuulub arendajatele mõeldud tekstide stiilijuhisesse?

Lühike fail hoidlas, mis mahub ühele ekraanile, määrab tooni, fikseerib terminid ja ütleb, kuhu stringid lähevad. Pikad stiilijuhised asuvad wikis ja neid loetakse ühe korra. Lühike juhis asub koodi kõrval ja inimesed ning tööriistad loevad seda iga kord, kui stringi lisatakse.

Töötav COPY.md (või jaotis olemasolevas panustajate juhendis) hõlmab:

1. Toon kolmes lauses. Kellena toode kõlab, kui formaalne see on, kas see ütleb „sina“ või „kasutaja“. Piisavalt, et lahendada enamik vaidlusi.
2. Terminid, mis ei varieeru. Toote kasutatav nimetus igale funktsioonile, põhitoimingute verbid (kas „Save“ või „Update“? „Delete“ või „Remove“?) ja sõnad, mida olete otsustanud mitte kasutada.
3. Suur- ja väiketähtede ning kirjavahemärkide reeglid. Lausekirjaviis või pealkirjakirjaviis nuppudes ja pealkirjades, punkt vihjetekstide lõpus või mitte, kuidas numbreid ja kuupäevi kirjutatakse.
4. Kuhu stringid lähevad ja kuidas võtmeid nimetatakse. Kataloogi tee, grupeerimisreegel, võtmete nimetamise reegel ja „otsi enne lisamist“.
5. Mida teha, kui pole kindel. Keda küsida või millist võtit vahepeal taaskasutada.

Hoidke see hoidlas, et reeglifail saaks sellele viidata, ülevaataja saaks kommentaaris lingi anda ja kodeerimisagent saaks selle läbi lugeda enne sildi kirjutamist.

Kuidas hoida tehisintellektil põhinevad kodeerimisagendid järjepidevust lõhkumast?

Andke agendile loetav tõeallikas ja värav, mis ta kinni püüab, kui ta sellest kõrvale kaldub. Vormi genereeriv agent kirjutab hea meelega ühele ekraanile „Submit“ ja järgmisele „Send“, sest kumbki oli oma konteksti põhjal kõige tõenäolisem sõna. Ta ei ole hooletu; tal pole lihtsalt millegagi kooskõlas püsida.

Kaks sammu lahendavad suurema osa probleemist. Esiteks reeglifail (AGENTS.md, .cursor/rules, CLAUDE.md, mida iganes teie tööriistad loevad), mis ütleb: kasutajale nähtav tekst läheb kataloogi, taaskasutage olemasolevaid võtmeid ja lugege COPY.md enne sildi kirjutamist. Teiseks eelmises jaotises kirjeldatud lint-reegel, sest reeglifail vähendab oletamist ja lint-reegel püüab kinni need oletused, mis siiski läbi pääsesid.

See on kõik, mis sellel lehel agentide kohta öelda on. Konkreetne probleem, kus agent sõnastab ümber varem olemasolevad stringid, ja kuidas teha see muudatus vaikse asemel nähtavaks, on omaette teema: kuidas peatada tehisintellektil põhinevaid kodeerimisagente teie kasutajaliidese tekstide ümberkirjutamast.

Kuhu lokaliseerimine siia sobitub?

Järjepidevus ja lokaliseerimine sõltuvad samast asjast, kokkulepitud allikast, ning kataloog, mis annab ühe, annab ka teise. Tiim, kes ei oska öelda, milline kolmest sõnastusest on kinnitatud, ei saa ühtegi neist ka õigesti tõlkida. Kui allikas on korras, muutub tõlge kataloogist tuletatud tulemiks, mitte omaette projektiks, millel on oma versioon tõest.

Praktikas tähendab see, et järjepidevuse jaoks ehitatud kataloog on juba fail, mille põhjal tõlkija või tõlketööriist töötab. Iga võti saab oma vasted kõigis sihtkeeltes, samad võtmenimed kehtivad ja sõnastuse muudatus lähtekataloogis on nähtav muudatusena, mida tõlked peavad järgima. Kui tõlked jäetakse allikast maha jääma, tekib probleemide klass, mida kirjeldab artikkel miks tõlkefailid sünkroonist välja lähevad, ja lahendus on taas sama distsipliin: üks kataloog, võtmed, muudatused diffis.

Kuhu globalize.now sobib

globalize.now on koodipõhine tekstihaldussüsteem sisseehitatud lokaliseerimisega ja iga sellel lehel kirjeldatud praktika on see, mida ta teie hoidla puhul eeldab. Ühendate rakenduses GitHubi või GitLabi hoidla. Skannimine selgitab välja, mis seal on. Kui stringid on komponentides literaalidena, tõstab ühekordne teisendus need võtmete alla kataloogi ja lisab i18n-seadistuse, kui seda veel pole. Kui kasutate juba next-intl'i, react-i18next'i, i18next'i või Lingui't, töötab see olemasolevaga. Tulemus jõuab teieni pull request'ina eraldi harus, nii et esimene kataloog läbib täpselt eespool kirjeldatud ülevaatuse. Pärast seda tõlgivad teie lisatud uusi lähtestringe push-töövood, mis avavad tulemusega pull request'i. Hoidla jääb ainsaks tõeallikaks.

Ehitame selle poole, et sama distsipliin kehtiks turunduslehel, sihtlehel ja tootes ühest allikast, nii et funktsiooni kirjeldatakse ühtmoodi kõikjal, kus kasutaja sellega kohtub. See on suund, kuhu liigume, mitte midagi, mida täna osta saab. Hinnad on hinnalehel.

Kontrollnimekiri, mille saate sel nädalal kasutusele võtta

1. Looge hoidlas üks kataloog lähtekeele kohta ja otsustage võtmete nimetamise reegel.
2. Viige sinna stringid ekraanidelt, millega te kõige sagedamini tegelete; viidake neile võtme kaudu.
3. Lülitage sisse no-literal-string lint-reegel, mis on piiratud kasutajale suunatud tekstiga, ja käivitage see CI-s.
4. Lisage kataloogi teele CODEOWNERS rida.
5. Kirjutage COPY.md: toon, fikseeritud terminid, kirjaviisi reeglid, kuhu tekstid paigutatakse. Üks ekraan.
6. Suunake oma agendi reeglifail kataloogile ja COPY.md.
7. Lükake ülevaatuses tagasi iga sõnastusmuudatus, millel pole PR-i kirjelduses põhjendust.

Kui teine samm tundub nagu kuu aja töö, ühendage hoidla, lugege läbi selle pakutud plaan ja vaadake üle selle avatud PR.