Internationalization (i18n) Guide¶

This guide explains how to add new language support to the SSH Tunnel Manager web panel.

How to Add a New Language¶

Step 1: Create Language Resource File¶

1. Navigate to the web/static/locales/ directory

2. Create a new JSON file named with the language code (e.g., fr.json for French, de.json for German)

3. Copy the structure from en.json and translate all the values

Step 2: Language File Structure¶

The language file should follow this structure:

{
  "app": {
    "title": "Your translation here",
    "name": "Your translation here",
    "help_title": "Your translation here"
  },
  "navigation": {
    "help": "Your translation here",
    "docker_hub": "Docker Hub",
    "github": "GitHub",
    "back": "Your translation here"
  }
  // ... continue with all sections
}

Step 3: Update Language Support¶

1. Open web/static/i18n.js

2. Find the getSupportedLanguages() method

3. Add your language to the array:

getSupportedLanguages() {
    return [
        { code: 'en', name: 'English' },
        { code: 'zh', name: '中文' },
        { code: 'fr', name: 'Français' }, // Add your language here
        // ... other languages
    ];
}

1. Update the language validation in the switchLanguage() method:

if (!["en", "zh", "fr"].includes(lang)) {
  // Add your language code here
  console.error(`Unsupported language: ${lang}`);
  return false;
}

Step 4: Test Your Translation¶

1. Start the application

2. Use the language toggle button to switch to your new language

3. Verify that all text is properly translated

4. Check both the main page and help page

Translation Guidelines¶

Consistency¶

Use consistent terminology throughout the translation. Create a glossary of key terms if needed.

Context¶

Consider the context in which text appears:

• Buttons: Keep text short and action-oriented
• Labels: Be descriptive but concise
• Messages: Provide clear feedback to users
• Help text: Be thorough and helpful

Length¶

Keep translations reasonably similar in length to avoid UI layout issues. If a translation is significantly longer, consider:

• Using abbreviations
• Rephrasing for brevity
• Testing the UI to ensure it still looks good

Technical Terms¶

Some technical terms should remain in English:

• SSH
• Docker
• YAML
• API
• CLI
• Hash

Placeholders¶

Preserve placeholder formats in your translations:

{
  "messages": {
    "tunnel_started": "Tunnel {{name}} started successfully"
  }
}

The {{name}} placeholder must remain unchanged.

Common Translation Keys¶

Currently Supported Languages¶

Submitting Your Translation¶

1. Fork the repository

2. Create a new branch for your translation:

   git checkout -b add-german-translation
   

3. Add your language file to web/static/locales/

4. Update web/static/i18n.js to include your language

5. Test your translation thoroughly

6. Submit a pull request with:

7. Clear description of the language added
8. Confirmation that all strings are translated
9. Any notes about translation choices

Testing Translations¶

Manual Testing Checklist¶

• [ ] All text on main page is translated
• [ ] All text on help page is translated
• [ ] Button tooltips are translated
• [ ] Error messages are translated
• [ ] Success messages are translated
• [ ] Placeholder text is translated
• [ ] Language persists after page refresh
• [ ] No layout issues with translated text

Browser Testing¶

Test in multiple browsers:

• Chrome
• Firefox
• Safari
• Edge

Mobile Testing¶

Verify translations display correctly on mobile devices.

Updating Existing Translations¶

If you find errors or want to improve existing translations:

1. Edit the appropriate language file in web/static/locales/

2. Test your changes

3. Submit a pull request with a description of what was changed and why

Questions¶

If you have questions about translations:

• Open an issue on GitHub
• Contact the maintainers

Thank you for helping make SSH Tunnel Manager accessible to more users worldwide!