extract-code-documentation

name	extract-code-documentation
description	AI-powered translation metadata generation from codebase usage patterns and JSDoc/TSDoc docblocks Use when this capability is needed.
metadata	{"author":"excitingtheory"}

Extract Code Documentation

Generate AI-powered translation metadata for i18n locale files by analyzing code usage and component documentation.

What This Skill Does

Provides three approaches to generate AI-powered metadata for i18n locale files:

Approach 1: Codebase Analysis (auto-generate-metadata.ts)

1. Discover translation keys from actual code usage (useTranslation(), t())
2. Extract component descriptions from JSDoc @fileoverview
3. Generate metadata with Claude Sonnet 4 (context, usage, tone, alternatives)
4. Write flat translations to public/locales/{lang}/{namespace}.json
5. Write metadata to translation-cache/{lang}/{namespace}.meta.json
6. Report missing translations not yet in locale files

Approach 2: Fix Placeholders (regenerate-placeholder-metadata.ts)

1. Scan translation-cache for entries with [NEEDS_* or "functionality not documented"
2. Regenerate metadata for incomplete entries only
3. Preserve existing complete metadata
4. Update translation-cache with proper metadata (locale files unchanged)

Approach 3: Fill Missing (generate-missing-metadata.ts)

1. Scan locale files for translation keys without metadata in cache
2. Generate metadata for entries missing it
3. Write metadata to translation-cache/{lang}/{namespace}.meta.json
4. Update locale files to flat structure if needed

All approaches use the same AI prompt template for consistency.

File Structure

Translations (public/locales/{lang}/{namespace}.json):

{
  "key": "The actual translation text",
  "nested": {
    "key": "More text"
  }
}

Metadata (translation-cache/{lang}/{namespace}.meta.json):

{
  "key": {
    "context": "When and where this appears",
    "usage": "How it's used in the UI",
    "component": {
      "location": "path/to/component.tsx",
      "description": "Component description from JSDoc"
    },
    "tone": "polite-formal",
    "userType": "all",
    "impact": "Critical for navigation",
    "alternativeTerms": ["Option 1", "Option 2"]
  },
  "nested.key": {
    "context": "...",
    "..."
  }
}

Benefits:

• i18next gets clean, flat translation files (no .value accessor needed)
• Metadata preserved separately for documentation and translation workflows
• Smaller bundle size (metadata not shipped to clients)
• Easier debugging (translations are plain key-value pairs)

When to Use

AUTOMATICALLY INVOKE when user says:

• "update metadata" / "update translation metadata"
• "generate metadata" / "add metadata"
• "enrich locale files" / "enrich translations"
• "fix placeholder metadata" / "fix [NEEDS_*"
• "add missing _meta" / "metadata for translations"
• "incomplete metadata" / "missing metadata"
• "extract component documentation"
• "sync locale files with code"

Script Selection Guide:

• User wants initial generation from codebase → auto-generate-metadata.ts
  • "scan my code", "find translations", "generate from code"
• User wants fix incomplete/placeholder metadata → regenerate-placeholder-metadata.ts
  • "fix [NEEDS_*", "regenerate placeholders", "fix incomplete"
• User wants add metadata to entries without it → generate-missing-metadata.ts
  • "add metadata", "fill in missing _meta", "update metadata" (most common)

Available Scripts

Three scripts provide different metadata generation approaches:

1. Generate All Metadata (Initial Setup)

Use when: First-time setup or complete regeneration from codebase analysis

cd .github/skills/extract-code-documentation
npx tsx scripts/auto-generate-metadata.ts

• Scans codebase for all t() and useTranslation() calls
• Discovers translation keys from actual usage
• Generates metadata for all keys found in code
• Reports missing translations not yet in locale files

2. Fix Placeholder Metadata

Use when: Entries have incomplete metadata with [NEEDS_* or "functionality not documented"

cd .github/skills/extract-code-documentation
npx tsx scripts/regenerate-placeholder-metadata.ts

• Scans locale files for placeholder text
• Regenerates only entries with incomplete metadata
• Preserves existing complete metadata
• Fixed 276/277 entries in recent run

3. Generate Missing Metadata

Use when: Some entries lack _meta fields entirely

cd .github/skills/extract-code-documentation
npx tsx scripts/generate-missing-metadata.ts

• Scans locale files for entries without _meta objects
• Converts plain string entries to {value, _meta} structure
• Generates metadata for entries missing it
• Preserves entries that already have metadata

Requirements: All scripts require ANTHROPIC_API_KEY environment variable

Typical Output:

🔍 Step 1: Scanning locale files...
   Found 277 entries without metadata
📊 Missing metadata by namespace:
   - components: 250 entries
   - common: 15 entries
   - editor: 8 entries
🔍 Step 2: Extracting component docblocks...
   Extracted 183 component docblocks
🔍 Step 3: Generating metadata with AI...
   Progress: 10/277 entries processed...
   Progress: 270/277 entries processed...
✅ Generation complete!
   Successfully generated: 276
   Errors: 1

Agent Execution

Check for API key first:

if [ -z "$ANTHROPIC_API_KEY" ]; then
  echo "Error: ANTHROPIC_API_KEY required"
  exit 1
fi

Determine which script to run:

1. User wants to generate metadata from codebase usage → Run auto-generate-metadata.ts

   • First-time setup
   • "scan my code for translations"
   • "generate metadata from usage"

2. User wants to fix incomplete metadata → Run regenerate-placeholder-metadata.ts

   • "fix placeholder metadata"
   • "regenerate [NEEDS_*"
   • "update incomplete metadata"

3. User wants to add metadata to entries without it → Run generate-missing-metadata.ts

   • "add metadata to all entries"
   • "generate missing _meta fields"
   • "convert plain strings to metadata"

Run the appropriate script:

cd .github/skills/extract-code-documentation
npx tsx scripts/[chosen-script].ts

Report results to user:

• Number of entries found/processed
• Number of metadata entries generated successfully
• Which namespaces/files were updated
• Any errors encountered (scripts continue on errors)

On failure: All scripts continue processing remaining entries and report success/error counts at end.

Generated Metadata

Each locale entry gets AI-generated _meta:

{
  "loginButton": {
    "value": "Sign In",
    "_meta": {
      "context": "Login button in authentication form...",
      "component": {
        "location": "src/components/Authenticator.js",
        "description": "Authentication form component..."
      },
      "usage": "Primary action button...",
      "impact": "Critical - enables user access",
      "userType": "all",
      "tone": "polite-formal",
      "alternativeTerms": ["Log In", "Login", "Sign On"]
    }
  }
}

Fields: context, component (location + description from JSDoc), usage, impact, userType, tone, alternativeTerms

Script Architecture

Shared Modules:

• metadata-prompt.ts - Shared AI prompt template used by all scripts
• extract-component-docblocks.ts - JSDoc extraction utilities

Main Scripts:

• auto-generate-metadata.ts - Codebase analysis and generation
• regenerate-placeholder-metadata.ts - Fix incomplete metadata
• generate-missing-metadata.ts - Add metadata to entries without it

All scripts share the same AI prompt template for consistency across metadata generation.

Additional Utilities

Standalone docblock extraction (no AI, no API key):

npx tsx scripts/extract-component-docblocks.ts

Outputs list of components with/without JSDoc @fileoverview for documentation audits.

Related Skills

• multi-model-ai-translation - Multi-model translation with consensus
• docblock-backfill - Sync docblocks with locale metadata

Reference Documentation

• references/README.md - Complete schemas and API docs
• scripts/auto-generate-metadata.ts - Codebase scan implementation
• scripts/regenerate-placeholder-metadata.ts - Placeholder fix implementation
• scripts/generate-missing-metadata.ts - Missing metadata implementation
• scripts/metadata-prompt.ts - Shared AI prompt template

---

Version: 1.1.0 | Status: Production ready | Scripts: 3 main + 2 utilities

---

Converted and distributed by TomeVault — claim your Tome and manage your conversions.