i18n noteikumi, kas jāieliek AGENTS.md, lai jūsu kodēšanas aģents beigtu cietkodēt tekstus

Zemāk redzamā i18n sadaļa ir tā, ko ielīmēt AGENTS.md: desmit īsi noteikumi, kas liek kodēšanas aģentam katru lietotājam redzamo tekstu virzīt caur tulkošanas funkciju, veidot tā atslēgu pēc funkcijas, nekad nesasaistīt fragmentus, nekad neimitēt daudzskaitli ar ternāro operatoru un nekad nepieskarties ģenerētam lokalizācijas failam. globalize.now ir ar mākslīgo intelektu darbināta lokalizācijas infrastruktūra, tāpēc mēs redzam daudz aģentu rakstīta i18n koda, un gandrīz visas kļūdas veido viena un tā pati neliela kopa. Katrs noteikums atbilst vienai no tām.

Šī raksta otrā puse ir par to, kur fails pārstāj darboties. Divas visbiežāk izmantotās koda rakstīšanas vides to nelasa nemaz, un neviens formulējums to neatrisina.

Kas jāraksta AGENTS.md i18n sadaļā?

Šis bloks. Pielāgojiet trīs failu ceļus un lint komandu savam projektam, pārējo atstājiet.

## Internationalization

- Every user-visible string goes through the translation function. That
  includes JSX text, input hint text, `title`, `aria-label`, `alt`, toast and
  error messages, empty states and the document `<title>`.
- The source locale is `en`. The catalog is `locales/en.json`. Add the key in
  the same change that uses it.
- Keys are namespaced by feature: `checkout.summary.total`, not `total3`.
  Search the catalog for an existing key before creating one.
- Never concatenate translated fragments. Use interpolation:
  `t('cart.items', { count })`, not `t('cart.you_have') + count`.
- Plurals use the library's plural forms (`_one` / `_other` keys, or ICU
  `{count, plural, ...}`). Never `count === 1 ? 'item' : 'items'`.
- Dates, numbers and currency go through `Intl.DateTimeFormat` and
  `Intl.NumberFormat` with the active locale. Never a bare
  `toLocaleString()`, never a currency symbol glued to a number.
- Do not hardcode the locale list, language names or text direction in
  components. Read them from `i18n/config.ts`.
- Do not translate brand names, code identifiers, URLs or environment values.
- Do not edit locale files other than `en`. They are generated. If a
  translation looks wrong, fix the source key or the glossary, not the file.
- Before finishing, run `npm run lint`. The `i18next/no-literal-string`
  rule must pass.

Desmit noteikumi ir apzināta izvēle. Cursor paša noteikumu dokumentācija iesaka noteikumus veidot fokusētus uz bieži lietotiem paraugiem un izmantot linteri, nevis ielīmēt stila ceļvedi, un Claude Code norādījumi ir tādi paši: rakstiet instrukcijas pietiekami konkrētas, lai tās varētu pārbaudīt, un turiet failu īsu, jo, augot failam, ievērošana pasliktinās. i18n sadaļu četrdesmit punktu garumā tikai pārlasa pavirši.

Kāpēc tieši šie desmit noteikumi, nevis vienkārši „izmanto i18n”?

Jo „izmanto i18n” ir tas, ko aģents jau uzskata, ka dara, rakstot <Button>Save changes</Button>. Neskaidras instrukcijas aģents izpilda pēc savas izpratnes par atbilstību. Katrs zemāk minētais noteikums nosauc konkrētu rezultātu un to aizliedz.

Teksti atribūtos. Aģenti iemācās, ka JSX pakārtotos elementus vajag tulkot, un tad aria-label="Close" un alt="Company logo" raksta kā parastas virknes, jo atribūti izskatās pēc konfigurācijas, nevis satura. Nosaucot atribūtus vārdā, šo robu var aizvērt; vispārīgs „tulko visu” — nevar.

Sasaistīšana. t('greeting') + ' ' + name + '!' angļu valodā attēlojas pareizi, bet to nevar iztulkot nevienā valodā, kurā vārds ir pirmajā vietā vai tiek lokāms. Interpolācija dod tulkotājam vienu tekstu ar vienu pārvietojamu mainīgo.

Ternārie daudzskaitļi. count === 1 ? 'item' : 'items' ir tas, ko mēs visbiežāk redzam aģentu rakstām pēc i18n iestatīšanas, un tas ir nepareizi katrā valodā, kurai ir vairāk nekā divas daudzskaitļa formas. Noteikums nosauc šo paraugu, lai aģents to varētu atpazīt. Ja jūsu katalogs izmanto ICU, sintaksi aplūko rakstā kas ir ICU MessageFormat un kur tas ar mākslīgo intelektu ģenerētās lietotnēs neiztur.

