Next.js i18n: eilutės, kurių jūsų t() iškvietimai nepasiekia

Jei jūsų Next.js programa išversta, bet naršyklės skirtukas, 404 puslapis, formų klaidos ir nuorodos peržiūra vis dar angliški, priežastis beveik visada ta pati: tos eilutės kuriamos už komponento ribų, todėl useTranslations iškvietimas jų niekada nepalietė. globalize.now yra dirbtiniu intelektu grįsta lokalizacijos infrastruktūra, ir būtent šį sluoksnį dažniausiai matome palikus nebaigtą, kai AI agentas prideda i18n į App Router projektą: matomas puslapis konvertuojamas, o likęs paviršius — ne.

Žemiau parodyta, kur kiekviena iš tų eilučių gyvena ir kuris next-intl iškvietimas jas sutvarko. Visi pavyzdžiai atitinka dabartinę next-intl dokumentaciją, gautą 2026-10-28.

Kur neišverstos eilutės slepiasi App Router programoje?

Jos slepiasi šešiose vietose, kurios nėra React komponentai, atvaizduojantys tekstą. Programavimo agentas, kuris prideda i18n eidamas per jūsų komponentus, konvertuos matomą UI ir tiesiog praeis pro šias vietas:

1. Puslapių pavadinimai ir aprašymai generateMetadata.
2. Validacijos klaidos ir rezultatų pranešimai Server Actions.
3. not-found.tsx, 404 puslapis.
4. error.tsx, vykdymo laiko klaidų puslapis.
5. Sugeneruoti failai, pavyzdžiui, opengraph-image.tsx, manifest.ts ir sitemap.ts.
6. Maršrutų apdorojimo funkcijos (Route Handlers), grąžinančios tekstą.

Bendras bruožas — nė viena iš jų neatvaizduojama jūsų [locale] maketų medyje įprastu būdu, todėl lokalę reikia joms perduoti arba nuskaityti kitaip. Next.js 16 maršrutizavimo įraše aptariamas maršrutizavimo sujungimas; šis įrašas — apie tai, ko tas sujungimas nepasiekia.

Kaip išversti puslapių pavadinimus ir aprašymus?

Iškvieskite getTranslations iš next-intl/server funkcijoje generateMetadata. Funkciją galima eksportuoti iš puslapio ar maketo, ji asinchroninė, todėl tinkamas yra await API:

// app/[locale]/page.tsx
import {getTranslations} from 'next-intl/server';

export async function generateMetadata() {
  const t = await getTranslations('Metadata');
  return {title: t('title'), description: t('description')};
}

Spąstai — statinė forma. Agentai dažnai rašo export const metadata = {title: 'Dashboard'}, nes tai trumpiau, o konstanta negali kviesti vertimo funkcijos. Konvertuokite į funkcijos formą ir pridėkite tuos pačius raktus į katalogą visoms lokalėms. Tai ir paieškai matomas tekstas, todėl programos vertimas be metaduomenų vertimo reitingams daro mažai.

Kaip išversti Server Action ir validacijos pranešimus?

Perduokite lokalę veiksmui ir iškvieskite getTranslations nurodydami ir vardų sritį, ir tą lokalę. Server Action nežino, kokia puslapio kalba, todėl next-intl dokumentacija nurodo ją pateikti, pavyzdžiui, kaip argumentą:

'use server';
import {getTranslations} from 'next-intl/server';

export async function subscribe(locale: string, formData: FormData) {
  const t = await getTranslations({locale, namespace: 'Subscribe'});
  // ...validate, then return t('success') or t('invalidEmail')
}

Viena to paties dokumento pastaba: pagalvokite, kas nutinka, jei lankytojas gali pakeisti kalbą, kol ekrane rodomas veiksmo pranešimas. Kai URL yra [locale] segmentas, tai sutvarkoma automatiškai, nes pasikeičia maršrutas. Be jo pranešimą gali tekti išvalyti patiems, pavyzdžiui, komponentui nustačius key={locale}, kad jo būsena būtų atkurta.

Formų validacijai su Zod dokumentuotas būdas — klaidų žemėlapis (error map). Zod priima jį kiekvienam safeParse iškvietimui, o žemėlapis gali kviesti getTranslations. Sudėkite tai į vieną asinchroninę pagalbinę funkciją ir jos rezultatą perduokite kaip error parinktį kiekvienam parse iškvietimui. Tuomet jūsų schemose lieka taisyklės, o ne angliški sakiniai, ir dirbtinio intelekto sugeneruotos formos nebeįterpia "Invalid email" į latvišką puslapį.

Kaip išversti 404 ir klaidų puslapius?

Įdėkite not-found.tsx į app/[locale]/, tada pridėkite visa apimantį maršrutą, kad jis iš tikrųjų suveiktų. Next.js atvaizduoja tą failą, kai segmentas iškviečia notFound(), o nežinomas URL pats to nedaro:

// app/[locale]/[...rest]/page.tsx
import {notFound} from 'next/navigation';

export default function CatchAllPage() {
  notFound();
}

Užklausos, kurių next-intl middleware neatpažįsta, neturi lokalės išvis, todėl [locale] 404 joms niekada netaikomas. Dokumentacijos atsakymas — app/global-not-found.tsx, kurį Next.js dokumentacijoje įvardija kaip eksperimentinį ir kuris atvaizduoja savo html ir body. Nežinomai [locale] reikšmei dokumentacija nurodo iškviesti notFound(), paprastai i18n/request.ts.

