@mars-stack/cli 0.2.0 → 1.0.2

package/template/.cursor/skills/configure-i18n/SKILL.md

@@ -0,0 +1,518 @@
+# Skill: Configure Internationalization (i18n)
+
+Set up multi-language support in a MARS application using `next-intl` with the App Router, including locale routing, translation files, and RTL support.
+
+## When to Use
+
+Use this skill when the user asks to add translations, multi-language support, internationalization, i18n, localization, l10n, or locale switching.
+
+## Prerequisites
+
+- Next.js App Router (MARS default)
+- `appConfig.features.i18n` set to `true` (add it if missing)
+
+## Step 1: Install next-intl
+
+```bash
+yarn add next-intl
+```
+
+## Step 2: Directory Structure
+
+```
+src/
+├── i18n/
+│   ├── request.ts         # getRequestConfig — server-side locale resolver
+│   └── routing.ts         # defineRouting — supported locales and default
+├── messages/
+│   ├── en.json            # English translations
+│   └── es.json            # Spanish translations (example)
+```
+
+## Step 3: Define Routing Configuration
+
+```typescript
+// src/i18n/routing.ts
+import { defineRouting } from 'next-intl/routing';
+
+export const routing = defineRouting({
+  locales: ['en', 'es', 'fr', 'de', 'ja', 'ar'],
+  defaultLocale: 'en',
+});
+
+export type Locale = (typeof routing.locales)[number];
+```
+
+Adjust the `locales` array based on the languages your app needs.
+
+## Step 4: Request Configuration
+
+```typescript
+// src/i18n/request.ts
+import { getRequestConfig } from 'next-intl/server';
+import { routing } from './routing';
+
+export default getRequestConfig(async ({ requestLocale }) => {
+  let locale = await requestLocale;
+
+  if (!locale || !routing.locales.includes(locale as any)) {
+    locale = routing.defaultLocale;
+  }
+
+  return {
+    locale,
+    messages: (await import(`../messages/${locale}.json`)).default,
+  };
+});
+```
+
+## Step 5: Translation Files
+
+### English (default)
+
+```json
+// src/messages/en.json
+{
+  "common": {
+    "save": "Save",
+    "cancel": "Cancel",
+    "delete": "Delete",
+    "edit": "Edit",
+    "loading": "Loading…",
+    "error": "Something went wrong",
+    "success": "Success",
+    "confirm": "Are you sure?",
+    "back": "Back",
+    "next": "Next",
+    "search": "Search",
+    "noResults": "No results found"
+  },
+  "auth": {
+    "login": "Log in",
+    "signup": "Sign up",
+    "logout": "Log out",
+    "forgotPassword": "Forgot password?",
+    "resetPassword": "Reset password",
+    "email": "Email",
+    "password": "Password",
+    "confirmPassword": "Confirm password",
+    "name": "Full name"
+  },
+  "nav": {
+    "home": "Home",
+    "dashboard": "Dashboard",
+    "settings": "Settings",
+    "admin": "Admin"
+  },
+  "settings": {
+    "title": "Settings",
+    "profile": "Profile",
+    "security": "Security",
+    "language": "Language",
+    "theme": "Theme"
+  },
+  "errors": {
+    "required": "This field is required",
+    "invalidEmail": "Please enter a valid email address",
+    "passwordTooShort": "Password must be at least 8 characters",
+    "passwordMismatch": "Passwords do not match",
+    "unauthorized": "You are not authorized to perform this action",
+    "notFound": "Page not found",
+    "serverError": "An unexpected error occurred. Please try again."
+  },
+  "metadata": {
+    "title": "My App",
+    "description": "Built with Mars"
+  }
+}
+```
+
+### Spanish (example)
+
+```json
+// src/messages/es.json
+{
+  "common": {
+    "save": "Guardar",
+    "cancel": "Cancelar",
+    "delete": "Eliminar",
+    "edit": "Editar",
+    "loading": "Cargando…",
+    "error": "Algo salió mal",
+    "success": "Éxito",
+    "confirm": "¿Estás seguro?",
+    "back": "Atrás",
+    "next": "Siguiente",
+    "search": "Buscar",
+    "noResults": "No se encontraron resultados"
+  },
+  "auth": {
+    "login": "Iniciar sesión",
+    "signup": "Registrarse",
+    "logout": "Cerrar sesión",
+    "forgotPassword": "¿Olvidaste tu contraseña?",
+    "resetPassword": "Restablecer contraseña",
+    "email": "Correo electrónico",
+    "password": "Contraseña",
+    "confirmPassword": "Confirmar contraseña",
+    "name": "Nombre completo"
+  },
+  "nav": {
+    "home": "Inicio",
+    "dashboard": "Panel",
+    "settings": "Configuración",
+    "admin": "Administración"
+  },
+  "settings": {
+    "title": "Configuración",
+    "profile": "Perfil",
+    "security": "Seguridad",
+    "language": "Idioma",
+    "theme": "Tema"
+  },
+  "errors": {
+    "required": "Este campo es obligatorio",
+    "invalidEmail": "Introduce un correo electrónico válido",
+    "passwordTooShort": "La contraseña debe tener al menos 8 caracteres",
+    "passwordMismatch": "Las contraseñas no coinciden",
+    "unauthorized": "No tienes autorización para realizar esta acción",
+    "notFound": "Página no encontrada",
+    "serverError": "Ocurrió un error inesperado. Inténtalo de nuevo."
+  },
+  "metadata": {
+    "title": "Mi Aplicación",
+    "description": "Construido con Mars"
+  }
+}
+```
+
+## Step 6: Middleware Integration
+
+Integrate locale detection with the existing `proxy.ts` (MARS uses Next.js 16 proxy instead of `middleware.ts`):
+
+```typescript
+// In src/proxy.ts — add locale middleware integration
+import createIntlMiddleware from 'next-intl/middleware';
+import { routing } from '@/i18n/routing';
+
+const intlMiddleware = createIntlMiddleware(routing);
+
+// In the proxy handler, before other route matching:
+// 1. Run intlMiddleware to handle locale detection and redirects
+// 2. It reads Accept-Language header, cookies, and URL prefix to determine locale
+// 3. Falls back to defaultLocale when no match is found
+```
+
+The middleware handles:
+- **URL prefix detection**: `/es/dashboard` → Spanish locale
+- **Accept-Language header**: Detects browser language preference
+- **Cookie persistence**: Remembers user's locale choice via `NEXT_LOCALE` cookie
+- **Default locale fallback**: Routes without a prefix use the default locale
+
+## Step 7: Layout Integration
+
+### Root Layout
+
+```typescript
+// src/app/[locale]/layout.tsx
+import { NextIntlClientProvider } from 'next-intl';
+import { getMessages, getTranslations } from 'next-intl/server';
+import { routing, type Locale } from '@/i18n/routing';
+import { notFound } from 'next/navigation';
+
+interface LayoutProps {
+  children: React.ReactNode;
+  params: { locale: string };
+}
+
+export function generateStaticParams() {
+  return routing.locales.map((locale) => ({ locale }));
+}
+
+export async function generateMetadata({ params }: { params: { locale: string } }) {
+  const t = await getTranslations({ locale: params.locale, namespace: 'metadata' });
+  return {
+    title: t('title'),
+    description: t('description'),
+  };
+}
+
+export default async function LocaleLayout({ children, params }: LayoutProps) {
+  const { locale } = params;
+
+  if (!routing.locales.includes(locale as Locale)) {
+    notFound();
+  }
+
+  const messages = await getMessages();
+  const isRTL = ['ar', 'he', 'fa'].includes(locale);
+
+  return (
+    <html lang={locale} dir={isRTL ? 'rtl' : 'ltr'}>
+      <body>
+        <NextIntlClientProvider messages={messages}>
+          {children}
+        </NextIntlClientProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+## Step 8: Usage in Components
+
+### Server Components
+
+```typescript
+import { getTranslations } from 'next-intl/server';
+
+export default async function SettingsPage() {
+  const t = await getTranslations('settings');
+
+  return (
+    <div>
+      <h1>{t('title')}</h1>
+      <p>{t('profile')}</p>
+    </div>
+  );
+}
+```
+
+### Client Components
+
+```typescript
+'use client';
+
+import { useTranslations } from 'next-intl';
+
+export function SaveButton() {
+  const t = useTranslations('common');
+
+  return <button>{t('save')}</button>;
+}
+```
+
+### With Interpolation
+
+Translation file:
+```json
+{
+  "greeting": "Hello, {name}!",
+  "itemCount": "You have {count, plural, =0 {no items} one {# item} other {# items}}"
+}
+```
+
+Component:
+```typescript
+const t = useTranslations('dashboard');
+t('greeting', { name: user.name });
+t('itemCount', { count: items.length });
+```
+
+### Locale-Aware Links
+
+```typescript
+import { Link } from '@/i18n/routing';
+
+// Automatically prefixes the current locale
+<Link href="/dashboard">Dashboard</Link>
+
+// Switch locale explicitly
+<Link href="/dashboard" locale="es">Dashboard (Spanish)</Link>
+```
+
+Create the locale-aware link:
+
+```typescript
+// src/i18n/routing.ts (add to existing file)
+import { createNavigation } from 'next-intl/navigation';
+
+export const { Link, redirect, usePathname, useRouter } = createNavigation(routing);
+```
+
+## Step 9: Locale Switcher Component
+
+```typescript
+// src/features/i18n/components/locale-switcher.tsx
+'use client';
+
+import { useLocale } from 'next-intl';
+import { useRouter, usePathname } from '@/i18n/routing';
+import type { Locale } from '@/i18n/routing';
+
+const LOCALE_LABELS: Record<string, string> = {
+  en: 'English',
+  es: 'Español',
+  fr: 'Français',
+  de: 'Deutsch',
+  ja: '日本語',
+  ar: 'العربية',
+};
+
+export function LocaleSwitcher() {
+  const locale = useLocale();
+  const router = useRouter();
+  const pathname = usePathname();
+
+  function handleChange(newLocale: string) {
+    router.replace(pathname, { locale: newLocale as Locale });
+  }
+
+  return (
+    <select
+      value={locale}
+      onChange={(e) => handleChange(e.target.value)}
+      className="rounded-md border border-border-input bg-surface-input px-3 py-1.5 text-sm text-text-primary"
+      aria-label="Select language"
+    >
+      {Object.entries(LOCALE_LABELS).map(([code, label]) => (
+        <option key={code} value={code}>
+          {label}
+        </option>
+      ))}
+    </select>
+  );
+}
+```
+
+## Step 10: Date and Number Formatting
+
+```typescript
+'use client';
+
+import { useFormatter } from 'next-intl';
+
+export function FormattedContent() {
+  const format = useFormatter();
+
+  return (
+    <div>
+      <p>{format.dateTime(new Date(), { dateStyle: 'long' })}</p>
+      <p>{format.number(1234.56, { style: 'currency', currency: 'USD' })}</p>
+      <p>{format.relativeTime(new Date(Date.now() - 3600_000))}</p>
+      <p>{format.list(['Alice', 'Bob', 'Charlie'], { type: 'conjunction' })}</p>
+    </div>
+  );
+}
+```
+
+## Step 11: RTL Support
+
+For right-to-left languages (Arabic, Hebrew, Farsi), use CSS logical properties:
+
+```css
+/* Instead of: margin-left: 1rem */
+margin-inline-start: 1rem;
+
+/* Instead of: padding-right: 0.5rem */
+padding-inline-end: 0.5rem;
+
+/* Instead of: text-align: left */
+text-align: start;
+
+/* Instead of: border-left: 1px solid */
+border-inline-start: 1px solid;
+```
+
+Tailwind equivalents:
+- `ml-4` → `ms-4` (margin-inline-start)
+- `pr-2` → `pe-2` (padding-inline-end)
+- `text-left` → `text-start`
+- `pl-4` → `ps-4`
+- `border-l` → `border-s`
+
+The `dir` attribute on `<html>` is set automatically in the layout based on the locale.
+
+## Step 12: Adding a New Locale
+
+1. Add the locale code to `routing.locales` in `src/i18n/routing.ts`:
+   ```typescript
+   locales: ['en', 'es', 'fr', 'de', 'ja', 'ar', 'pt'],
+   ```
+
+2. Create the translation file `src/messages/pt.json` — copy `en.json` as a starting point:
+   ```bash
+   cp src/messages/en.json src/messages/pt.json
+   ```
+
+3. Translate all values in the new file (keys stay in English).
+
+4. Add the label to `LOCALE_LABELS` in the `LocaleSwitcher` component:
+   ```typescript
+   pt: 'Português',
+   ```
+
+5. If the locale is RTL, add it to the RTL check in the root layout:
+   ```typescript
+   const isRTL = ['ar', 'he', 'fa'].includes(locale);
+   ```
+
+6. Test the locale by visiting `/<locale>/` (e.g., `/pt/dashboard`).
+
+## Design Token Considerations
+
+- Ensure text containers can handle longer translations (German text is often 30% longer than English).
+- Use `min-width` / `min-height` instead of fixed dimensions for buttons and labels.
+- Test RTL layout thoroughly — check that icons, arrows, and navigation flow correctly.
+- Consider different numeral systems for Arabic (`useFormatter` handles this automatically).
+
+## Config Integration
+
+Add to `app.config.ts`:
+
+```typescript
+features: {
+  i18n: true,
+},
+services: {
+  i18n: {
+    defaultLocale: 'en',
+    locales: ['en', 'es'],
+  },
+},
+```
+
+## Tests
+
+```typescript
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { NextIntlClientProvider } from 'next-intl';
+
+const messages = {
+  common: { save: 'Save', cancel: 'Cancel' },
+};
+
+function renderWithIntl(ui: React.ReactElement, locale = 'en') {
+  return render(
+    <NextIntlClientProvider locale={locale} messages={messages}>
+      {ui}
+    </NextIntlClientProvider>,
+  );
+}
+
+describe('Translated component', () => {
+  it('renders translated text', () => {
+    renderWithIntl(<SaveButton />);
+    expect(screen.getByText('Save')).toBeInTheDocument();
+  });
+});
+```
+
+## Checklist
+
+- [ ] `next-intl` installed
+- [ ] `src/i18n/routing.ts` created with supported locales
+- [ ] `src/i18n/request.ts` created with `getRequestConfig`
+- [ ] Default translation file created (`src/messages/en.json`)
+- [ ] At least one additional locale file created
+- [ ] Proxy/middleware updated for locale detection and routing
+- [ ] Root layout wrapped with `NextIntlClientProvider`
+- [ ] `lang` and `dir` attributes set on `<html>` element
+- [ ] `generateStaticParams` exports all locales
+- [ ] Locale-aware `Link` and `useRouter` created via `createNavigation`
+- [ ] `LocaleSwitcher` component added to settings or header
+- [ ] Date/number formatting uses `useFormatter`
+- [ ] RTL styles use CSS logical properties / Tailwind logical utilities
+- [ ] Feature flag checked (`appConfig.features.i18n`)
+- [ ] Tests use `NextIntlClientProvider` wrapper