@zoyth/simple-site-framework 1.0.0

package/docs/features/i18n/best-practices.md

@@ -0,0 +1,273 @@
+# i18n Best Practices
+
+Guidelines and patterns for effective internationalization.
+
+## Planning
+
+### Choose Locales Carefully
+
+- Start with languages your target audience actually speaks
+- Consider regional variants (en-US vs en-GB, fr-FR vs fr-CA)
+- Don't add languages you can't properly maintain
+
+### URL Structure
+
+Choose the right `localePrefix` mode:
+
+- **'as-needed'** (Recommended) - Clean default locale URLs, prefixed alternatives
+- **'always'** - Explicit language in all URLs, equal treatment
+- **'never'** - Simplest URLs, harder to share specific language links
+
+## Content Management
+
+### Keep Translations Complete
+
+Ensure all locales have translations:
+
+```typescript
+// ✅ Good - All locales covered
+const heading = {
+  en: 'Welcome',
+  fr: 'Bienvenue',
+  es: 'Bienvenido',
+};
+
+// ❌ Bad - Missing Spanish
+const heading = {
+  en: 'Welcome',
+  fr: 'Bienvenue',
+};
+```
+
+### Use TypeScript for Safety
+
+Define translation keys with types:
+
+```typescript
+type TranslationKeys = {
+  heading: LocalizedString;
+  description: LocalizedString;
+  cta: LocalizedString;
+};
+
+const translations: TranslationKeys = {
+  heading: { en: '...', fr: '...' },
+  description: { en: '...', fr: '...' },
+  cta: { en: '...', fr: '...' },
+};
+```
+
+### Organize Translations
+
+Group by feature or page:
+
+```
+config/translations/
+  ├── common.ts       # Shared across site
+  ├── navigation.ts   # Nav, footer links
+  ├── home.ts         # Homepage
+  ├── about.ts        # About page
+  └── services.ts     # Services page
+```
+
+## SEO Optimization
+
+### Use hreflang Tags
+
+Framework automatically generates hreflang tags via I18nMetaTags:
+
+```typescript
+import { I18nMetaTags } from '@zoyth/simple-site-framework/components';
+
+<I18nMetaTags
+  currentLocale={locale}
+  pathname={pathname}
+  baseUrl="https://example.com"
+/>
+```
+
+### Separate Sitemaps
+
+Generate sitemap per locale or include all in one with locale information.
+
+### Canonical URLs
+
+Set canonical URLs correctly for each locale variant.
+
+## Performance
+
+### Static Generation
+
+Pre-generate all locale variants:
+
+```typescript
+export async function generateStaticParams() {
+  const locales = ['en', 'fr', 'es'];
+
+  return locales.map(locale => ({ locale }));
+}
+```
+
+### Code Splitting
+
+Split translations by page to reduce bundle size:
+
+```typescript
+// Load translations on-demand
+const translations = await import(`./translations/${locale}.ts`);
+```
+
+### Avoid Over-Translation
+
+Don't translate:
+- Brand names
+- Product names (unless officially localized)
+- Technical terms without clear equivalents
+- Code examples
+
+## User Experience
+
+### Language Detection
+
+- Enable browser detection for first visit
+- Store preference in cookie
+- Allow manual override via LanguageSelector
+- Don't force redirects on every visit
+
+### Language Switcher Placement
+
+Place LanguageSelector where users expect it:
+- Header (top-right is common)
+- Footer
+- Mobile menu
+
+### Preserve Context
+
+When switching languages:
+```typescript
+// ✅ Good - Stay on same page
+/en/about → /fr/about
+
+// ❌ Bad - Go to homepage
+/en/about → /fr/
+```
+
+## Content Guidelines
+
+### Avoid Concatenation
+
+```typescript
+// ❌ Bad - Word order varies by language
+const message = `${userName} ${action} ${item}`;
+
+// ✅ Good - Full sentence per locale
+const message = {
+  en: `${userName} purchased ${item}`,
+  fr: `${userName} a acheté ${item}`,
+};
+```
+
+### Handle Pluralization
+
+Different languages have different plural rules:
+
+```typescript
+const itemCount = {
+  en: count === 1 ? '1 item' : `${count} items`,
+  fr: count <= 1 ? '1 article' : `${count} articles`,
+  ar: /* Arabic has 6 plural forms! */
+};
+```
+
+Consider using a library like `react-intl` for complex pluralization.
+
+### Date and Time Clarity
+
+Always use locale-aware formatting:
+
+```typescript
+import { formatDate } from '@zoyth/simple-site-framework/lib/i18n';
+
+formatDate(date, locale, { dateStyle: 'long' });
+```
+
+## Testing
+
+### Test All Locales
+
+- Navigate through site in each locale
+- Test forms and validation messages
+- Verify date/number formatting
+- Check layout with longer translations (German often longer than English)
+- Test RTL languages if supported
+
+### Automated Testing
+
+```typescript
+describe('i18n', () => {
+  const locales = ['en', 'fr', 'es'];
+
+  locales.forEach(locale => {
+    it(`renders ${locale} homepage`, () => {
+      // Test each locale
+    });
+  });
+});
+```
+
+## Maintenance
+
+### Version Control
+
+Track translations in git alongside code:
+- Easy to review changes
+- See translation history
+- Merge conflicts are manageable
+
+### Translation Workflow
+
+1. Develop feature in default locale
+2. Extract translatable strings
+3. Send to translators
+4. Review and integrate translations
+5. Test all locales
+6. Deploy
+
+### Professional Translation
+
+For production sites:
+- Use professional translators
+- Avoid machine translation for customer-facing content
+- Consider translation management platforms
+- Review translations in context
+
+## Common Pitfalls
+
+### Don't Assume English
+
+Framework doesn't assume English as default - you choose the default locale.
+
+### Don't Hardcode Strings
+
+```typescript
+// ❌ Bad
+<button>Click here</button>
+
+// ✅ Good
+<button>{buttonText}</button>
+```
+
+### Don't Skip Metadata
+
+Translate:
+- Page titles
+- Meta descriptions
+- Alt text for images
+- Form labels and errors
+- Button text
+
+## See Also
+
+- [Configuration](./configuration.md)
+- [Translations](./translations.md)
+- [SEO Guide](../seo/best-practices.md)

