Svelte i18n Helper

A powerful Visual Studio Code extension to manage translations in Svelte applications.

Features

This extension provides a comprehensive set of tools to help you manage translations in your Svelte project:

🌍 Translations Explorer

Access all your translations from a dedicated sidebar. The translations explorer is organized by:

• Locales (languages)
• Namespaces (nested translation keys)
• Translation keys and values

🔍 Intelligent Code Features

• Hover Previews: See translations across all locales when hovering over translation keys in your code
• Auto-completion: Get suggestions for existing translation keys as you type
• Diagnostics: Automatically detect missing translations in your codebase
• Extract Text: Select text in your code and extract it to a translation key with a single command

⚡ Powerful Management Tools

• Search Translations: Quickly find translation keys and values
• Filter by Current File: Show only translations used in your active file
• Find References: Locate where translation keys are used in your codebase
• Edit Translations: Dedicated editor for managing strings, plural forms, and complex translations
• Add, Rename, Delete: Comprehensive key management with reference updates

Getting Started

Installation

1. Install the extension from the VS Code Marketplace
2. Open your Svelte project
3. Access the Translations Explorer from the activity sidebar

Configuration

Configure the extension in your VS Code settings:

{
  "svelte-phraselink.translationsPath": "src/translations", // Path to translations directory
  "svelte-phraselink.baseLocale": "en", // Your base/source locale
  "svelte-phraselink.translationFunction": "t", // Name of your translation function
  "svelte-phraselink.autoDetectTranslations": true, // Auto-refresh on file changes
  "svelte-phraselink.allowHyphenInKeys": true // Allow hyphens in translation keys
}

Usage Guide

Working with Translations

Browsing Translations

Open the Translations panel from the activity sidebar and expand locales to view your translation hierarchy.

Adding New Translations

1. Click the "+" icon in the Translations Explorer header
2. Enter the new translation key (supports dot notation like "common.buttons.save")
3. Provide the translation value for your base locale

Editing Translations

1. Click on a translation in the Translations Explorer
2. Edit the value in the input box or editor
3. Press Enter to save

Finding Translations

1. Click the search icon in the Translations Explorer header
2. Type your search query to filter keys and values

Filtering by Current File

1. Click the filter icon in the Translations Explorer header
2. The view will update to show only translations used in your current file

Finding References

1. Right-click on a translation in the explorer
2. Select "Find References to Translation Key"
3. Choose from the list of files that use this key

Working with Code

Extracting Text to Translation

1. Select text in your code
2. Right-click and select "i18n: Extract String to Translation Key" or use the Command Palette
3. Enter a translation key name
4. The text will be added to your translations and replaced with a translation function call

Seeing Translation Details

Hover over any translation key in your code to see:

• Values across all locales
• Edit link for quick updates

Getting Key Suggestions

As you type your translation function (e.g., t('), the extension will suggest available keys.

Commands

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

• i18n: Show Translations Explorer - Open the translations panel
• i18n: Extract String to Translation Key - Convert selected text to a translation key
• i18n: Refresh Translations - Reload all translation files
• i18n: Add New Translation Key - Create a new translation
• i18n: Search Translations - Find translations by key or value
• i18n: Show Only Translations Used in Current File - Filter to current file
• i18n: Edit Translation - Modify a translation value
• i18n: Rename Translation Key - Rename a key and update references
• i18n: Delete Translation Key - Remove a translation key
• i18n: Find References to Translation Key - Find where a key is used

Supported File Structure

The extension expects your translations to be organized in JSON files within your translations directory:

src/translations/
  ├── en.json       # Base locale
  ├── fr.json       # French translations
  ├── de.json       # German translations
  └── ...

Each file should contain key-value pairs representing your translations:

{
  "common": {
    "buttons": {
      "save": "Save",
      "cancel": "Cancel"
    },
    "messages": {
      "welcome": "Welcome to our app!"
    }
  },
  "home": {
    "title": "Home Page",
    "description": "This is the home page"
  }
}

Plural Forms Support

The extension supports plural forms following the ICU format:

{
  "items": {
    "count": {
      "zero": "No items",
      "one": "One item",
      "other": "{{count}} items"
    }
  }
}

Troubleshooting

Common Issues

Translations not showing up:

• Ensure your translations path is correct in settings
• Verify JSON files are valid and properly formatted
• Try the "Refresh Translations" command

Cannot edit translations:

• Check file permissions
• Ensure translation files are not open in other editors with unsaved changes

Missing diagnostics:

• Diagnostics run on file save, try saving your files
• Check that your translation function name matches the setting

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT