---

TODO: Project Name (AOSSIE Webpage Starter)

TODO: Project Description.

A high-performance, developer-friendly webpage built on Next.js 16 (App Router), React 19, Tailwind CSS v4, and pre-configured for Internationalization (i18n) and Localization (l10n) using next-intl.

---

🚀 Project's Features

TODO: List your main features here:

• Feature 1: Description
• Feature 2: Description
• Feature 3: Description
• Feature 4: Description

---

💻 Tech Stack

TODO: Update based on your project

---

📋 Project Maturity & TODO Checklist

In the checklist below, mark the items that have been completed for your project:

• The project has a logo (public/brand/icons/aossie_logo.svg).
• The project has a favicon (public/brand/icons/favicon.ico).
• The web frontend:
  • Has proper title and metadata.
  • Has proper open graph metadata, to ensure that it is shown well when shared in social media.
  • Has a footer and header with AOSSIE logos and social handles.
  • Uses React Server Components by default, introducing Client Components ("use client") only when interactivity or client hooks are required.
  • Is deployed to GitHub Pages via a GitHub Workflow (.github/workflows/nextjs.yml).
  • Has automated CI build and lint validation (.github/workflows/ci.yml).
  • Has CodeRabbit automated AI code review (.coderabbit.yml).
  • Has open-source legal compliance (DCO.md, COPYRIGHT.md, Contributors.md).

---

🚀 Website's Features

• Next.js 16 & React 19: Utilizing the latest Server Components, Client Actions, and async routing paradigms.
• Tailwind CSS v4: Modern utility-first styling with native CSS variables and streamlined postcss integrations.
• Dual Theme System: Flash-free light, dark, and system-preferred themes using next-themes and Tailwind CSS v4 custom variants.
• Robust i18n & l10n: Deeply integrated multi-language support:
  • Automatic locale detection based on browser preferences.
  • Subpath routing (e.g., /hi for Hindi, and /en for English as default) with clean URL prefixing.
  • Sleek, interactive language switcher client component.
  • Zero-bundle-size footprint for static translations using Server Components & Client useTranslations.
• Developer Experience: Strict TypeScript compilation and ES Lint setup.
• Application Control Compatibility: Configured with manual Webpack & Turbopack alias resolution to bypass restrictive execution environments blocking native binary compiles.
• Open-Source Governance & CI/CD: Integrated GitHub Actions workflows (ci.yml, nextjs.yml, label-merge-conflicts.yml), .coderabbit.yml, and DCO.md legal documentation.
• AI Agent Pairing Ready: Includes AGENTS.md and CLAUDE.md to guide AI development agents.

---

📂 Project Structure

Here is a breakdown of the key i18n directories and files:

├── .github/
│   └── workflows/          # GitHub Actions (CI, GitHub Pages deployment, merge conflict checks)
├── next.config.ts          # Alias-wrapped Next configuration
├── public/                 # Static assets, robots.txt, assetlinks.json, llms.txt
│   ├── .well-known/
│   ├── llms.txt
│   ├── robots.txt
│   └── brand/
│       ├── Brand.md            # Official AOSSIE brand guidelines document
│       └── icons/             
│           ├── aossie_logo.svg              # AOSSIE Vector logo
│           ├── stability_nexus_logo.svg     # Vector logo
│           └── favicon.ico                  # Browser tab icon
├── src/
│   ├── config/
│   │   └── languages.ts        # Central registry of supported languages & locales
│   ├── i18n/
│   │   ├── routing.ts          # Core i18n routing parameters (locales, defaults)
│   │   ├── request.ts          # Server-side translation dictionary loading configuration
│   │   ├── metadata.ts         # Configuration data, SEO values, or reflection data for a project
│   │   └── navigation.ts       # Type-safe navigation helpers (Link, useRouter, etc.)
│   ├── messages/
│   │   ├── en.json             # English translation dictionary
│   │   └── hi.json             # Hindi translation dictionary
│   ├── app/
│   │   ├── page.tsx            # Root page redirecting to default locale (/en) for static export
│   │   ├── sitemap.ts          # Statically generated localized sitemaps
│   │   └── [locale]/           # Localized route group
│   │       ├── layout.tsx      # Multi-lingual layout injecting client context & translations
│   │       ├── page.tsx        # Localized Landing Page ("use client")
│   │       ├── globals.css     # Global styles for the app segment
│   │       ├── error.tsx       # Localized Error Boundary page fallback
│   │       └── not-found.tsx   # Localized 404 page fallback
│   └── components/
│       ├── LanguageSwitcher.tsx # Dropdown element to switch interface locales interactively
│       ├── ThemeToggle.tsx      # Multi-state theme switch with micro-animations
│       └── providers/
│           ├── theme-provider.tsx # Next-themes client wrapper component
│           └── lenis-provider.tsx # Lenis smooth scrolling provider wrapper
├── .coderabbit.yml         # Automated AI Code Review configuration
├── COPYRIGHT.md            # Copyright terms
├── Contributors.md         # Project contributors list
└── DCO.md                  # Developer Certificate of Origin