package/docs/features/i18n/configuration.md

@@ -0,0 +1,84 @@
+# i18n Configuration
+
+Configure internationalization settings for your multi-language site.
+
+## Configuration File
+
+Create your i18n configuration:
+
+```typescript
+// src/config/i18n.ts
+import type { I18nConfig } from '@zoyth/simple-site-framework/lib/i18n';
+
+export const i18nConfig: I18nConfig = {
+  locales: ['en', 'fr', 'es', 'de'],
+  defaultLocale: 'en',
+  localePrefix: 'as-needed',
+  localeDetection: true,
+  localeNames: {
+    en: 'English',
+    fr: 'Français',
+    es: 'Español',
+    de: 'Deutsch',
+  },
+  localeLabels: {
+    en: 'EN',
+    fr: 'FR',
+    es: 'ES',
+    de: 'DE',
+  },
+  rtlLocales: ['ar', 'he'],
+  localeCookie: {
+    name: 'NEXT_LOCALE',
+    maxAge: 365 * 24 * 60 * 60, // 1 year
+    sameSite: 'lax',
+  },
+};
+```
+
+## Configuration Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `locales` | `string[]` | Yes | Supported locale codes |
+| `defaultLocale` | `string` | Yes | Default/fallback locale |
+| `localePrefix` | `'always' \| 'as-needed' \| 'never'` | No | URL prefix mode (default: 'as-needed') |
+| `localeDetection` | `boolean` | No | Auto-detect from browser (default: true) |
+| `localeNames` | `Record<string, string>` | No | Full language names for UI |
+| `localeLabels` | `Record<string, string>` | No | Short labels for UI |
+| `rtlLocales` | `string[]` | No | Right-to-left locales |
+| `localeCookie` | `object` | No | Cookie configuration |
+
+## Locale Prefix Modes
+
+### 'always'
+All URLs include locale prefix:
+- `/en/about`
+- `/fr/about`
+
+### 'as-needed' (Default)
+Only non-default locales have prefix:
+- `/about` (default locale)
+- `/fr/about` (other locales)
+
+### 'never'
+No locale prefixes, detection via cookie/header:
+- `/about` (all languages)
+
+## Initialization
+
+Initialize config in your root layout:
+
+```typescript
+// app/[locale]/layout.tsx
+import { setI18nConfig } from '@zoyth/simple-site-framework/lib/i18n';
+import { i18nConfig } from '../../config/i18n';
+
+setI18nConfig(i18nConfig);
+```
+
+## See Also
+
+- [Routing](./routing.md)
+- [Locale Detection](./locale-detection.md)
+- [Configuration Guide](../../i18n/CONFIGURATION.md)

package/docs/features/i18n/formatting.md

