Building a Premium Bilingual Portfolio with Next.js

The Challenge

Building a developer portfolio that truly stands out requires more than just listing projects. It needs to reflect your technical capabilities while providing an exceptional user experience. For this portfolio, the goals were ambitious:

• Bilingual support (English/Persian) with proper RTL handling
• Restrained systems-documentation UI that feels modern yet accessible
• Production-oriented infrastructure with Docker builds and CI validation
• Performance optimization without sacrificing visual appeal

Tech Stack

Core Framework

• Next.js 15 with App Router and server components
• React 19 for the component layer
• Tailwind CSS for utility-first styling with custom design tokens

Internationalization

• next-intl for type-safe translations
• Custom RTL utilities for Persian layout
• Locale-aware date formatting

Infrastructure

• Docker multi-stage builds for the production image
• Docker Compose for local development and production
• GitHub Actions for lint, application-build, and production-image validation; the workflow does not publish or deploy the image

Key Features Implemented

1. Systems-documentation design system

The UI uses solid reading surfaces and reserves restrained translucency for navigation and small proof callouts:

.systems-panel {
  background: #0D1A2B;
  border: 1px solid rgba(148, 163, 184, 0.18);
}

Interactive states use small position changes and visible focus rings:

.systems-panel:focus-within {
  border-color: rgba(34, 211, 238, 0.65);
}

2. RTL-First Approach

Instead of treating RTL as an afterthought, the design system was built with bidirectional support from the start:

• Tailwind's rtl: variants for directional styles
• Logical properties (ms-4, me-4) instead of physical (ml-4, mr-4)
• Mirrored gradients and animations for Persian

3. Performance Optimizations

• Dynamic imports for heavy components (Lottie animations, Marquee)
• Image optimization with Next.js Image component
• Font subsetting for Persian typography
• Staggered animations using CSS animation-delay

4. Blog System

The blog section features:

• Responsive grid layout (1→2→3 columns)
• Tag-based filtering with search
• Reading time calculation
• Locale-aware relative dates

Lessons Learned

1. Cache invalidation is hard - Next.js build cache required multiple full rebuilds during development
2. RTL is more than text direction - Shadows, gradients, and animations all need consideration
3. Accessibility matters - Focus states, keyboard navigation, and contrast ratios improve UX for everyone

Verification boundaries

• Blog posts are stored as structured JSON content; this article does not claim MDX support.
• The repository includes a local viewport smoke-check across selected routes and widths. It captures two mobile screenshots, but it does not compare them with approved baselines, so it is not automated visual regression testing.
• The checked workflow runs lint and application builds and validates a production Docker image. It does not publish that image or automate a production deployment.
• No Web Vitals monitoring integration is claimed here.