error.tsx yra kitoks. Next.js reikalauja, kad jis būtų kliento komponentas, ir jis atvaizduojamas po jūsų maketu, todėl jam reikia NextIntlClientProvider, perduodančio bent Error vardų sritį. Perduokite tik tuos pranešimus, o ne visą katalogą:

// app/[locale]/layout.tsx (excerpt)
const messages = await getMessages();
// ...
<NextIntlClientProvider locale={locale} messages={pick(messages, 'Error')}>

Tada useTranslations('Error') veikia error.tsx viduje. Puslapis neapima global-error, todėl jei tokį failą turite, patikrinkite jį rankiniu būdu.

O kaip su bendrinimo paveikslėliais, manifest ir sitemap?

Kiekvienam jų reikia pateikti lokalę, nes jie gyvena už maketų medžio ribų. opengraph-image.tsx atveju nuskaitykite locale iš params ir iškvieskite getTranslations({locale, namespace}). Su pritaikytu localePrefix dokumentacija įspėja, kad sugeneruotas maršrutas gali tapti nepasiekiamas, nes Next.js nemato proxy (middleware) perrašymų; sprendimas — nustatyti matcher, kad praleistų kelius, besibaigiančius opengraph-image.

app/manifest.ts yra už [locale] ribų, todėl next-intl negali nustatyti lokalės iš kelio. Pasirinkite reprezentatyvią, dažniausiai numatytąją, ir perduokite ją aiškiai. sitemap.ts atveju pridėkite alternates.languages įrašus ir kiekvieną URL sudarykite naudodami asinchroninį getPathname({locale, href}) iš savo navigacijos modulio, priekyje pridėdami pagrindinį adresą (host). next-intl pagal numatytuosius nustatymus taip pat siunčia link atsako antraštę, skelbiančią kalbines versijas; svetainės struktūros failas (sitemap) yra tinkamas pasirinkimas, kai reikia kontroliuoti iš CMS gaunamus slug'us.

Kaip tvarkote Route Handlers?

Paimkite lokalę iš paieškos parametro, segmento ar accept-language antraštės, patikrinkite ją su hasLocale(routing.locales, locale) ir, jei nepavyko, grąžinkite 400. Tada iškvieskite getTranslations({locale, namespace}). Praleidus validaciją, į jūsų katalogo paiešką pakliūva savavališka eilutė.

Kaip rasti angliškus tekstus, kuriuos paliko jūsų agentas?

Vykdykite šias komandas projekto šaknyje. Jos sąmoningai apytikslės; tikslas — gauti sąrašą, kurį reikia peržiūrėti, o ne įvertį.

# 1. Static metadata that cannot be translated
grep -rn "export const metadata" app

# 2. Titles and descriptions already in generateMetadata
grep -rn "title:" app --include=page.tsx --include=layout.tsx

# 3. Server Actions with literal return messages
grep -rln "use server" app src 2>/dev/null | xargs grep -n "message:\|error:"

# 4. Zod schemas with inline messages
grep -rn "message:\s*['\"]" app src 2>/dev/null

# 5. 404 and error files, and whether a catch-all exists
ls app/\[locale\]/not-found.tsx app/\[locale\]/error.tsx "app/[locale]/[...rest]/page.tsx" 2>&1

Viskas, kas pirmuosiuose keturiuose rezultatuose yra paprastas angliškas literalas, turėtų atsidurti kataloge. Kodėl agentai vis prideda užkoduotas eilutes paaiškina, kodėl tai kartojasi: agentas seka matomą šabloną, o matomas šablonas — komponentas. Jei naudojate Copilot, čia taip pat galioja Copilot instrukcijų failų apribojimai.

Ką tai keičia jūsų kataloge?

Tai prideda raktų, o raktai — vieta, kur prasideda neatitikimai (drift). Kiekvienas aukščiau išvardytas punktas į katalogą atneša naujų įrašų, tokių kaip Metadata, Error, Subscribe ir validacijos pranešimai, ir kiekvienam reikia vertimo kiekvienai jūsų pateikiamai lokalei. Projektas, kuris komponentus išverčia vieną kartą, o vėliau prideda Server Action ar naują puslapio pavadinimą, yra tas pats projektas, apibūdintas straipsnyje apie tai, kodėl vertimų failai išsisinchronizuoja.

next-intl vykdymo metu pateikia vertimus, ir mes jo nekeičiame. globalize.now veikia vienu sluoksniu aukščiau: prijungiate saugyklą programoje, kodo bazė vieną kartą konvertuojama į katalogą, o push užduotys vėliau išverčia naujus katalogo vienetus, kai tik jie atsiranda, ir pateikia juos kaip pakeitimus jūsų peržiūrai. Next.js integracija aprašo sąranką, o ką darome ir ko neliečiame esamoje i18n sąrankoje aptaria atvejį, kai next-intl jau sujungtas rankiniu būdu.

Nuo ko pradėti

Paleiskite penkias grep komandas, konvertuokite visus statinius metadata eksportus, pridėkite visa apimantį maršrutą ir suteikite error.tsx jo teikėją (provider). Tada patikrinkite, ar kataloge yra naujos vardų sritys visose lokalėse. Jei išleidote AI sukurtą programą ir norite, kad konvertavimu bei vertimu rūpintųsi kas nors kitas, o ne jūs patys, vibe coders puslapis pateikia apžvalgą, kūrėjo dokumentacija aprašo agentų sąrankas, o kainos yra atskirame puslapyje.