next-app-i18n-starter: Instructions file for Codex

Repository instructions

These instructions apply to coding assistants of any model or editor. Read this file first, then read the nearest AGENTS.md for the files you change. User instructions take priority. When documentation conflicts with the code or configuration, verify the behavior and update the stale documentation in the same change.

Project facts

• Next.js 16 App Router, React 19, next-intl 4, Tailwind CSS 4, and shadcn/ui.
• Bun is the package manager; bun.lock is the lockfile. Node.js 24 is required.
• The app supports English, Arabic, Chinese, Spanish, and Japanese. English is the default locale.

Shared rules

• Keep changes focused on the requested outcome. Inspect the relevant code and current Git status first, reuse existing patterns, and avoid dependencies or abstractions without a concrete need.
• Protect credentials and user data. Never read, edit, or commit .env files. Put new variable names and safe example values in .env.example; never place real credentials there.
• Use @/i18n/navigation for links and navigation that should preserve locale. Use Next.js navigation APIs directly when the operation is not locale-aware, such as notFound().
• dictionary/en.json defines translation message types. Add or rename message keys in every dictionary/*.json file. Keep locale copy accurate and have fluent speakers review production translations.
• Locale routes live under src/app/[locale]/. Validate route locales with hasLocale before using them. The locale reaches server code through next/root-params in src/i18n/request.ts, so pages do not call setRequestLocale, which next-intl deprecated in 4.13.5.
• Build locale URLs with helpers from src/lib/site.ts. Routing uses localePrefix: "as-needed": English uses /, and other locales use /{locale}. Automatic locale detection is disabled so cookies and browser language do not redirect the default URL.
• Use createLocalizedMetadata for page metadata and keep canonical, alternate-language, sitemap, and Open Graph URLs aligned. Follow SEO.md and the nextjs-seo-* skills in .agents/skills/. Add structured data only when it describes visible page content; render JSON-LD in a Server Component and escape < in its serialized value.
• Prefer Server Components. Add "use client" only for client state, event handlers, or browser APIs. Theme initialization uses the existing cookie-based SSR implementation.
• Follow the component, styling, accessibility, and RTL conventions in src/components/AGENTS.md when changing UI.
• Keep documentation and instructions consistent with the implementation when changing a convention, route, locale, or environment variable.