Translation Navigator

The ultimate smart translation key navigator for VS Code with inline editing, bulk editing, coverage reports, multi-format support, and intelligent file proximity sorting.

✨ Features Overview

🎯 Intelligent Translation Detection

• Hover tooltips - See all translations for a key across all locale files instantly
• Code snippets - View surrounding code context for each translation
• Proximity sorting - Translation files closest to your current file appear first
• Multi-format support - Works with TypeScript, JavaScript, JSON, and YAML files
• Configurable i18n libraries - Supports any translation function (t, i18n.t, $t, etc.)
• Ternary operator support - Recognizes t(condition ? 'key1' : 'key2')

✏️ Inline Editing

• Edit translations directly from the hover tooltip
• Bulk edit all locales - Edit the same key across all locale files at once
• Rename translation keys - Refactor keys across ALL files (locales + code) with one click
• Add missing translations without leaving your current file
• Auto-refresh - Tooltips update automatically after edits
• Smart cursor positioning - Cursor placed between quotes for easy editing

🔄 Rename Translation Keys (v1.1.0)

• Complete codebase refactoring - Updates both translation files AND code files
• Multi-format support - Works across .yml, .json, .ts, .js locale files
• Code file support - Updates .ts, .tsx, .js, .jsx, .vue, .svelte, .html, .erb, .haml, .slim
• All translation functions - Handles t(), $t(), i18n.t(), tNoPath(), tScope(), and custom functions
• Ternary operators - Properly renames keys in t(condition ? 'key1' : 'key2')
• Progress indicator - Shows search status while finding all usages
• Preview before applying - See all files to be modified with occurrence counts

📊 Translation Coverage Reports

• Coverage statistics - See percentage of translated keys per locale
• Visual reports - Beautiful webview panel with color-coded progress bars
• Missing translation lists - Easily identify which keys are missing
• Status bar indicator - Optional coverage percentage display

📦 Advanced Features

• Directory-specific settings - Restrict translation formats per directory (e.g., YAML in backend, TS in frontend)
• Intelligent file deduplication - Shows each locale once, preferring main files over nested ones
• File extension display - Tooltips show file format (.yml, .ts, .json) for each locale
• Enhanced table layout - Wider, more readable tooltips with proper spacing
• Scoped translations - Handles useTranslate('scope') patterns
• Nested keys - Supports deep nesting like brands.campaign.workflow.drawer.title
• Empty string deletion - Enter empty string to remove a translation
• YAML locale prefixes - Automatically handles Rails-style cs: root keys
• Custom file patterns - Configure your own glob patterns for translation files
• Regex escaping - Handles special characters in translation keys safely
• Cache management - Manual cache clearing command for force refresh

📦 Supported File Formats

🚀 Quick Start

Hover Over Translation Keys

Simply hover over any translation key in your code:

const { t } = useTranslate("brands.campaign");

<div>{t("title")}</div>  // <- Hover here!

View Translations

The hover tooltip shows:

• ✅ Existing translations with code snippets and edit/navigate links
• ❌ Missing translations with quick add links
• 📁 File paths (relative to workspace)
• 🔽 Show/Hide toggle for code snippets
• 📝 File format indicators (.yml, .ts, .json)

Edit or Add Translations

Click Edit or Add translation in the tooltip:

1. Input box appears with current value (for editing)
2. Type new translation
3. Press Enter
4. Tooltip refreshes automatically

Rename Translation Keys

To rename a key across your entire codebase:

1. Hover over the translation key
2. Click Rename Key in the tooltip
3. Enter the new key name
4. Review the list of files to be modified
5. Confirm to apply changes

What gets renamed:

• All locale files (en.yml, cs.ts, de.json, etc.)
• All code files using the key (.ts, .tsx, .js, .jsx, .vue, .svelte, .html, etc.)
• Handles all translation functions: t(), $t(), i18n.t(), and custom ones
• Works with ternary operators: t(condition ? 'oldKey' : 'otherKey')

Bulk Edit All Locales

When multiple translations exist, click Edit All Locales in the tooltip header to:

1. Select which locales to update (multi-select)
2. Enter new translation value
3. All selected locales update simultaneously

View Coverage Report

Run the Show Translation Coverage Report command to:

• See total translation keys across your project
• View percentage coverage per locale
• Identify all missing translations
• Color-coded progress bars (green ≥90%, orange ≥70%, red <70%)

📋 Commands

Access these commands via the Command Palette (Cmd+Shift+P / Ctrl+Shift+P):

⚙️ Configuration

⚙️ Configuration

Customize the extension behavior in VS Code settings (settings.json):

Directory-Specific Settings

Restrict translation file formats per directory. For example, use YAML in backend and TypeScript in frontend:

{
  "translationNavigator.directorySettings": [
    {
      "directory": "frontend/",
      "formats": ["ts", "js"],
      "enabled": true
    },
    {
      "directory": "backend/",
      "formats": ["yml", "yaml"],
      "enabled": true
    }
  ]
}

💡 Tip: Use the command "Configure Directory Settings" to set this up interactively.

File Patterns

Configure custom glob patterns for finding translation files:

{
  "translationNavigator.filePatterns": [
    "**/{locale}.{ts,js,json,yml,yaml}",
    "**/locales/{locale}.{yml,yaml}",
    "**/translations/{locale}.{ts,js,json}",
    "**/i18n/{locale}/**/*.{yml,yaml}"
  ]
}