---

🛠️ Usage Guide

1. Adding a New Language

To add support for a new language (e.g., French - fr):

1. Register the language: Open src/config/languages.ts and add your new language to the languages array:

   export const languages: Language[] = [
     { code: 'en', name: 'English', localName: 'English' },
     { code: 'hi', name: 'Hindi', localName: 'हिन्दी' },
     { code: 'fr', name: 'French', localName: 'Français' } // Add this line
   ];

2. Create the translation catalog: Under src/messages/, create a new file named fr.json:

   {
     "Home": {
       "heading": "Bienvenue sur AOSSIE Webpage Starter"
     }
   }

3. That's it! Next.js and next-intl will automatically register the locale, add it to the routing tables, and handle redirection for visitors matching fr browser preferences.

---

2. Translating Text in Pages and Components

Server Components (Recommended for Static Content)

By default, server components can load translations statically without shipping translation JSONs to the client bundle:

import { useTranslations } from 'next-intl';

export default function Section() {
  const t = useTranslations('Home');
  return <h1>{t('heading')}</h1>;
}

Client Components

If your component uses React hooks (e.g., useState), define it with "use client" and import from next-intl:

"use client";

import { useTranslations } from 'next-intl';

export default function InteractiveButton() {
  const t = useTranslations('Home');
  return <button onClick={() => alert('Clicked!')}>{t('heading')}</button>;
}

---

3. Navigation Helpers

When navigating between routes, always use the locale-aware navigation helpers imported from src/i18n/navigation.ts instead of standard next/link or next/navigation:

import { Link } from '../../i18n/navigation';

// Will automatically resolve to /en/about or /hi/about based on active locale
<Link href="/about">About Us</Link>

For programmatic router navigation:

import { useRouter, usePathname } from '../../i18n/navigation';

const router = useRouter();
const pathname = usePathname();

// Switch active locale on current page
router.replace(pathname, { locale: 'hi' });

---

4. Theme Configuration & Dual Theme Support

The starter kit uses next-themes combined with Tailwind CSS v4's class-based custom variants to provide a responsive and flash-free theme experience.

Customizing Colors

Preferred Method

Tailwind v4 is configured via CSS custom properties in src/app/[locale]/globals.css. To adjust the default light and dark theme background or text colors, edit the root variables:

:root {
  --background: #ffffff; /* Light theme background */
  --foreground: #121212; /* Light theme text */
}

.dark {
  --background: #0a0a0a; /* Dark theme background */
  --foreground: #f4f4f5; /* Dark theme text */
}

Using Theme Classes

To create element styles that adapt automatically to the user's selected theme, use semantic utility tokens instead of inline dark: utilities:

<div className="bg-background-secondary text-foreground-primary border border-border-default">
  This card automatically transitions colors across light and dark themes.
</div>

---

5. Smooth Scrolling (Lenis)

The starter repository integrates the lenis library to provide smooth, high-performance inertial scrolling across all browsers.

