Internationalization (i18n) Guide

VibeAlive supports multiple languages through its internationalization system. This guide explains how to contribute translations and use different locales.

Supported Languages

Currently supported locales:

English (en) - Default, fully supported
Spanish (es) - Community contributions welcome
French (fr) - Community contributions welcome
German (de) - Community contributions welcome
Japanese (ja) - Community contributions welcome
Chinese (zh) - Community contributions welcome
Portuguese (pt) - Community contributions welcome
Russian (ru) - Community contributions welcome
Italian (it) - Community contributions welcome
Korean (ko) - Community contributions welcome

Using Different Languages

CLI Usage

Set your preferred language using the --locale option:

# Use Spanish
vibealive analyze . --locale es

# Use French  
vibealive analyze . --locale fr

# Use German
vibealive analyze . --locale de

# Use Japanese
vibealive analyze . --locale ja

# Use Portuguese
vibealive analyze . --locale pt

Configuration File

You can also set the locale in your project's configuration file:

// .vibealive.config.js
module.exports = {
  locale: 'es', // Spanish
  // ... other config options
};

Environment Detection

VibeAlive automatically detects your system locale from environment variables (LANG, LC_ALL, LC_MESSAGES) and uses it as the default if supported.

Contributing Translations

We welcome community contributions for translations! Here's how to add support for a new language or improve existing translations.

1. Create a New Locale File

Create a new JSON file in src/i18n/locales/ named with the language code (e.g., es.json for Spanish).

2. Translation Structure

Use the English locale file (src/i18n/locales/en.json) as your reference. The structure looks like this:

{
  "cli": {
    "analysis": {
      "starting": "🔍 Analyzing Next.js project...",
      "complete": "✅ Analysis complete!"
    },
    "errors": {
      "analysisError": "❌ Analysis failed:"
    }
  },
  "reports": {
    "markdown": {
      "title": "# Next.js Code Analysis Report",
      "executiveSummary": "## 📊 Executive Summary"
    }
  }
}

3. Translation Guidelines

Preserve Formatting