Use {locale} as a placeholder for locale codes (e.g., en, cs, de, pt-BR).

Translation Functions

Support for any i18n library by configuring the function names:

{
  "translationNavigator.translationFunctions": [
    "t",
    "tNoPath",
    "tScope",
    "i18n.t",
    "$t",
    "translate",
    "_",
    "__"
  ]
}

Exclude Patterns

Skip certain directories from being scanned:

{
  "translationNavigator.excludePatterns": [
    "**/node_modules/**",
    "**/dist/**",
    "**/build/**",
    "**/.git/**",
    "**/coverage/**"
  ]
}

Additional Settings

{
  // Enable/disable automatic translation (coming soon)
  "translationNavigator.autoTranslate": false,

  // Translation service (coming soon)
  "translationNavigator.translationService": "none",

  // Show coverage percentage in status bar
  "translationNavigator.showCoverageInStatusBar": false
}

🎯 Usage Examples

TypeScript/JavaScript

// en.ts
export const en = {
  brands: {
    campaign: {
      title: "Campaign Title",
      description: "Campaign Description"
    }
  }
};

// Usage in code
const { t } = useTranslate("brands.campaign");
<div>{t("title")}</div>  // Hover shows all translations!

JSON

{
  "brands": {
    "campaign": {
      "title": "Campaign Title",
      "description": "Campaign Description"
    }
  }
}

YAML (Rails-style)

en:
  brands:
    campaign:
      title: Campaign Title
      description: Campaign Description

Ternary Operators

// The extension recognizes both keys!
<Button>
  {t(saveDisabled ? 'save_disabled_tooltip' : 'save_tooltip')}
</Button>

Scoped Translations

const { t } = useTranslate('brands.campaign');

// Hover over "title" shows translations for "brands.campaign.title"
<h1>{t('title')}</h1>

📊 File Detection

The extension automatically finds translation files across your entire workspace matching these patterns:

Default Pattern:

<locale>.<extension>

Examples:

• en.js, cs.yml, de.json, fr.ts, pt-BR.yaml

Supported Locale Codes:

• 2-letter ISO 639-1 codes: en, cs, de, fr, es, pt, etc.
• Region variants: en-US, pt-BR, zh-CN, fr-CA, etc.

⚡ Performance

• � File caching - Files are cached in memory with modification time checking
• ⚡ Fast lookups - O(1) object lookups for JSON/YAML files
• 💾 Workspace scanning cache - Translation file list cached for 30 seconds
• 🎯 Smart proximity sorting - Files closer to your current file appear first
• 🔄 Automatic cache invalidation - Cache clears when files are saved, created, or deleted
• 🧹 Manual cache clearing - Use "Clear Translation Cache" command when needed

🧪 Testing

The extension includes a comprehensive test suite:

# Run all tests
pnpm test

# Compile TypeScript
pnpm run compile

# Run linter
pnpm run lint

# Watch mode for development
pnpm run watch

Test Coverage:

• ✅ 35 tests passing
• ✅ Cache functionality
• ✅ File parsers (YAML, JSON, TS, JS)
• ✅ Translation key extraction
• ✅ Rename operations

📋 Requirements

• VS Code: 1.80.0 or higher
• Node.js: 22.0.0 or higher (for development)
• Package Manager: pnpm 9.15.0 or higher (for development)

🐛 Known Issues

None at this time. Please report issues on GitHub.

📝 Release Notes

1.1.0 - Enhanced Translation Management 🚀

Major Features:

• 🔄 Enhanced Rename Translation Key - Now updates BOTH translation files AND all code files

  • Supports ALL translation functions: t(), $t(), i18n.t(), custom functions
  • Handles ternary operators: t(condition ? 'key1' : 'key2')
  • Works across .ts, .tsx, .js, .jsx, .vue, .svelte, .html, .erb, .haml, .slim
  • Shows progress indicator and file preview before applying

• 📁 Directory-Specific Settings - Configure translation formats per directory

• 🗑️ Clear Translation Cache - New manual cache clearing command

Critical Bug Fixes:

• ✅ Fixed $t() function not being detected (proper $ escaping)
• ✅ Fixed ternary operators not working (extract all string literals)
• ✅ Fixed TypeScript files showing as "Missing" (removed URL-breaking regex)
• ✅ Fixed YAML file parsing (proper nested object extraction)
• ✅ Enhanced cache invalidation (automatic + manual clearing)

See CHANGELOG.md for complete details.

1.0.0 - Initial Release

• Smart hover tooltips with code snippets
• Inline editing and adding translations
• Multi-format support (TS, JS, JSON, YAML)
• Translation coverage reports
• Bulk editing across locales
• Auto-refreshing tooltips
• Performance optimizations

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• Repository: github.com/volajmaerik/Translation-Navigator
• Issues: github.com/volajmaerik/Translation-Navigator/issues
• Marketplace: Coming soon!

💡 Tips & Tricks

Quickly Navigate Between Locales

Use the Go to definition link in tooltips to jump directly to translation files.

Fix Typos in Translation Keys

Use Rename Translation Key to fix typos everywhere at once instead of manually finding and replacing.

Keep Cache Fresh

If translations aren't updating, use Clear Translation Cache command to force a refresh.

Organize by Directory

Use Directory-Specific Settings to enforce format conventions (e.g., YAML in backend, TS in frontend).

Bulk Updates

Use Edit All Locales to update the same message across all languages simultaneously.

Made with ❤️ for the i18n community