AgentRules.org
RulesStacksClientsAuditorPrunerSelf-HealRFCsBenchmarkCLICI/CDAuthorsSubmit
This specification is maintained by the AgentRules Working Group. Have enhancements or want to claim maintainership?Submit Specification →
frontendhigh PriorityID: next-intl-app-router-localization

Next.js 15 App Router & next-intl Dynamic Localization Architecture

Enterprise internationalization standard for Next.js 15 App Router. Mandates server-side translation resolution via next-intl, type-safe translation keys, clean routing middleware with alternate hreflang tags, and zero client bundle bloat from translation dictionaries.

Prohibited Anti-Pattern: AI passes massive monolithic JSON translation dictionaries to client-side Context providers, bloating client bundle size and destroying Next.js 15 SSR caching.

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: Next.js 15 App Router & next-intl Dynamic Localization Architecture - Enterprise internationalization standard for Next.js 15 App Router. Mandates server-side translation resolution via next-intl, type-safe translation keys, clean routing middleware with alternate hreflang tags, and zero client bundle bloat from translation dictionaries.
globs: **/messages/*.json, **/middleware.ts, **/i18n.ts, **/app/[locale]/**/*.tsx
alwaysApply: false
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/next-intl-app-router-localization"
---

# Next.js 15 App Router & next-intl Dynamic Localization Architecture

> **Severity**: HIGH | **Category**: frontend
> **Anti-Pattern Warning**: AI passes massive monolithic JSON translation dictionaries to client-side Context providers, bloating client bundle size and destroying Next.js 15 SSR caching.

## System Constraints
You are a Senior Next.js 15 and Internationalization Specialist. When building multilingual applications with Next.js 15 and next-intl, resolve messages directly in Server Components using getTranslations(). Never ship raw global JSON translation bundles to the client browser.

## Strict Guidelines
- Use next-intl getTranslations() in Server Components for zero-bundle-overhead translations.
- Configure proxy middleware (createMiddleware) for type-safe locale prefixing and automated Accept-Language content negotiation.
- Always generate canonical alternate links with hreflang attributes in generateMetadata() for multi-locale SEO discovery.
- Enforce strict TypeScript compiler verification for translation key namespaces (IntlMessages declaration).
- Isolate client-side translations to dynamic leaf components using useTranslations() only when interactive client re-renders are strictly required.

## Bad vs Good Implementations
### Server Component Translation with next-intl and SEO Metadata

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Importing full JSON localization dictionaries into client components embeds hundreds of kilobytes of unused translation strings into the initial client JavaScript bundle, severely slowing down mobile LCP.
```typescript
// FATAL: Shipping all language dictionaries to client via massive JSON context
'use client';
import { createContext, useContext } from 'react';
import enDict from '@/locales/en.json'; // Bundles 500KB of JSON into client JS!
import zhDict from '@/locales/zh.json';

const I18nContext = createContext({ en: enDict, zh: zhDict });
export function BadTranslate({ k }: { k: string }) {
  const dicts = useContext(I18nContext);
  return <span>{dicts.en[k]}</span>;
}
```

#### Production Standard (Correct)
> **Standard**: Leverages Next.js 15 asynchronous params with next-intl server-side getTranslations(). Translations are resolved on the server and streamed as raw HTML, adding 0 bytes of JSON dictionary bloat to the client browser bundle.
```typescript
// app/[locale]/page.tsx - Zero-Client-Bundle Next.js 15 Server Component
import { getTranslations, setRequestLocale } from 'next-intl/server';
import type { Metadata } from 'next';

interface PageProps {
  params: Promise<{ locale: string }>;
}

export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
  const { locale } = await params;
  const t = await getTranslations({ locale, namespace: 'Metadata' });
  return {
    title: t('title'),
    description: t('description'),
    alternates: {
      languages: {
        en: '/en',
        zh: '/zh',
        ja: '/ja',
      },
    },
  };
}

export default async function HomePage({ params }: PageProps) {
  const { locale } = await params;
  setRequestLocale(locale);
  const t = await getTranslations('Home');

  return (
    <main className='max-w-4xl mx-auto px-4 py-8'>
      <h1 className='text-3xl font-bold'>{t('welcome')}</h1>
      <p className='text-slate-600'>{t('description')}</p>
    </main>
  );
}
```
Recommended MCP Servers (mcp-serverlist.com)

Equip agent with system tools to verify code for this stack.

i18n Localization Linter MCP
Scans React components for unextracted raw strings and detects missing localized keys across JSON files.
Recommended Agent Skills (askills.dev)

Ready-to-use executable skill functions tailored to this stack.

askills: next-intl Key Synchronizer
Maintains strict schema parity across locale files and validates hreflang SEO tags.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: Next.js 15 App Router & next-intl Dynamic Localization Architecture