Keep emojis and special characters (🔍, ✅, ❌, etc.)
Maintain Markdown formatting (#, ##, ###, **bold**, etc.)
Preserve HTML-like tags and code blocks

Variable Interpolation

Variables are marked with {{variableName}}. Translate around them but keep the variable syntax:

// English
"totalFiles": "- **Total Files Analyzed**: {{count}}"

// Spanish  
"totalFiles": "- **Archivos Analizados**: {{count}}"

Context-Aware Translation

Consider the context where strings appear:

CLI messages: Brief, action-oriented
Report headers: Formal, descriptive
Error messages: Clear, helpful
Status messages: Concise, informative

Consistent Terminology

Maintain consistent technical terms throughout your translation:

"Next.js project" → Same term throughout
"Analysis" → Same term throughout
"Bundle" → Same term throughout

4. Testing Your Translation

Build the project with your new locale file:
```
npm run build
```

Test CLI commands with your locale:

node dist/cli.js analyze . --locale your_locale

Verify reports are generated correctly:

# Check generated markdown report
cat .vibealive/analysis-results/analysis-report-*.md

5. Translation Template

Copy this template for new translations:

{
  "cli": {
    "analysis": {
      "starting": "🔍 [Analyzing Next.js project...]",
      "detectingStructure": "📁 [Detecting project structure...]",
      "generatingHealthReport": "🏠 [Generating project health report...]",
      "complete": "✅ [Analysis complete!]",
      "failed": "❌ [Analysis failed:]",
      "initializingAnalysis": "- [Initializing analysis...]",
      "analysisCompleted": "✔ [Analysis completed!]",
      "generatingReports": "- [Generating reports...]",
      "reportsGenerated": "✔ [Reports generated!]"
    },
    "apiScan": {
      "title": "🚀 [API Routes Analysis]",
      "totalApiFiles": "• [Total API files:] {{count}}",
      "unusedRoutes": "• [Unused routes:] {{count}}",
      "activeRoutes": "• [Active routes:] {{count}}",
      "generatedReports": "📁 [Generated reports:]",
      "reportFile": "• {{file}}",
      "failed": "[API scan failed]"
    },
    "config": {
      "initComplete": "🎉 [Initialization complete!]",
      "nextSteps": "[Next steps:]",
      "reviewConfig": "   1. [Review and customize .vibealive/config.js if needed]",
      "runAnalyze": "   2. [Run `vibealive analyze` to start analyzing your project]",
      "cleanupCancelled": "ℹ️  [Cleanup cancelled.]",
      "cleanupComplete": "🎉 [Cleanup completed!]",
      "removedVibeAliveDir": "✅ [Removed .vibealive directory]",
      "noFilesToCleanup": "🔍 [No VibeAlive files found to cleanup.]"
    },
    "errors": {
      "analysisError": "❌ [Analysis failed:]",
      "configInitFailed": "❌ [Failed to initialize config:]",
      "cleanupFailed": "❌ [Failed to cleanup:]",
      "fileCheckFailed": "❌ [File check failed:]",
      "directoryScanFailed": "❌ [Directory scan failed:]",
      "componentScanFailed": "❌ [Component scan failed:]",
      "apiScanFailed": "❌ [API scan failed:]",
      "mcpServerStartFailed": "❌ [Failed to start MCP server:]",
      "cleanupDirFailed": "❌ [Failed to remove .vibealive directory:] {{error}}"
    },
    "validation": {
      "unsupportedFormat": "[Unsupported format:] {{format}}",
      "invalidFormats": "[Invalid format:] {{formats}}. [Valid formats:] {{validFormats}}",
      "portMustBeNumber": "[Port must be a number.]"
    }
  },
  "reports": {
    "markdown": {
      "title": "# [Next.js Code Analysis Report]",
      "executiveSummary": "## 📊 [Executive Summary]",
      "project": "- **[Project]**: {{project}}",
      "nextVersion": "- **[Next.js Version]**: {{version}}",
      "routerType": "- **[Router Type]**: {{routerType}}",
      "analysisDate": "- **[Analysis Date]**: {{date}}",
      "analysisTime": "- **[Analysis Time]**: {{time}}",
      "totalFiles": "- **[Total Files Analyzed]**: {{count}}",
      "totalComponents": "- **[Total Components]**: {{count}}",
      "totalApiEndpoints": "- **[Total API Endpoints]**: {{count}}",
      "keyFindings": "## 🎯 [Key Findings]",
      "unusedFiles": "### [Unused Files]",
      "unusedFilesCount": "- **[Count]**: {{count}}",
      "potentialSavings": "- **[Potential Bundle Size Savings]**: {{size}}",
      "deadCode": "### [Dead Code]",
      "deadCodeCount": "- **[Count]**: {{count}}",
      "redundantApis": "### [Redundant APIs]",
      "redundantApisCount": "- **[Count]**: {{count}}",
      "fileAnalysis": "## 🗂️ [File Analysis]",
      "unusedFilesSection": "### [Unused Files] ({{count}})",
      "deadCodeSection": "### [Dead Code] ({{count}})",
      "apiAnalysis": "## 🔌 [API Analysis]",
      "unusedApisSection": "### [Unused APIs] ({{count}})",
      "recommendations": "## 💡 [Recommendations]",
      "dependencyGraph": "## 🏗️ [Dependency Graph]",
      "entryPoints": "### [Entry Points]",
      "orphanedComponents": "### [Orphaned Components] ({{count}})",
      "circularDependencies": "### [Circular Dependencies] ({{count}})",
      "cycle": "#### [Cycle] {{index}}",
      "safeDeletions": "## 📈 [Safe Deletions]",
      "safeDeletionsDescription": "[The following files can be safely deleted with high confidence:]",
      "generatedBy": "*[Report generated by Next.js Analyzer on] {{date}}*"
    },
    "health": {
      "title": "## 🏥 [Next.js Project Health Score:] {{score}}/100",
      "strengths": "### ✅ [Strengths]",
      "improvements": "### 🔧 [Areas for Improvement]",
      "routingPatterns": "### 🛤️  [Advanced Routing Patterns]",
      "ecosystemPackages": "### 📦 [Next.js Ecosystem Packages]",
      "setupIssues": "### ⚠️  [Setup Issues & Recommendations]",
      "criticalIssues": "#### 🚨 [Critical Issues] ({{count}})",
      "warnings": "#### ⚠️  [Warnings] ({{count}})",
      "optimizationOpportunities": "#### ℹ️  [Optimization Opportunities] ({{count}})",
      "recommendations": "[Recommendations:]"
    },
    "bundle": {
      "title": "## 📦 [Bundle Size Analysis]",
      "currentImpact": "### [Current Bundle Impact]",
      "totalBundleSize": "- **[Total Bundle Size]**: {{size}}",
      "gzippedSize": "- **[Gzipped Size]**: {{size}}",
      "unusedCodeSize": "- **[Unused Code Size]**: {{size}} ({{percentage}}% [of total])",
      "potentialSavings": "### [Potential Savings]",
      "rawSizeReduction": "- **[Raw Size Reduction]**: {{size}}",
      "gzippedReduction": "- **[Gzipped Reduction]**: {{size}}",
      "bundleSizeImprovement": "- **[Bundle Size Improvement]**: {{percentage}}%",
      "topUnusedModules": "### [Top Unused Modules by Size]",
      "noUnusedModules": "_[No unused modules detected.]_",
      "optimizationRecommendations": "### [Bundle Optimization Recommendations]",
      "noRecommendations": "_[No specific bundle recommendations available.]_"
    },
    "tables": {
      "fileTableHeaders": "| [File] | [Type] | [Confidence] | [Reasons] |",
      "fileTableSeparator": "|------|------|------------|---------|",
      "apiTableHeaders": "| [API Path] | [Methods] | [File] | [Confidence] | [Reasons] |",
      "apiTableSeparator": "|----------|---------|------|------------|---------|",
      "routingPatternHeaders": "| [Pattern Type] | [Path] | [Purpose] | [Status] |",
      "routingPatternSeparator": "|--------------|------|---------|--------|",
      "packageHeaders": "| [Package] | [Version] | [Setup Status] | [Purpose] |",
      "packageSeparator": "|---------|---------|--------------|---------|",
      "noFilesFound": "_[No files found in this category.]_",
      "noApisFound": "_[No APIs found in this category.]_"
    },
    "csv": {
      "headers": {
        "type": "[Type]",
        "path": "[Path]",
        "usageCount": "[UsageCount]",
        "classification": "[Classification]",
        "confidence": "[Confidence]",
        "reasons": "[Reasons]"
      }
    }
  },
  "status": {
    "complete": "✅",
    "partial": "⚠️",
    "missing": "❌",
    "misconfigured": "🔧",
    "unknown": "❓",
    "valid": "✅",
    "invalid": "❌"
  },
  "mcp": {
    "server": {
      "starting": "🚀 [Starting MCP HTTP Server with v2025-03-26 standards...]",
      "running": "✅ [MCP Server running on] http://localhost:{{port}}",
      "modernEndpoint": "🔗 [Modern endpoint:] http://localhost:{{port}}/mcp",
      "legacyEndpoint": "🔗 [Legacy endpoint:] http://localhost:{{port}}/sse",
      "protocol": "📋 [Protocol: v2025-03-26 with backwards compatibility]",
      "security": "🛡️  [Security:] {{status}}",
      "cors": "🌐 [CORS: Enabled for browser clients]",
      "clientConnecting": "📡 [Legacy SSE client connecting (deprecated)]",
      "startingStdio": "🚀 [Starting MCP Server with stdio transport...]",
      "readyStdio": "✅ [MCP Server ready on stdio transport]"
    }
  }
}

Replace all [text] placeholders with your translations.

Submission Process

Fork the repository on GitHub
Create a new branch for your translation: git checkout -b add-spanish-translation
Add your locale file to src/i18n/locales/
Test your translation thoroughly
Submit a pull request with:
- Clear title: "Add [Language] translation support"
- Description of what you translated
- Any cultural notes or context

Translation Quality

We value high-quality translations that:

Sound natural to native speakers
Maintain technical accuracy
Are consistent throughout
Follow the established tone (professional but friendly)

Maintenance

Translations may need updates when:

New features are added
Existing messages change
Community feedback suggests improvements

We'll tag translation contributors when updates are needed.

Questions?

GitHub Discussions: Ask questions about specific translations
Issues: Report problems with existing translations
Discord/Slack: Real-time help with translation work

Thank you for helping make VibeAlive accessible to developers worldwide! 🌍

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Internationalization (i18n) Guide

Supported Languages

Using Different Languages

CLI Usage

Configuration File

Environment Detection

Contributing Translations

1. Create a New Locale File

2. Translation Structure

3. Translation Guidelines

Preserve Formatting

Variable Interpolation

Context-Aware Translation

Consistent Terminology

4. Testing Your Translation

5. Translation Template

Submission Process

Translation Quality

Maintenance

Questions?

FilesExpand file tree

i18n.md

Latest commit

History

i18n.md

File metadata and controls

Internationalization (i18n) Guide

Supported Languages

Using Different Languages

CLI Usage

Configuration File

Environment Detection

Contributing Translations

1. Create a New Locale File

2. Translation Structure

3. Translation Guidelines

Preserve Formatting

Variable Interpolation

Context-Aware Translation

Consistent Terminology

4. Testing Your Translation

5. Translation Template

Submission Process

Translation Quality

Maintenance

Questions?