# Extract Code Documentation > AI-powered translation metadata generation from codebase usage patterns and JSDoc/TSDoc docblocks Use when this capability is needed. - Skill: `tomevault-io/extract-code-documentation` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/extract-code-documentation` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/extract-code-documentation/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/extract-code-documentation --- # 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`): ```json { "key": "The actual translation text", "nested": { "key": "More text" } } ``` **Metadata** (`translation-cache/{lang}/{namespace}.meta.json`): ```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 ```bash 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" ```bash 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 ```bash 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:** ```bash 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:** ```bash 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`: ```json { "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](./scripts/metadata-prompt.ts) - Shared AI prompt template used by all scripts - [extract-component-docblocks.ts](./scripts/extract-component-docblocks.ts) - JSDoc extraction utilities **Main Scripts:** - [auto-generate-metadata.ts](./scripts/auto-generate-metadata.ts) - Codebase analysis and generation - [regenerate-placeholder-metadata.ts](./scripts/regenerate-placeholder-metadata.ts) - Fix incomplete metadata - [generate-missing-metadata.ts](./scripts/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): ```bash 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-ai-translation/SKILL.md) - Multi-model translation with consensus - [docblock-backfill](../docblock-backfill/SKILL.md) - Sync docblocks with locale metadata ## Reference Documentation - [references/README.md](./references/README.md) - Complete schemas and API docs - [scripts/auto-generate-metadata.ts](./scripts/auto-generate-metadata.ts) - Codebase scan implementation - [scripts/regenerate-placeholder-metadata.ts](./scripts/regenerate-placeholder-metadata.ts) - Placeholder fix implementation - [scripts/generate-missing-metadata.ts](./scripts/generate-missing-metadata.ts) - Missing metadata implementation - [scripts/metadata-prompt.ts](./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](https://tomevault.io/claim/excitingtheory) — claim your Tome and manage your conversions.