@@ -0,0 +1,133 @@
+# Locale-Aware Formatting
+
+Format dates, numbers, and currency based on user's locale.
+
+## Date Formatting
+
+Format dates according to locale conventions:
+
+```typescript
+import { formatDate } from '@zoyth/simple-site-framework/lib/i18n';
+
+const date = new Date('2024-12-25');
+
+formatDate(date, 'en'); // "12/25/2024"
+formatDate(date, 'fr'); // "25/12/2024"
+formatDate(date, 'de'); // "25.12.2024"
+
+// With options
+formatDate(date, 'en', {
+  dateStyle: 'long',
+}); // "December 25, 2024"
+
+formatDate(date, 'fr', {
+  dateStyle: 'long',
+}); // "25 décembre 2024"
+```
+
+## Number Formatting
+
+Format numbers with locale-specific separators:
+
+```typescript
+import { formatNumber } from '@zoyth/simple-site-framework/lib/i18n';
+
+const number = 1234567.89;
+
+formatNumber(number, 'en'); // "1,234,567.89"
+formatNumber(number, 'fr'); // "1 234 567,89"
+formatNumber(number, 'de'); // "1.234.567,89"
+
+// With options
+formatNumber(number, 'en', {
+  minimumFractionDigits: 2,
+  maximumFractionDigits: 2,
+}); // "1,234,567.89"
+```
+
+## Currency Formatting
+
+Format currency amounts:
+
+```typescript
+import { formatCurrency } from '@zoyth/simple-site-framework/lib/i18n';
+
+const amount = 1234.56;
+
+formatCurrency(amount, 'en', 'USD'); // "$1,234.56"
+formatCurrency(amount, 'fr', 'EUR'); // "1 234,56 €"
+formatCurrency(amount, 'de', 'EUR'); // "1.234,56 €"
+formatCurrency(amount, 'ja', 'JPY'); // "¥1,235"
+
+// With options
+formatCurrency(amount, 'en', 'USD', {
+  currencyDisplay: 'name',
+}); // "1,234.56 US dollars"
+```
+
+## Relative Time Formatting
+
+Format relative time periods:
+
+```typescript
+import { formatRelativeTime } from '@zoyth/simple-site-framework/lib/i18n';
+
+formatRelativeTime(-1, 'day', 'en'); // "1 day ago"
+formatRelativeTime(-1, 'day', 'fr'); // "il y a 1 jour"
+formatRelativeTime(2, 'week', 'en'); // "in 2 weeks"
+formatRelativeTime(2, 'week', 'es'); // "dentro de 2 semanas"
+```
+
+## List Formatting
+
+Format lists according to locale:
+
+```typescript
+const items = ['Apple', 'Banana', 'Orange'];
+
+new Intl.ListFormat('en').format(items);
+// "Apple, Banana, and Orange"
+
+new Intl.ListFormat('fr').format(items);
+// "Apple, Banana et Orange"
+
+new Intl.ListFormat('es', { type: 'disjunction' }).format(items);
+// "Apple, Banana o Orange"
+```
+
+## Intl API Reference
+
+All formatters use the native JavaScript Intl API:
+
+- `Intl.DateTimeFormat` - Date/time formatting
+- `Intl.NumberFormat` - Number/currency formatting
+- `Intl.RelativeTimeFormat` - Relative time formatting
+- `Intl.ListFormat` - List formatting
+
+## Usage in Components
+
+Example with formatted dates:
+
+```typescript
+import { formatDate } from '@zoyth/simple-site-framework/lib/i18n';
+
+export function BlogPost({ date, locale }: Props) {
+  const formattedDate = formatDate(date, locale, {
+    dateStyle: 'long',
+  });
+
+  return (
+    <article>
+      <time dateTime={date.toISOString()}>
+        {formattedDate}
+      </time>
+    </article>
+  );
+}
+```
+
+## See Also
+
+- [Translations](./translations.md)
+- [Configuration](./configuration.md)
+- [MDN Intl Documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl)

package/docs/features/i18n/locale-detection.md