Customizing Lenis Options

To configure scroll parameters (e.g., dampening velocity, custom scroll durations, or scroll directions), update the parameters passed to the ReactLenis component in lenis-provider.tsx:

<ReactLenis root options={{ lerp: 0.1, duration: 1.5, smoothWheel: true }}>
  {children}
</ReactLenis>

To access the active Lenis instance or bind custom scroll animations programmatically in your page components, use the useLenis hook:

import { useLenis } from 'lenis/react';

const lenis = useLenis(({ scroll, limit, velocity, direction }) => {
  // Bind your scroll logic or animation timelines here
});

---

⚡ Development and Deployment

Getting Started

Install the project dependencies:

npm install

Start the development server:

npm run dev

Open http://localhost:3000 to view it. The application will automatically detect your browser's language preferences and route you to /hi for Hindi or /en for English (the default locale).

Building for Production (Static Export)

Compile and export the project into static HTML/CSS/JS assets for hosting on GitHub Pages:

npm run build

This generates an optimized static export in the ./out directory, fully configured for client-side rendering and hosting on GitHub Pages.

---

⚙️ Initial Project Setup Checklist

When bootstrapping a new project from this starter repository, complete the following TODO setup checklist to align the repository with your project's branding, metadata, AI agent guidelines, and hosting configurations:

1. Project Identity & Header Details

• Project Title & Logo (README.md): Update the main project header logo (public/brand/icons/todo-project-logo.svg), title <h1>TODO: Project Name</h1>, project description, feature list, and tech stack.
• AI Agent Context (AGENTS.md): Replace # TODO: Project Title and add project-specific directives and rules for AI coding agents.
• LLM Manifest (public/llms.txt): Update # TODO: Project Title in the root LLM crawler policy.
• Community & Social Links (Contributors.md): Replace the [TODO Channel](TODO) placeholder with your project's Discord, Telegram, or chat channel link.

2. Domain Names & Search Engine Crawlers

• Sitemap Generator (src/app/sitemap.ts): Replace the default fallback domain https://project.aossie.org with your project's production domain in the source code or set the NEXT_PUBLIC_SITE_URL environment variable at build time (e.g., in .github/workflows/nextjs.yml or build pipeline settings).
• Search Crawler Rules (public/robots.txt): Replace the sitemap URL placeholder domain TODO 'project.aossie.org' with your actual production domain.

3. Branding Guidelines & Assets

• Logo & Favicons (public/brand/icons/): Replace aossie_logo.svg and favicon.ico with your organization's custom logos.
• Brand Documentation (public/brand/Brand.md): Document your custom color hex codes, typography selections, and asset paths here to guide future developers and AI coding agents.

4. SEO & i18n Localization Metadata

• Schema.org JSON-LD (src/app/[locale]/page.tsx): Locate the jsonLd object inside the Home component. Update the publisher.name, publisher.url, and publisher.logo fields from TODO placeholders to your project metadata.
• Translation Catalogs (src/messages/en.json, src/messages/hi.json): Update the heading, metaTitle, and metaDescription keys with your project's localized titles and descriptions.

5. Mobile & AI Platform Configurations

• Android App Links (public/.well-known/assetlinks.json): Update the package name TODO:org.aossie.starter and insert your Android application certificate SHA-256 fingerprint (TODO:...).
• AI Agent Plugins (public/.well-known/ai-plugin.json): Replace all TODO placeholders for name_for_human, name_for_model, description_for_human, description_for_model, host URLs, contact emails, and legal info links.

---

🤝 Contributing

We welcome contributions of all kinds! To contribute:

1. Fork the repository and create your feature branch (git checkout -b feature/AmazingFeature).
2. Commit your changes (git commit -m 'Add some AmazingFeature').
3. Ensure code quality:
   • npm run lint
   • npm run build
4. Push your branch (git push origin feature/AmazingFeature).
5. Open a Pull Request for review.

© 2026 AOSSIE. Released under the Apache 2.0 / Open Source License.