Next.js 15 App Router & next-intl Dynamic Localization Architecture defines an industrial-grade behavioral standard for frontend engineering. Enterprise internationalization standard for Next.js 15 App Router. Mandates server-side translation resolution via next-intl, type-safe translation keys, clean routing middleware with alternate hreflang tags, and zero client bundle bloat from translation dictionaries. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: AI passes massive monolithic JSON translation dictionaries to client-side Context providers, bloating client bundle size and destroying Next.js 15 SSR caching. Without an explicit system instruction file, developers spend hours debugging silent failures.
Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure ModeAI Symptom (The Anti-Pattern)SeverityProduction Impact & Remedy
AI Hallucination & Deprecation DriftAI passes massive monolithic JSON translation dictionaries to client-side Context providers, bloating client bundle size and destroying Next.js 15 SSR caching.High
Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production.
Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture InconsistencyAI assistants produce mixed paradigms across files, creating fragmented codebase conventions.Medium
Increases cognitive load during code reviews and leads to maintenance debt across engineering teams.
Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.
Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

1

Use next-intl getTranslations() in Server Components for zero-bundle-overhead translations.

Use next-intl getTranslations() in Server Components for zero-bundle-overhead translations.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
2

Configure proxy middleware (createMiddleware) for type-safe locale prefixing and automated Accept-Language content negotiation.

Configure proxy middleware (createMiddleware) for type-safe locale prefixing and automated Accept-Language content negotiation.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
3

Always generate canonical alternate links with hreflang attributes in generateMetadata() for multi-locale SEO discovery.

Always generate canonical alternate links with hreflang attributes in generateMetadata() for multi-locale SEO discovery.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
4

Enforce strict TypeScript compiler verification for translation key namespaces (IntlMessages declaration).

Enforce strict TypeScript compiler verification for translation key namespaces (IntlMessages declaration).

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
5

Isolate client-side translations to dynamic leaf components using useTranslations() only when interactive client re-renders are strictly required.

Isolate client-side translations to dynamic leaf components using useTranslations() only when interactive client re-renders are strictly required.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
Technical Questions & Answers

Frequently Asked Technical Questions

Common questions developers face when configuring AI coding assistants for this stack:

Q:Why is Next.js 15 App Router & next-intl Dynamic Localization Architecture critical for AI coding assistants?

Enterprise internationalization standard for Next.js 15 App Router. Mandates server-side translation resolution via next-intl, type-safe translation keys, clean routing middleware with alternate hreflang tags, and zero client bundle bloat from translation dictionaries. Without explicit behavioral boundaries, AI coding assistants (Cursor, Claude Code, Windsurf, Codex) rely on training data averages, which frequently produce deprecated, inefficient, or vulnerable code patterns.

Q:How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (AI passes massive monolithic JSON translation dictionaries to client-side Context providers, bloating client bundle size and destroying Next.js 15 SSR caching.) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q:Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q:Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

Open Specification · CC BY 4.0·Free for Personal, Team & Commercial In-Repo Use

Citation & Open Source Attribution Guidelines

This specification is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0). You are completely free to adapt and share this rule in your workspace. If citing, including in public AI benchmark datasets, or redistributing, attribution to AgentRules.org is required.

Related FRONTEND Rules

View all rules →
frontend
119

SolidStart 1.0 Server Functions & Async Boundaries Production Standard

SolidStart 1.0 relies on the Vinxi bundler to split `server$` closures into independent HTTP POST RPC endpoints. Direct lexical closure over client signals within `server$` scopes or failure to demarcate async boundaries with `<Suspense>` causes silent serialization failures, client-bundle secret leaks, and SSR hydration mismatches. Enforcing strict parameter passing, runtime input validation, and Solid async primitives maintains security and fine-grained reactivity across network boundaries.

frontend
119

Astro 5 Actions & Content Layer Production Standard

Enforces strict type safety and architectural correctness for Astro 5 Server Actions and the zero-waterfall Content Layer API. Prevents runtime contract mismatches, hydration mismatches, and unhandled mutation exceptions across dynamic and prerendered boundaries. Failure to follow these patterns leads to silent data fetching waterfalls, build-time cache corruptions, and unhandled server action exceptions.

frontend
51

Nuxt 4 Nitro Server Engine & Shared Directory Production Standard

Nuxt 4 enforces strict boundary segregation between client UI in the app/ directory, backend endpoints in server/, and universal contracts in shared/. Violating cross-boundary isolation or maintaining module-scoped state in Nitro server handlers causes catastrophic cross-request data corruption and hydration mismatches under concurrent production traffic. Architects must enforce request-isolated H3 event contexts, universal serialization schemas, and strict path-alias boundaries.

1 Rule in Stack

Next.js