Ģenerētie lokalizācijas faili. Šis noteikums pastāv, jo aģenti ir izpalīdzīgi. Lūgts izlabot kļūdu vācu tekstā, aģents atvērs locales/de.json un to rediģēs, un tas darbosies, līdz nākamais tulkošanas uzdevums failu pārģenerēs no avota. Pasakot aģentam, ka faili, kas nav avota faili, ir ģenerēti, un kur patiesībā jāveic labojums, tiek novērsta kluso regresiju kategorija.

en rediģēšana tajā pašā izmaiņā. Bez šī noteikuma aģents pievieno t('checkout.summary.total') un dodas tālāk, un atslēga tiek attēlota kā pats tās nosaukums, līdz kāds to ievēro. Kataloga ierakstam un tā pirmajai lietošanai jābūt vienā izmaiņu kopā.

Kur katrs rīks faktiski nolasa failu?

Tas pats saturs jāliek dažādās vietās atkarībā no aģenta, un novietojums nosaka, vai noteikums vienmēr atrodas kontekstā, vai tiek ielādēts tikai tad, kad tas ir nepieciešams.

AGENTS.md repozitorija saknē ir kopīgā atrašanās vieta. Formāts ir vienkāršs Markdown bez obligātiem laukiem, to pārvalda Agentic AI Foundation Linux Foundation paspārnē, un to nolasa Cursor, Codex, Copilot kodēšanas aģents un gara citu rīku virkne. Specifikācija atbalsta ligzdotus failus, un uzvar tas, kas atrodas vistuvāk rediģējamajam failam.

Cursor nolasa AGENTS.md tieši, ieskaitot ligzdotos, un tam ir arī savs formāts ar darbības jomu. Noteikums, kas ierobežots ar UI failiem, paliek ārpus konteksta, līdz tiek atvērts atbilstošs fails:

---
description: i18n rules for user-visible strings
globs: src/**/*.tsx, src/**/*.jsx
alwaysApply: false
---
(paste the Internationalization section here)

Failam jābeidzas ar .mdc un jāatrodas .cursor/rules/; parasts .md šajā mapē tiek ignorēts, jo tam nav frontmatter bloka.

GitHub Copilot programmā VS Code piedāvā trīs iespējas. .github/copilot-instructions.md attiecas uz katru tērzēšanas pieprasījumu. .github/instructions/i18n.instructions.md fails ar applyTo: "**/*.tsx,**/*.jsx" frontmatter attiecas tikai tad, kad šie faili tiek izveidoti vai mainīti. Savukārt AGENTS.md repozitorija saknē nolasa Local aģents, kad ieslēgts iestatījums chat.useAgentsMdFile; ligzdotie AGENTS.md faili apakšmapēs ir pieejami aiz atsevišķa eksperimentāla iestatījuma chat.useNestedAgentsMdFiles, kas pēc noklusējuma ir izslēgts. Copilot specifiskā uzvedība aplūkota rakstā kā pievienot i18n lietotnei, kas izveidota ar GitHub Copilot.

Claude Code nolasa CLAUDE.md, un kopš versijas v2.1.277 patstāvīgi nolasa saknes AGENTS.md, ja projektā virs darba direktorijas nav CLAUDE.md. Ja paturat abus, dokumentētais paņēmiens ir @AGENTS.md imports CLAUDE.md sākumā, lai fails tiktu ielādēts vienreiz. Darbības jomas ierobežošanai .claude/rules/i18n.md ar paths: sarakstu frontmatter ielādējas tikai tad, kad Claude nolasa atbilstošu failu. Pilnu Claude Code darbplūsmu skatiet rakstā kā lokalizēt lietotni, ko ģenerējis Claude Code.

Praktisks risinājums repozitorijam, ar ko strādā vairāki aģenti: desmit noteikumi ierobežota apjoma failā tam aģentam, ko jūsu komanda lieto visvairāk, un divu rindu norāde AGENTS.md („UI teksti: skatiet i18n noteikumus .cursor/rules/i18n.mdc un ievērojiet tos”), lai jebkurš aģents bez darbības jomas atbalsta tik un tā saņemtu instrukciju.

Kurās koda rakstīšanas vidēs AGENTS.md netiek lasīts nekad?

Iekļautā koda pabeigšana. To dokumentējuši abi izstrādātāji, un tieši tāpēc noteikumu fails nevar būt pilnīgs risinājums.

Cursor noteikumu BUJ uz jautājumu „Vai noteikumi ietekmē Cursor Tab vai citas AI funkcijas?” atbild ar viennozīmīgu „nē”. Noteikumi tiek nodoti Agent; Tab — automātiskā pabeigšana, kas papildina rindu, ko rakstāt, — tos neredz. VS Code pielāgoto instrukciju lapā Copilot gadījumam ir tāda pati piezīme: instrukcijas netiek ņemtas vērā iekļautajiem ieteikumiem, kamēr rakstāt redaktorā.

