software-localisation

Original source / Raw SKILL.md

---
name: software-localisation
description: Production-grade i18n/l10n patterns for React, Vue, Angular, and Node.js. Covers i18next, react-intl, vue-i18n, ICU message format, RTL support, TMS integration, and CI/CD translation workflows.
---

# Software Localisation — Quick Reference

Production patterns for internationalisation (i18n) and localisation (l10n) in modern web applications. Covers library selection, translation management, ICU message format, RTL support, and CI/CD workflows.

**Modern Best Practices (Dec 2025)**: react-i18next 15.x (2.1M weekly downloads), react-intl 7.x (FormatJS), vue-i18n 10.x (Vue 3 Composition API), @angular/localize 19.x, LinguiJS 5.x (smallest bundle). ICU MessageFormat 2.0 draft, CLDR 46. TMS leaders: Phrase, Lokalise, Crowdin.

**Authoritative References**:
- [i18next Documentation](https://www.i18next.com/)
- [FormatJS/react-intl](https://formatjs.github.io/)
- [ICU Message Format](https://unicode-org.github.io/icu/userguide/format_parse/messages/)
- [MDN Intl API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl)

---

## Quick Reference

| Task | Tool/Library | Command | When to Use |
|------|--------------|---------|-------------|
| React i18n | react-i18next 15.x | `npm i i18next react-i18next` | Most React apps, flexibility |
| React i18n (ICU) | react-intl 7.x | `npm i react-intl` | Enterprise, ICU/CLDR standards |
| Vue i18n | vue-i18n 10.x | `npm i vue-i18n` | Vue 3 apps |
| Angular i18n | @angular/localize 19.x | `ng add @angular/localize` | Angular apps |
| Next.js i18n | next-intl 3.x | `npm i next-intl` | Next.js App Router |
| Minimal bundle | LinguiJS 5.x | `npm i @lingui/core @lingui/react` | Bundle size critical |
| Type-safe | typesafe-i18n 5.x | `npm i typesafe-i18n` | TypeScript-first projects |
| String extraction | i18next-parser | `npx i18next-parser` | Extract keys from code |
| ICU linting | @formatjs/cli | `npx formatjs extract` | Validate ICU messages |

---

## When to Use This Skill

Use this skill when the user requests:

- Setting up i18n/l10n in a React, Vue, Angular, or Next.js project
- Choosing between i18n libraries (i18next vs react-intl vs LinguiJS)
- Implementing pluralisation, interpolation, or ICU message format
- Adding RTL (right-to-left) language support
- Integrating with translation management systems (TMS)
- Setting up CI/CD pipelines for translation workflows
- Handling dates, numbers, currencies across locales
- Lazy loading translations for performance
- TypeScript integration with i18n

---

## Decision Tree: Library Selection

```text
Project requirements:
    │
    ├─ React/Next.js project?
    │   ├─ Enterprise, ICU/CLDR standards, TMS-first?
    │   │   └─ react-intl (FormatJS) — 17.8 kB, native ICU
    │   │
    │   ├─ Flexibility, plugins, lazy loading?
    │   │   └─ react-i18next — 22.2 kB, most popular
    │   │
    │   ├─ Bundle size critical (<15 kB)?
    │   │   └─ LinguiJS — 10.4 kB, ICU syntax
    │   │
    │   └─ TypeScript-first, compile-time safety?
    │       └─ typesafe-i18n — 2 kB runtime
    │
    ├─ Vue/Nuxt project?
    │   └─ vue-i18n — Native Vue integration, Composition API
    │
    ├─ Angular project?
    │   ├─ Built-in solution preferred?
    │   │   └─ @angular/localize — First-party, AOT support
    │   │
    │   └─ Need i18next ecosystem?
    │       └─ angular-i18next — Plugin wrapper
    │
    └─ Framework-agnostic / Node.js?
        └─ i18next core — Works everywhere
```

---

## Library Comparison

| Library | Bundle Size | ICU Support | Lazy Loading | TypeScript | Best For |
|---------|-------------|-------------|--------------|------------|----------|
| react-i18next | 22.2 kB | Plugin | Native | Good | Most React apps |
| react-intl | 17.8 kB | Native | Manual | Good | Enterprise, ICU standards |
| LinguiJS | 10.4 kB | Native | Native | Excellent | Bundle-conscious apps |
| typesafe-i18n | 2 kB | No | Manual | Excellent | TypeScript-first |
| vue-i18n | ~15 kB | Native | Native | Good | Vue 3 apps |
| @angular/localize | Built-in | Native | AOT | Native | Angular apps |

---

## Core Concepts

### Translation Key Patterns

```typescript
// Flat keys (simple)
"welcome": "Welcome to our app"
"user.greeting": "Hello, {name}"

// Nested keys (organised)
{
  "user": {
    "greeting": "Hello, {name}",
    "profile": {
      "title": "Your Profile"
    }
  }
}

// Namespace separation (scalable)
// common.json, auth.json, dashboard.json
```

### ICU Message Format Essentials

```text
// Simple interpolation
"Hello, {name}!"

// Pluralisation
"{count, plural, one {# item} other {# items}}"

// Select (gender, category)
"{gender, select, male {He} female {She} other {They}} liked your post"

// Number formatting
"Price: {price, number, currency}"

// Date formatting
"Posted: {date, date, medium}"
```

### Locale Detection Strategy

```text
Priority order:
1. User preference (stored in profile/localStorage)
2. URL parameter or path (/en/about, ?lang=de)
3. Cookie (NEXT_LOCALE, i18next)
4. Accept-Language header
5. Default locale fallback
```

---

## Navigation

### Resources (Deep Dives)

- [resources/framework-guides.md](resources/framework-guides.md) — React, Vue, Angular, Next.js implementation
- [resources/icu-message-format.md](resources/icu-message-format.md) — Pluralisation, select, formatting
- [resources/translation-workflows.md](resources/translation-workflows.md) — TMS, CI/CD, string extraction
- [resources/rtl-support.md](resources/rtl-support.md) — Right-to-left language support
- [resources/locale-handling.md](resources/locale-handling.md) — Dates, numbers, currencies

### Templates (Production Starters)

- [templates/react-i18next-setup.md](templates/react-i18next-setup.md) — React + i18next complete setup
- [templates/vue-i18n-setup.md](templates/vue-i18n-setup.md) — Vue 3 + vue-i18n setup
- [templates/nextjs-i18n-setup.md](templates/nextjs-i18n-setup.md) — Next.js App Router i18n

### Data

- [data/sources.json](data/sources.json) — 50+ curated external references

### Related Skills

- [../software-frontend/SKILL.md](../software-frontend/SKILL.md) — Frontend architecture patterns (React, Vue, Angular, Next.js)
- [../marketing-seo-technical/SKILL.md](../marketing-seo-technical/SKILL.md) — Hreflang, international SEO

---

## Quick Setup Examples

### React + i18next (5 minutes)

```bash
npm install i18next react-i18next i18next-http-backend i18next-browser-languagedetector
```

```typescript
// src/i18n.ts
import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import Backend from 'i18next-http-backend';
import LanguageDetector from 'i18next-browser-languagedetector';

i18n
  .use(Backend)
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    fallbackLng: 'en',
    debug: process.env.NODE_ENV === 'development',
    ns: ['common', 'auth', 'dashboard'],
    defaultNS: 'common',
    interpolation: { escapeValue: false },
    backend: { loadPath: '/locales/{{lng}}/{{ns}}.json' }
  });

export default i18n;
```

```typescript
// Usage in component
import { useTranslation } from 'react-i18next';

function Welcome() {
  const { t } = useTranslation();
  return <h1>{t('welcome')}</h1>;
}
```

### Vue 3 + vue-i18n (5 minutes)

```bash
npm install vue-i18n
```

```typescript
// src/i18n.ts
import { createI18n } from 'vue-i18n';

export const i18n = createI18n({
  legacy: false, // Composition API
  locale: 'en',
  fallbackLocale: 'en',
  messages: {
    en: { welcome: 'Welcome' },
    de: { welcome: 'Willkommen' }
  }
});
```

```vue
<script setup lang="ts">
import { useI18n } from 'vue-i18n';
const { t } = useI18n();
</script>

<template>
  <h1>{{ t('welcome') }}</h1>
</template>
```

### Next.js App Router + next-intl (5 minutes)

```bash
npm install next-intl
```

```typescript
// i18n/request.ts
import { getRequestConfig } from 'next-intl/server';

export default getRequestConfig(async ({ locale }) => ({
  messages: (await import(`../messages/${locale}.json`)).default
}));
```

```typescript
// app/[locale]/page.tsx
import { useTranslations } from 'next-intl';

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

---

## Common Patterns

### Namespace Organisation

```text
locales/
├── en/
│   ├── common.json      # Shared: buttons, errors, nav
│   ├── auth.json        # Login, register, password
│   ├── dashboard.json   # Dashboard-specific
│   └── validation.json  # Form validation messages
├── de/
│   └── ... (same structure)
└── ar/
    └── ... (same structure)
```

### Lazy Loading (Performance)

```typescript
// i18next: Load namespaces on demand
i18n.loadNamespaces('dashboard').then(() => {
  // Dashboard translations now available
});

// React Suspense integration
<Suspense fallback={<Loading />}>
  <Dashboard />
</Suspense>
```

### TypeScript Integration

```typescript
// resources.d.ts - Type-safe keys
import common from './locales/en/common.json';

declare module 'i18next' {
  interface CustomTypeOptions {
    defaultNS: 'common';
    resources: {
      common: typeof common;
    };
  }
}

// Now t('nonexistent') shows TypeScript error
```

---

## Anti-Patterns to Avoid

| Anti-Pattern | Problem | Fix |
|--------------|---------|-----|
| Hardcoded strings | Not translatable | Extract all user-facing text |
| String concatenation | Breaks translation context | Use interpolation `{name}` |
| Manual pluralisation | Wrong for many languages | Use ICU plural rules |
| Inline styles for RTL | Doesn't scale | Use CSS logical properties |
| Storing locale in URL only | Lost on navigation | Also persist to cookie/storage |
| No fallback locale | Blank text for missing keys | Always set `fallbackLng` |
| Loading all locales upfront | Slow initial load | Lazy load per namespace/locale |

---

## Operational Checklist

### Initial Setup

- [ ] Choose i18n library based on decision tree
- [ ] Set up directory structure for translations
- [ ] Configure fallback locale chain
- [ ] Set up locale detection strategy
- [ ] Add TypeScript types for translation keys
- [ ] Configure lazy loading for namespaces

### Translation Workflow

- [ ] Set up string extraction (i18next-parser, formatjs)
- [ ] Integrate with TMS (Phrase, Lokalise, Crowdin)
- [ ] Configure CI/CD for translation sync
- [ ] Set up translation review process
- [ ] Add missing key detection in development

### RTL Support

- [ ] Use CSS logical properties (margin-inline-start)
- [ ] Add dir="rtl" to html/body for RTL locales
- [ ] Test with actual RTL content (Arabic, Hebrew)
- [ ] Handle bidirectional text (BiDi)
- [ ] Mirror icons and images where appropriate

### Testing

- [ ] Test pluralisation with 0, 1, 2, 5, 21 (language-specific)
- [ ] Test date/number formatting per locale
- [ ] Test RTL layout in all components
- [ ] Test missing translation key handling
- [ ] Test locale switching without page reload


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### ../software-frontend/SKILL.md

```markdown
---
name: software-frontend
description: Production-grade frontend development with Next.js 16 App Router, TypeScript 5.9+ strict mode, Tailwind CSS v4, shadcn/ui, React 19.2 Server Components, state management (Zustand/Recoil), performance optimization (Turbopack stable, ISR/SSR/SSG), and accessibility best practices. Includes TanStack Query for server-state, Vitest for testing, and modern React patterns.
---

# Frontend Engineering Skill — Quick Reference

This skill equips frontend engineers with execution-ready patterns for building modern web applications with Next.js, React, TypeScript, and Tailwind CSS. Apply these patterns when you need component design, state management, routing, forms, data fetching, animations, accessibility, or production-grade UI architectures.

**Modern Best Practices (December 2025)**: Next.js 16 with Turbopack (stable, default bundler), **middleware.ts → proxy.ts migration** (clarifies network boundary, runs on Node.js runtime), React 19.2 with Server Components, Actions, Activity component, and useEffectEvent hook, enhanced ISR/SSR/SSG, partial prerendering (PPR), stable caching APIs (`cacheLife`, `cacheTag`, `updateTag`), Zustand/Recoil as Redux alternatives, TanStack Query (React Query) for server-state, TypeScript 5.9+ strict mode enforcement (TypeScript 7 "Corsa" Go-based compiler in preview), `satisfies` operator, Tailwind CSS v4 (CSS-first config, 5x faster builds), Vitest for testing, and progressive enhancement patterns.

**Next.js 16 Breaking Changes**: [Upgrade Guide](https://nextjs.org/docs/app/guides/upgrading/version-16)

---

## Quick Reference

| Task | Tool/Framework | Command | When to Use |
|------|----------------|---------|-------------|
| Next.js App | Next.js 16 + Turbopack | `npx create-next-app@latest` | Full-stack React apps, SEO, SSR/SSG |
| Vue App | Nuxt 4 | `npx nuxi@latest init` | Vue ecosystem, auto-imports, Nitro server |
| Angular App | Angular 21 | `ng new` | Enterprise apps, zoneless change detection, esbuild |
| Svelte App | SvelteKit 2.49+ | `npm create svelte@latest` | Performance-first, minimal JS, Svelte 5 runes |
| React SPA | Vite + React | `npm create vite@latest` | Client-side apps, fast dev server |
| UI Components | shadcn/ui + Radix UI | `npx shadcn@latest init` | Accessible components, Tailwind v4 styling |
| Forms | React Hook Form + Zod | `npm install react-hook-form zod` | Type-safe validation, performance |
| State Management | Zustand/Recoil | `npm install zustand` | Lightweight global state |
| Server State | TanStack Query | `npm install @tanstack/react-query` | API caching, server-state sync |
| Testing | Vitest + Testing Library | `vitest run` | Unit/component tests, fast execution |

# When to Use This Skill

Use this skill when you need:

- Next.js 16 application architecture and setup (Turbopack stable, App Router, React 19)
- React component design and patterns (functional components, hooks, Server Components)
- TypeScript type definitions for UI (strict mode, `satisfies` operator, discriminated unions)
- Tailwind CSS styling and responsive design (utility-first, dark mode variants)
- shadcn/ui component integration (Radix UI + Tailwind)
- Form handling and validation (React Hook Form + Zod, Server Actions)
- State management (Zustand/Recoil for client state, TanStack Query for server state)
- Data fetching (Server Components, TanStack Query/SWR, Server Actions, streaming)
- Authentication flows (NextAuth.js, Clerk, Auth0)
- Route handling and navigation (App Router, parallel routes, intercepting routes)
- Performance optimization (Turbopack, Image optimization, code splitting, ISR/SSR/SSG)
- Accessibility (WCAG 2.2, ARIA, keyboard navigation, screen reader testing) https://www.w3.org/TR/WCAG22/
- Animation and transitions (Framer Motion, Tailwind animations)
- Testing (Vitest for unit tests, Testing Library for components, Playwright for E2E)

## Decision Tree: Frontend Framework Selection

```text
Project needs: [Framework Choice]
    ├─ React ecosystem?
    │   ├─ Full-stack + SEO → Next.js 16 (App Router, React 19.2, Turbopack stable)
    │   ├─ Progressive enhancement → Remix (loaders, actions, nested routes)
    │   └─ Client-side SPA → Vite + React (fast dev, minimal config)
    │
    ├─ Vue ecosystem?
    │   ├─ Full-stack + SSR → Nuxt 4 (auto-imports, Nitro server, file-based routing)
    │   └─ Client-side SPA → Vite + Vue 3.5+ (Composition API, script setup)
    │
    ├─ Angular preferred?
    │   └─ Enterprise app → Angular 21 (zoneless change detection, esbuild, signals)
    │
    ├─ Performance-first?
    │   └─ Minimal JS bundle → SvelteKit 2.49+ (Svelte 5.45 runes, compiler magic)
    │
    ├─ Component library?
    │   ├─ Headless + customizable → shadcn/ui + Radix UI + Tailwind
    │   ├─ Material Design → MUI (Material-UI)
    │   └─ Enterprise UI → Ant Design
    │
    ├─ State management?
    │   ├─ Server data → TanStack Query/SWR (caching, sync)
    │   ├─ Global client state → Zustand (lightweight) or Recoil (React-first)
    │   ├─ Complex state logic → XState (state machines)
    │   └─ URL-based state → useSearchParams (shareable filters)
    │
    ├─ Styling approach?
    │   ├─ Utility-first → Tailwind CSS v4 (CSS-first config, 5x faster builds)
    │   ├─ CSS-in-JS → Styled Components or Emotion
    │   └─ CSS Modules → Built-in CSS Modules
    │
    └─ Testing strategy?
        ├─ Unit/Component → Vitest + Testing Library (fast, modern)
        ├─ E2E → Playwright (cross-browser, reliable)
        └─ Visual regression → Chromatic or Percy
```

**Framework Selection Factors:**

- **Team experience**: Choose what the team knows or can learn quickly
- **SSR/SSG requirements**: Next.js, Nuxt, Remix for server-side rendering
- **Performance constraints**: SvelteKit for minimal JS, Next.js for optimization
- **Ecosystem maturity**: React has largest ecosystem, Vue/Angular are also mature

See [resources/](resources/) for framework-specific best practices.

---

## Next.js 16 Migration: middleware.ts → proxy.ts

**Breaking Change (Dec 2025)**: The `middleware` convention is renamed to `proxy` in Next.js 16.

### Why the Change?

- **Clarity**: "Proxy" better describes the network boundary behavior (runs in front of the app)
- **Runtime**: `proxy.ts` runs on **Node.js runtime** (not Edge by default)
- **Avoid confusion**: Prevents confusion with Express.js middleware patterns

### Migration Steps

```bash
# 1. Run the codemod (recommended)
npx @next/codemod@canary upgrade latest

# 2. Or manually rename
mv middleware.ts proxy.ts
```

```typescript
// Before (Next.js 15)
export function middleware(request: Request) {
  // ... logic
}

// After (Next.js 16)
export function proxy(request: Request) {
  // ... logic
}
```

```typescript
// next.config.ts - Update config option
const nextConfig: NextConfig = {
  skipProxyUrlNormalize: true, // was: skipMiddlewareUrlNormalize
}
```

### Runtime Considerations

| Feature | proxy.ts (Next.js 16) | middleware.ts (legacy) |
| ------- | --------------------- | ---------------------- |
| Default Runtime | Node.js | Edge |
| Edge Support | Not supported | Supported |
| Use Case | Auth, rewrites, redirects | Edge-first apps |

**⚠️ Keep using `middleware.ts`** if you need Edge Runtime. The `proxy` convention does NOT support Edge.

### Related Changes in Next.js 16

- **Async Request APIs**: `cookies()`, `headers()`, `params`, `searchParams` are now async
- **Turbopack default**: Remove `--turbopack` flags from scripts
- **Parallel routes**: Require explicit `default.js` files
- **Image changes**: `domains` deprecated (use `remotePatterns`), new default cache TTL

---

## React 19.2 Patterns (Dec 2025)

### Security Note (React Server Components)

- Track and patch React Server Components vulnerabilities quickly (RCE/DoS/source exposure advisories in Dec 2025) https://react.dev/blog/2025/12/03/critical-security-vulnerability-in-react-server-components and https://react.dev/blog/2025/12/11/denial-of-service-and-source-code-exposure-in-react-server-components

### Partial Prerendering (PPR)

Pre-render static shell, stream dynamic content.

```typescript
// Next.js 16 with PPR enabled
// next.config.js
export default {
  experimental: {
    ppr: true, // Enable Partial Prerendering
  },
};

// Page component
export default async function Page() {
  return (
    <main>
      <Header /> {/* Static: pre-rendered */}
      <Suspense fallback={<Skeleton />}>
        <DynamicContent /> {/* Dynamic: streamed */}
      </Suspense>
      <Footer /> {/* Static: pre-rendered */}
    </main>
  );
}
```

### use() Hook Pattern

Promise resolution in components with Suspense.

```typescript
// Before: useEffect + useState
const [data, setData] = useState(null);
useEffect(() => {
  fetchData().then(setData);
}, []);

// After: use() hook (React 19+)
const data = use(fetchDataPromise);
```

### Error Boundary Patterns

```typescript
'use client';

import { ErrorBoundary } from 'react-error-boundary';

function ErrorFallback({ error, resetErrorBoundary }) {
  return (
    <div role="alert">
      <p>Something went wrong:</p>
      <pre>{error.message}</pre>
      <button onClick={resetErrorBoundary}>Try again</button>
    </div>
  );
}

export default function App() {
  return (
    <ErrorBoundary FallbackComponent={ErrorFallback}>
      <MyComponent />
    </ErrorBoundary>
  );
}
```

### Performance Budgets

| Metric | Target | Tool |
|--------|--------|------|
| LCP (Largest Contentful Paint) | <= 2.5s | Lighthouse / web-vitals |
| INP (Interaction to Next Paint) | <= 200ms | Chrome DevTools / web-vitals https://web.dev/vitals/ |
| CLS (Cumulative Layout Shift) | <= 0.1 | Lighthouse / web-vitals |
| TTFB (Time to First Byte) | Project SLO [Inference] | Lighthouse |
| Bundle size (JS) | Project budget [Inference] | bundle analyzer |

---

### Optional: AI/Automation Extensions

> **Note**: AI design and development tools. Skip if not using AI tooling.

#### AI Design Tools

| Tool | Use Case |
|------|----------|
| v0.dev | UI generation from prompts |
| Vercel AI SDK | Streaming UI, chat interfaces |
| Figma AI | Design-to-code prototypes |
| Visily | Wireframe generation |

#### AI-Powered Testing

| Tool | Use Case |
|------|----------|
| Playwright AI | Self-healing selectors |
| Testim | AI-generated test maintenance |
| Applitools | Visual AI testing |

#### Optional Related Skills

- [../ai-llm/SKILL.md](../ai-llm/SKILL.md) — Optional: AI-powered features and LLM integration patterns

---

## Navigation

**Resources** (Framework-specific best practices)
- [resources/fullstack-patterns.md](resources/fullstack-patterns.md) — Universal patterns: Server vs client components, data fetching, TypeScript
- [resources/vue-nuxt-patterns.md](resources/vue-nuxt-patterns.md) — Vue 3 Composition API, Nuxt 3, Pinia state management
- [resources/angular-patterns.md](resources/angular-patterns.md) — Angular 18 standalone components, signals, RxJS patterns
- [resources/svelte-sveltekit-patterns.md](resources/svelte-sveltekit-patterns.md) — Svelte 5 runes, SvelteKit loaders/actions
- [resources/remix-react-patterns.md](resources/remix-react-patterns.md) — Remix loaders, actions, progressive enhancement
- [resources/vite-react-patterns.md](resources/vite-react-patterns.md) — Vite setup, React hooks, TanStack Query
- [resources/artifacts-builder.md](resources/artifacts-builder.md) — React/Tailwind/shadcn artifact workflow and bundling to single HTML
- [README.md](README.md) — Folder overview and usage notes
- [data/sources.json](data/sources.json) — 106 curated resources for all frameworks (Next.js, Vue/Nuxt, Angular, Svelte, Remix, Vite)
- Shared checklist: [../software-clean-code-standard/templates/checklists/frontend-performance-a11y-checklist.md](../software-clean-code-standard/templates/checklists/frontend-performance-a11y-checklist.md)

**Shared Utilities** (Centralized patterns — extract, don't duplicate)
- [../software-clean-code-standard/utilities/error-handling.md](../software-clean-code-standard/utilities/error-handling.md) — Effect Result types, correlation IDs
- [../software-clean-code-standard/utilities/config-validation.md](../software-clean-code-standard/utilities/config-validation.md) — Zod 3.24+, Valibot for client validation
- [../software-clean-code-standard/utilities/logging-utilities.md](../software-clean-code-standard/utilities/logging-utilities.md) — Structured logging patterns
- [../software-clean-code-standard/utilities/testing-utilities.md](../software-clean-code-standard/utilities/testing-utilities.md) — Vitest, MSW v2, factories, fixtures
- [../software-clean-code-standard/utilities/observability-utilities.md](../software-clean-code-standard/utilities/observability-utilities.md) — OpenTelemetry SDK, tracing, metrics
- [../software-clean-code-standard/resources/clean-code-standard.md](../software-clean-code-standard/resources/clean-code-standard.md) — Canonical clean code rules (`CC-*`) for citation

**Templates** (Production-ready starters by framework)
- **Next.js**: [templates/nextjs/template-nextjs-tailwind-shadcn.md](templates/nextjs/template-nextjs-tailwind-shadcn.md)
- **Vue/Nuxt**: [templates/vue-nuxt/template-nuxt3-tailwind.md](templates/vue-nuxt/template-nuxt3-tailwind.md)
- **Angular**: [templates/angular/template-angular21-standalone.md](templates/angular/template-angular21-standalone.md)
- **Svelte/SvelteKit**: [templates/svelte/template-sveltekit-runes.md](templates/svelte/template-sveltekit-runes.md)
- **Remix**: [templates/remix/template-remix-react.md](templates/remix/template-remix-react.md)
- **Vite + React**: [templates/vite-react/template-vite-react-ts.md](templates/vite-react/template-vite-react-ts.md)

**Related Skills**
- [../dev-api-design/SKILL.md](../dev-api-design/SKILL.md) — REST/GraphQL API patterns, OpenAPI, versioning
- [../git-workflow/SKILL.md](../git-workflow/SKILL.md) — Git branching, PR workflow, commit conventions
- [../software-backend/SKILL.md](../software-backend/SKILL.md) — Backend API development, Node.js, Prisma, authentication
- [../software-architecture-design/SKILL.md](../software-architecture-design/SKILL.md) — System design, scalability, microservices patterns
- [../software-code-review/SKILL.md](../software-code-review/SKILL.md) — Code review best practices, PR workflow
- [../ops-devops-platform/SKILL.md](../ops-devops-platform/SKILL.md) — Deployment, CI/CD, containerization, Kubernetes
- [../data-sql-optimization/SKILL.md](../data-sql-optimization/SKILL.md) — Database design, SQL optimization, Prisma/Drizzle

---

## Operational Playbooks
- [resources/operational-playbook.md](resources/operational-playbook.md) — Framework-specific architecture patterns, TypeScript guides, and security/performance checklists

```

### ../marketing-seo-technical/SKILL.md

```markdown
---
name: marketing-seo-technical
description: Technical SEO auditing for traditional search engines (Google, Bing) covering Core Web Vitals, crawlability, structured data, mobile optimization, site architecture, and actionable fix recommendations.
---

# TECHNICAL SEO AUDITING — OPERATIONAL SKILL

This skill contains **actionable, production-ready systems** for performing comprehensive technical SEO audits and delivering prioritized optimization recommendations for **traditional search engines** (Google, Bing).

Use this skill when the user asks for:
- Technical SEO audits (full or targeted)
- Core Web Vitals optimization (LCP, INP, CLS)
- Crawlability and indexation issues
- Structured data/Schema.org implementation
- Mobile-first optimization
- Site speed and performance fixes
- Internal linking architecture
- Duplicate content and canonical handling
- International SEO (hreflang)
- Security and HTTPS configuration

---

## Quick Reference

| Task | Resource/Template | Location | When to Use |
|------|------------------|----------|-------------|
| **Auditing** | | | |
| Full Technical Audit | 10-Point Checklist | `templates/audits/full-technical-audit.md` | Comprehensive site-wide audit |
| Quick Audit | Abbreviated Checklist | `templates/audits/quick-audit-checklist.md` | Fast issue identification |
| Priority Matrix | Impact vs Effort | `templates/priority/impact-effort-matrix.md` | Prioritize audit findings |
| **Core Web Vitals** | | | |
| CWV Deep Dive | CWV Guide | `resources/core-web-vitals-guide.md` | LCP, INP, CLS optimization |
| CWV Report | Report Template | `templates/cwv/core-web-vitals-report.md` | Document CWV findings |
| **Crawlability** | | | |
| Indexation Issues | Crawlability Guide | `resources/crawlability-indexing.md` | Robots.txt, sitemaps, GSC issues |
| **Performance** | | | |
| Site Speed | Speed Guide | `resources/site-speed-optimization.md` | TTFB, render-blocking, images |
| **Technical Setup** | | | |
| Mobile Optimization | Mobile Guide | `resources/mobile-seo-guide.md` | Responsive, viewport, mobile-first |
| Structured Data | Schema Guide | `resources/structured-data-guide.md` | JSON-LD, rich snippets |
| Schema Report | Validation Template | `templates/schema/schema-validation-report.md` | Document schema findings |
| Security/HTTPS | Security Guide | `resources/security-https-guide.md` | HTTPS, HSTS, headers |
| **Architecture** | | | |
| Internal Linking | Link Strategy | `resources/internal-linking-strategy.md` | Link equity, orphan pages |
| Duplicate Content | Canonical Guide | `resources/duplicate-content-handling.md` | Canonicals, pagination |
| International SEO | Hreflang Guide | `resources/internationalization-hreflang.md` | Multi-language/region sites |

---

## 10-Point Audit Framework

Every technical SEO audit follows this systematic checklist:

| # | Area | Key Metrics | Weight |
|---|------|-------------|--------|
| 1 | **Crawlability** | robots.txt status, sitemap coverage, crawl budget | High |
| 2 | **Core Web Vitals** | LCP <2.5s, INP <200ms, CLS <0.1 | High |
| 3 | **Site Speed** | TTFB <800ms, FCP <1.8s, Speed Index | High |
| 4 | **Mobile** | Mobile-friendly score, viewport, touch targets | High |
| 5 | **Security** | HTTPS, mixed content, HSTS, headers | Medium |
| 6 | **Structured Data** | Schema validity, rich snippet eligibility | Medium |
| 7 | **On-Page** | Meta tags, heading hierarchy, keyword signals | Medium |
| 8 | **Architecture** | Internal links, URL structure, canonicals | High |
| 9 | **Duplicate Content** | Canonical implementation, pagination | Medium |
| 10 | **Internationalization** | Hreflang (if applicable), geo-targeting | Low |

**Scoring**: Rate each area 0-10, calculate weighted average for overall Technical Health Score.

---

## Decision Trees

```text
### Audit Type Selection
Full site audit needed
  └─ Use templates/audits/full-technical-audit.md
Quick issue check
  └─ Use templates/audits/quick-audit-checklist.md
CWV-only deep dive
  └─ Use templates/cwv/core-web-vitals-report.md
Schema validation only
  └─ Use templates/schema/schema-validation-report.md

### Core Web Vitals Failing
LCP >2.5s
  └─ Preload LCP element, optimize images, add CDN
  └─ See resources/core-web-vitals-guide.md
INP >200ms
  └─ Reduce JavaScript, optimize event handlers
  └─ See resources/core-web-vitals-guide.md
CLS >0.1
  └─ Add dimensions to images/ads, avoid layout shifts
  └─ See resources/core-web-vitals-guide.md

### Indexation Issues
Pages not indexed
  └─ Check robots.txt blocking
  └─ Verify sitemap inclusion
  └─ Check canonical tags
  └─ See resources/crawlability-indexing.md
Crawl budget problems
  └─ Remove low-value pages from crawl
  └─ Fix redirect chains
  └─ Optimize pagination
  └─ See resources/crawlability-indexing.md

### Mobile Issues
Mobile-unfriendly
  └─ Check viewport meta tag
  └─ Verify responsive CSS
  └─ Test touch target sizes
  └─ See resources/mobile-seo-guide.md

### Security Issues
Mixed content warnings
  └─ Update all HTTP resources to HTTPS
  └─ See resources/security-https-guide.md
SSL/TLS issues
  └─ Run SSL Labs test
  └─ See resources/security-https-guide.md
```

---

## Navigation

### Core Resources

- [resources/core-web-vitals-guide.md](resources/core-web-vitals-guide.md) - LCP, INP, CLS thresholds and optimization
- [resources/crawlability-indexing.md](resources/crawlability-indexing.md) - Robots.txt, sitemaps, GSC, indexation
- [resources/site-speed-optimization.md](resources/site-speed-optimization.md) - TTFB, render-blocking, image optimization
- [resources/mobile-seo-guide.md](resources/mobile-seo-guide.md) - Mobile-first indexing, responsive design
- [resources/structured-data-guide.md](resources/structured-data-guide.md) - Schema.org, JSON-LD, rich snippets
- [resources/security-https-guide.md](resources/security-https-guide.md) - HTTPS, HSTS, security headers
- [resources/internal-linking-strategy.md](resources/internal-linking-strategy.md) - Link architecture, orphan pages
- [resources/duplicate-content-handling.md](resources/duplicate-content-handling.md) - Canonicals, pagination, parameters
- [resources/internationalization-hreflang.md](resources/internationalization-hreflang.md) - Hreflang, geo-targeting

### Templates

#### Audits
- [templates/audits/full-technical-audit.md](templates/audits/full-technical-audit.md) - Complete 10-point audit checklist
- [templates/audits/quick-audit-checklist.md](templates/audits/quick-audit-checklist.md) - Fast abbreviated audit

#### Core Web Vitals
- [templates/cwv/core-web-vitals-report.md](templates/cwv/core-web-vitals-report.md) - CWV-specific audit report

#### Structured Data
- [templates/schema/schema-validation-report.md](templates/schema/schema-validation-report.md) - Schema audit report

#### Prioritization
- [templates/priority/impact-effort-matrix.md](templates/priority/impact-effort-matrix.md) - Issue prioritization matrix

---

## Related Skills

**Marketing & SEO**
- [../marketing-ai-search-optimization/SKILL.md](../marketing-ai-search-optimization/SKILL.md) - Search visibility beyond classic SERPs (complements technical SEO)
- [../marketing-social-media/SKILL.md](../marketing-social-media/SKILL.md) - Social media marketing and content distribution

**Technical Implementation**
- [../software-frontend/SKILL.md](../software-frontend/SKILL.md) - Frontend performance optimization, SSR
- [../software-backend/SKILL.md](../software-backend/SKILL.md) - Server-side optimization, API performance
- [../software-security-appsec/SKILL.md](../software-security-appsec/SKILL.md) - Security hardening, HTTPS implementation

**Quality & Performance**
- [../qa-observability/SKILL.md](../qa-observability/SKILL.md) - Performance monitoring, observability
- [../ops-devops-platform/SKILL.md](../ops-devops-platform/SKILL.md) - CDN setup, infrastructure optimization

---

## Key Differentiators

**Audit Output Format:**
- **Critical Issues** - Fix immediately (high impact)
- **Important Optimizations** - Fix soon (medium impact)
- **Recommended Enhancements** - Nice to have

**Each finding includes:**
- What's wrong and why it matters
- Step-by-step fix instructions
- Expected outcome
- Validation method

---

## External Resources

See [data/sources.json](data/sources.json) for 46 primary sources across:
- Google Search Central, web.dev, and Chrome developer docs (CWV, Lighthouse, CrUX)
- Bing Webmaster Guidelines and diagnostic tooling
- Crawl/index/render fundamentals (robots, sitemaps, canonicals, JS SEO)
- Structured data eligibility and validation tooling
- Optional automation references (Search Console API, CrUX API, Lighthouse CI)

---

## Getting Started

**Quick audit (15 minutes):**
1. Run PageSpeed Insights on key pages
2. Check robots.txt and sitemap.xml accessibility
3. Validate structured data with Rich Results Test
4. Review GSC Coverage report for indexation issues
5. Use [templates/audits/quick-audit-checklist.md](templates/audits/quick-audit-checklist.md)

**Full audit (2-4 hours):**
1. Use [templates/audits/full-technical-audit.md](templates/audits/full-technical-audit.md)
2. Work through all 10 audit areas systematically
3. Score each area 0-10
4. Prioritize findings with [templates/priority/impact-effort-matrix.md](templates/priority/impact-effort-matrix.md)
5. Document fixes with validation steps

**Ongoing monitoring:**
1. Set up GSC alerts for indexation issues
2. Monitor Core Web Vitals in CrUX
3. Schedule quarterly audits
4. Track improvements against baseline

---

## Core: SEO Testing & Monitoring

### Testing Framework

| Test Type | When | Tools | Goal |
|-----------|------|-------|------|
| **Pre-launch** | Before deployment | Staging crawl, Lighthouse CI | Catch issues before they affect live site |
| **SEO split tests** | When optimizing | Edge routing, feature flags, server-side experiments | Validate changes before full rollout |
| **Regression testing** | After deployments | Screaming Frog, Sitebulb | Ensure no new issues introduced |
| **CWV monitoring** | Continuous | CrUX, PageSpeed API, WebPageTest | Track performance over time |

### Monitoring Checklist

| Signal | Frequency | Tool | Alert Threshold |
|--------|-----------|------|-----------------|
| Indexation status | Daily | GSC Coverage | >5% drop |
| CWV scores | Daily | CrUX/PSI | Any metric fails threshold |
| Crawl errors | Daily | GSC | Any new 4xx/5xx |
| Sitemap health | Weekly | GSC | Submitted ≠ Indexed |
| Schema validity | Weekly | Rich Results Test | Any errors |
| Security issues | Daily | GSC Security Issues | Any alerts |

### Do (Testing)

- Set up automated Lighthouse CI in your deployment pipeline
- Use GSC API to monitor indexation programmatically
- Test staging environments with noindex before launch
- Track CWV in CrUX (field data) not just lab data
- Create baseline measurements before optimization

### Avoid (Testing)

- Testing only on fast dev machines (test on throttled mobile)
- Ignoring field data (CrUX) in favor of lab data (Lighthouse)
- Making multiple changes simultaneously (can't isolate impact)
- Deploying without crawling staging first

---

## Success Criteria

> A successful technical SEO audit delivers a prioritized list of issues with clear fix instructions and validation methods that measurably improve search visibility and Core Web Vitals scores.

---

## Optional: AI / Automation

> **Note**: Core technical SEO fundamentals above work without AI tools. This section covers optional automation capabilities.

### Automated Auditing Tools

| Tool | Automation Level | Best For |
|------|------------------|----------|
| **Screaming Frog** | Crawl + export | Comprehensive site audits |
| **Sitebulb** | Crawl + prioritized insights | Visual issue prioritization |
| **Semrush Site Audit** | Automated crawls + alerts | Continuous monitoring |
| **Ahrefs Site Audit** | Automated crawls | Technical + backlink combined |
| **ContentKing** | Real-time monitoring | Enterprise with frequent changes |
| **Lumar (DeepCrawl)** | Enterprise crawling | Large sites, JavaScript-heavy |

### Log Analysis Automation

| Tool | Use Case |
|------|----------|
| **Screaming Frog Log Analyzer** | Googlebot crawl patterns |
| **OnCrawl** | Log + crawl correlation |
| **JetOctopus** | Large-scale log analysis |
| **BigQuery + GSC API** | Custom analysis pipelines |

### AI-Assisted Analysis

| Use Case | Approach | Consideration |
|----------|----------|---------------|
| **Issue prioritization** | ML models rank by impact | Validate with domain knowledge |
| **Anomaly detection** | Automated traffic/ranking drops | Set appropriate thresholds |
| **Content gap analysis** | NLP-based competitor analysis | Combine with manual review |
| **Schema generation** | LLM-generated JSON-LD | Always validate output |

### Do (AI/Automation)

- Automate crawling on a schedule (weekly minimum)
- Use alerts for critical issues (500 errors, robots.txt changes)
- Combine automated findings with manual analysis
- Version control robots.txt and critical SEO files

### Avoid (AI/Automation)

- Trusting automated recommendations without validation
- Over-relying on tools without understanding fundamentals
- Auto-implementing schema without testing
- Ignoring false positives (tools over-report)

---

## Collaboration Notes

### With Product

- **Site redesigns**: SEO requirements in early planning, not post-launch
- **URL changes**: Redirect mapping before launch
- **New features**: Consider indexability and crawlability impact
- **Page deprecation**: Proper 301/410 handling

### With Engineering

- **Deployment pipeline**: Add Lighthouse CI, crawl staging pre-launch
- **Performance budgets**: Set CWV thresholds in CI
- **Server config**: robots.txt, redirects, canonical implementation
- **JavaScript**: SSR/SSG for critical content, hydration impact
- **CDN setup**: Cache headers, edge optimization

### With Design

- **Image optimization**: WebP/AVIF formats, responsive images
- **Layout stability**: Reserve space for dynamic elements (CLS)
- **Above-the-fold**: Prioritize LCP element rendering
- **Fonts**: Font loading strategy (font-display: swap)

---

## Anti-Patterns

| Anti-Pattern | Why It Fails | Instead |
|--------------|--------------|---------|
| **Audit without action** | Findings sit in a spreadsheet | Assign owners, set deadlines, track progress |
| **Fix everything at once** | Can't measure what worked | Batch by priority, deploy incrementally |
| **Ignore mobile** | 60%+ of traffic is mobile, mobile-first indexing | Test and optimize mobile-first |
| **Over-optimize CWV** | Diminishing returns past "good" threshold | Focus on user experience, not perfect scores |
| **Block crawlers "for protection"** | Invisible to search | Allow crawlers, rate limit if needed |
| **Dynamic rendering as first choice** | Complexity, maintenance cost | Prefer SSR/SSG; dynamic rendering as last resort |
| **Trust lab data only** | Doesn't reflect real user experience | Use CrUX (field data) as source of truth |
| **One-time audit** | SEO degrades over time | Continuous monitoring, quarterly deep audits |

```