Skip to content

I18N.md

Latest commit

 

History

History
191 lines (153 loc) · 5.15 KB

I18N.md

File metadata and controls

191 lines (153 loc) · 5.15 KB

Multi-Language System Documentation

Overview

This extension now supports multiple languages through a comprehensive localization system. Currently, it includes built-in support for English (en) and Spanish (es), with the ability for users to add custom translations.

Structure

Translation Files

resources/locales/
├── en.json      # English translations
└── es.json      # Spanish translations

Each file contains organized translation keys grouped by category:

  • commands: Command titles and labels
  • messages: User notifications and dialog messages
  • placeholders: Input box placeholders

Configuration

Language preferences and custom translations are stored in:

~/.config/remote-dev/localization.json

This file contains:

{
  "language": "en",
  "customTranslations": {
    "messages": {
      "customKey": "Your custom translation"
    }
  }
}

Usage in Code

Getting Translations

import LocalizationManager from './controllers/localization.controller';

const i18n = LocalizationManager.getInstance();

// Simple translation
const message = i18n.t('messages.fileDeleted');

// Translation with variable substitution (supports {0}, {1}, etc.)
const message = i18n.t('messages.fileDeleted', filename);
const message = i18n.t('messages.ftpConnectionError', protocol, errorMessage);

Initialization

The LocalizationManager must be initialized early in the extension's activation:

// In extension.ts
await LocalizationManager.getInstance().init(context);

User Features

Changing Language

Users can change the language using the Change Language command:

  1. Open Command Palette (Cmd+Shift+P)
  2. Search for "Change Language"
  3. Select the desired language from the quick pick menu

Creating Custom Translations

Users can add custom translations by:

  1. Running the Change Language command
  2. Selecting Edit Custom Translations
  3. Adding keys and values in the JSON format

Example custom translation:

{
  "messages": {
    "myCustomMessage": "This is my custom translation"
  }
}

Adding New Translations

Step 1: Add to Translation Files

Edit resources/locales/en.json and resources/locales/es.json:

{
  "messages": {
    "newFeatureMessage": "New feature message in English"
  }
}

Step 2: Use in Code

const i18n = LocalizationManager.getInstance();
vscode.window.showInformationMessage(i18n.t('messages.newFeatureMessage'));

Translation Key Convention

  • Category: commands, messages, placeholders
  • Format: camelCase for sub-keys
  • Variables: Use {0}, {1}, etc. for substitution

Example:

{
  "messages": {
    "errorConnectingServer": "Error connecting to server: {0}",
    "fileDeleted": "File deleted: {0}"
  }
}

Custom Translation Support

Custom translations are merged with default translations and take precedence. This allows users to:

  • Override existing translations
  • Add translations for custom features
  • Contribute new language translations

Loading Custom Translations

  1. Place custom translations in ~/.config/remote-dev/custom-translations.json
  2. The system will automatically merge them with default translations
  3. Restart the extension for changes to take effect

Language Detection

The system detects language automatically based on:

  1. Saved preference in localization.json
  2. Falls back to English if not set

Adding a New Language

To add a new language:

  1. Create resources/locales/{languageCode}.json with all keys from English
  2. Update LanguageController to include the new language in the quick pick menu
  3. Update the LocalizationManager type definitions if needed

Example:

// In language.controller.ts
const quickPickItems = [
    {
        label: 'English',
        language: 'en' as const,
    },
    {
        label: 'Español',
        language: 'es' as const,
    },
    {
        label: 'Français',  // New language
        language: 'fr' as const,
    },
];

Fallback Behavior

  • If a translation key is not found in the current language, the key path is returned
  • If a language file is missing, the system falls back to English
  • Custom translations are checked before falling back

Best Practices

  1. Always use the i18n system for user-facing strings
  2. Keep keys organized by category (commands, messages, placeholders)
  3. Use meaningful key names that describe the message
  4. Add variables for dynamic content instead of string concatenation
  5. Test with multiple languages to ensure UI doesn't break

Troubleshooting

Translations Not Appearing

  • Verify the key path is correct in the translation file
  • Check that the language file is in resources/locales/
  • Ensure the extension is restarted after changing translations
  • Check for typos in the key name

Custom Translations Not Working

  • Verify the custom-translations.json file is in the correct location
  • Ensure the JSON syntax is valid
  • Restart the extension after editing

Missing Language Files

  • If a language file is missing, the system logs an error and falls back to English
  • Check the VS Code output channel for error messages