@@ -0,0 +1,122 @@
+# Locale Detection
+
+Automatic language detection from browser, cookies, and URL.
+
+## Detection Strategy
+
+The middleware detects locale in this order:
+
+1. **URL Parameter** - Explicit locale in path (`/fr/about`)
+2. **Cookie** - Previously selected locale (`NEXT_LOCALE` cookie)
+3. **Accept-Language Header** - Browser language preference
+4. **Default Locale** - Configured fallback
+
+## Browser Detection
+
+Enable in configuration:
+
+```typescript
+export const i18nConfig = {
+  locales: ['en', 'fr', 'es', 'de'],
+  defaultLocale: 'en',
+  localeDetection: true, // Enable browser detection
+};
+```
+
+### Accept-Language Header
+
+The framework parses the `Accept-Language` header:
+
+```
+Accept-Language: fr-CA,fr;q=0.9,en;q=0.8,de;q=0.5
+```
+
+Matches:
+1. Exact match: `fr-CA` → `fr`
+2. Language prefix: `fr` → `fr`
+3. Quality values (q) determine priority
+4. Fallback to default if no match
+
+## Cookie Persistence
+
+When user selects a language, it's stored in a cookie:
+
+```typescript
+// Cookie configuration
+localeCookie: {
+  name: 'NEXT_LOCALE',
+  maxAge: 365 * 24 * 60 * 60, // 1 year
+  sameSite: 'lax',
+}
+```
+
+Cookie persists across:
+- Browser sessions
+- Different pages
+- Returning visits
+
+## Manual Cookie Setting
+
+Set locale cookie programmatically:
+
+```typescript
+import { setLocaleCookie } from '@zoyth/simple-site-framework/lib/i18n';
+
+function handleLanguageChange(locale: string) {
+  setLocaleCookie(locale);
+  // Navigate to new locale...
+}
+```
+
+## Detection Flow
+
+```
+User visits site
+     ↓
+Check URL for locale
+     ↓ (not found)
+Check NEXT_LOCALE cookie
+     ↓ (not found)
+Parse Accept-Language header
+     ↓ (no match)
+Use default locale
+     ↓
+Redirect if needed (based on localePrefix mode)
+     ↓
+Set cookie with detected locale
+```
+
+## Disabling Detection
+
+Disable automatic browser detection:
+
+```typescript
+export const i18nConfig = {
+  locales: ['en', 'fr'],
+  defaultLocale: 'en',
+  localeDetection: false, // Disable
+};
+```
+
+Users must explicitly select language via LanguageSelector.
+
+## Testing Detection
+
+Test different scenarios:
+
+```bash
+# Test with specific Accept-Language
+curl -H "Accept-Language: fr-FR,fr;q=0.9" http://localhost:3000/
+
+# Test with cookie
+curl -H "Cookie: NEXT_LOCALE=es" http://localhost:3000/
+
+# Test URL override
+curl http://localhost:3000/de/
+```
+
+## See Also
+
+- [Routing](./routing.md)
+- [Configuration](./configuration.md)
+- [LanguageSelector Component](../../components/layout/LanguageSelector.md)

package/docs/features/i18n/routing.md

@@ -0,0 +1,99 @@
+# Locale Routing
+
+URL routing and navigation for multi-language sites.
+
+## Route Structure
+
+Based on your `localePrefix` configuration:
+
+### 'as-needed' Mode (Default)
+```
+/                    → Default locale homepage
+/about              → Default locale about page
+/fr/                → French homepage
+/fr/about           → French about page
+```
+
+### 'always' Mode
+```
+/en/                → English homepage
+/en/about           → English about page
+/fr/                → French homepage
+/fr/about           → French about page
+```
+
+### 'never' Mode
+```
+/                    → Homepage (locale from cookie/header)
+/about              → About page (locale from cookie/header)
+```
+
+## Middleware Setup
+
+Create middleware for automatic routing:
+
+```typescript
+// src/middleware.ts
+import { createI18nMiddleware } from '@zoyth/simple-site-framework/lib/i18n';
+import { i18nConfig } from './config/i18n';
+
+export default createI18nMiddleware(i18nConfig);
+
+export const config = {
+  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
+};
+```
+
+## Navigation
+
+### Using Next.js Link
+
+```typescript
+import Link from 'next/link';
+
+// Same-locale navigation
+<Link href="/about">About</Link>
+
+// Cross-locale navigation
+<Link href="/fr/about">À propos</Link>
+```
+
+### Language Switching
+
+Use the LanguageSelector component:
+
+```typescript
+import { LanguageSelector } from '@zoyth/simple-site-framework/components';
+
+<LanguageSelector currentLocale={locale} />
+```
+
+## Dynamic Routes
+
+Handle dynamic routes with locale parameter:
+
+```typescript
+// app/[locale]/blog/[slug]/page.tsx
+export async function generateStaticParams() {
+  const locales = ['en', 'fr'];
+  const slugs = ['post-1', 'post-2'];
+
+  return locales.flatMap(locale =>
+    slugs.map(slug => ({ locale, slug }))
+  );
+}
+```
+
+## Redirects
+
+The middleware automatically:
+1. Detects missing locale in URL
+2. Determines user's preferred locale
+3. Redirects to appropriate localized URL
+4. Sets locale cookie for persistence
+
+## See Also
+
+- [Configuration](./configuration.md)
+- [Locale Detection](./locale-detection.md)
+- [Routing Examples](../../i18n/EXAMPLES.md)