Tātad vide, kurā izstrādātājs raksta <p>No results found</p> un pieņem pelēko ieteikuma tekstu, ir tieši tā, kuru noteikumi nekad nesasniedz. Tērzēšana un aģenta režīms tekstam piešķirs atslēgu; pabeigšana, kas pabeidza rindu, kamēr jūs domājāt par citu, — nē. Nedēļas laikā parastā darbā kodu bāzē uzkrājas burtiski teksti no vienīgā ceļa, ko instrukciju fails nesedz, un izstrādātājs, uzrakstījis rūpīgu noteikumu failu, secina, ka aģents to ignorē.

Claude Code nav iekļautās pabeigšanas virsmas, taču tā dokumentācija to pašu domu izsaka no otras puses: CLAUDE.md saturs ir konteksts, nevis uzspiesta konfigurācija, un, lai bloķētu darbību neatkarīgi no modeļa lēmuma, izmanto hook. Tas ir pareizais domāšanas modelis visiem šeit minētajiem rīkiem. Instrukciju faili maina varbūtības. Tie neuzspiež.

Kas patiesībā īsteno noteikumu?

Lint noteikums CI vidē, un tas ir vienas rindas papildinājums, ja noteikumu fails jau liek aģentam to palaist. eslint-plugin-i18next piegādā no-literal-string; ieslēdziet to savām komponentu direktorijām, un burtisks teksts JSX izraisīs būvējuma kļūdu, nevis pieklājīgu atgādinājumu. Iestatīšana, noteikuma opcijas un tas, kāpēc instrukcija un uzspiešana ir divi dažādi slāņi, izklāstīti rakstā kāpēc Cursor pēc i18n iestatīšanas turpina pievienot burtiskus tekstus, tāpēc šajā rakstā to neatkārtosim.

Lint slānis dod divas lietas, ko noteikumu fails nespēj. Tas noķer iekļautās pabeigšanas rezultātu, jo darbojas ar failu, nevis ar sarunu. Un tas pārvērš paša aģenta ciklu par labojumu: pēdējais noteikums iepriekšējā blokā liek aģentam pirms pabeigšanas palaist lint, un aģents, kas redz no-literal-string kļūdu, pats atslēgs tekstu tajā pašā sesijā.

Claude Code gadījumā uzspiešanas mehānisms, uz kuru norāda tā dokumentācija, ir PreToolUse vai pēc-rediģēšanas hook, kas palaiž linteri uz tikko uzrakstīto failu. Hook darbojas kā čaulas komandas noteiktos punktos un attiecas neatkarīgi no tā, vai modelis izvēlējās ievērot noteikumu.

Kas notiek ar tekstiem, kas tomēr izslīd cauri?

Tie jāizvelk, jāpiešķir atslēgas esošajās nosaukumvietās un jātulko, un tieši to ir vērts automatizēt, nevis atkārtoti dot aģentam jaunus norādījumus. Sarkans būvējums norāda, ka burtisks teksts pastāv. Kādam joprojām tas jāpārvērš par atslēgu, jāpievieno en un jānodrošina tā pieejamība katrā citā lokalizācijā.

Tieši šajā slānī darbojas globalize.now. Konvertēšana ir vienreizēja un notiek lietotnē: pieslēdziet repozitoriju, un kodu bāze tiek konvertēta vienu reizi, katalogu piegādājot kā pull request, ko jūs izskatāt. Pēc tam push uzdevumi iztulko jaunās kataloga vienības, tiklīdz tās parādās, tāpēc otrdien PR pievienotajai atslēgai tulkojumi būs gatavi trešdien. Izpildlaika bibliotēka, kataloga formāts un iepriekš minētais noteikumu fails ir jūsu; izstrādātāju atsauce skaidro, kā aģenti Cursor, Claude Code, Codex un Copilot pēc iestatīšanas uzņemas šo lomu, un Cursor integrācija ir īsākais ceļvedis.

Divi saistīti kļūmju veidi ir aplūkoti atsevišķos rakstos. Ja problēma ir tā, ka aģents pārfrāzē tekstu, kas jau bija atslēgots, skatiet kā novērst, ka AI aģenti pārraksta jūsu UI tekstus — risinājums ir tāda pati avota lokalizācijas disciplīna kā devītajā noteikumā iepriekš. Ja lokalizācijas pastāv, bet nepārtraukti atšķiras, kāpēc tulkojumu faili noiet no sinhronizācijas izskaidro maršrutēšanas kļūmi, kas to izraisa.

Ar ko sākt?

Ielīmējiet bloku, ierobežojiet to ar savām UI direktorijām un tajā pašā pēcpusdienā CI ieslēdziet no-literal-string. Pēc tam nedēļu vērojiet, ko noķer lint noteikums; tas ir jūsu mērs tam, cik daudz noteikumu fails jebkad varēja paveikt pats. Ja piegādājat ar AI veidotu lietotni un vēlaties, lai visu, kas tomēr izslīd cauri, izvilkšanu un tulkošanu kāds veiktu jūsu vietā, nevis jums pašiem tas jāuztur, vibe coders lapa ir pārskats, bet cenas atrodas atsevišķā lapā.