JC Translate Peek | Translate Without Breaking Your Flow

Read and translate code snippets or documentation without losing focus in your editor.

Purpose and Motivation

During daily programming and technical writing, there is a frequent need to translate words or sentences from English to Portuguese. Typically, this requires leaving VS Code to open a browser or an external tool, which breaks the reading flow and distracts from the current task.

To address this problem, this project was created: to select a word or phrase and immediately view the translation alongside the original text without modifying the file.

During development, several existing extensions were tested but did not meet the required usability. The initial implementation used the Google Translate API. While functional, it occasionally failed with HTTP 429 errors (Too Many Requests) due to the strict rate limits of the free public API. Consequently, a Fallback mechanism to OpenRouter was implemented. OpenRouter provides free LLM (AI) requests, ensuring service continuity and enabling context-aware translations.

Features

• Read-only Translation: Translate text and view it in a side panel without modifying the source file.
• Smart Fallback System: Attempts Google first. If it fails, automatically falls back to OpenRouter (AI).
• Security (SecretStorage): API keys are not exposed. They are stored encrypted in the operating system's credential vault.
• Local Cache: Repeated translations are instantaneous and save network calls.

Usage

1. Select the text in your file.
2. Press Ctrl+Alt+T (or Cmd+Alt+T on Mac), or right-click and select Translate Selection (Peek).
3. The panel will open on the right with the translation. The footer will display the provider used (Google, OpenRouter, or Cache).

How to Change the Target Language

By default, the extension translates text into Portuguese. If you need to translate to another language, follow these steps:

1. Press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (macOS) to open the Command Palette.
2. Type JC Translate Peek: Select Target Language and select it.
3. A list of supported languages will appear at the top of the screen (e.g., English, Spanish, French).
4. Click on your desired language.

Example: If you select "English", the next time you select a Portuguese text and press Ctrl+Alt+T, the side panel will show the translation in English.

The extension will remember this choice globally, so you only need to set it once.

Configuring the OpenRouter API Key

To ensure the extension continues to function if Google blocks requests, configure your free OpenRouter API key:

1. Create an account at openrouter.ai and generate an API Key.
2. In VS Code, press Ctrl+Shift+P.
3. Search for JC Translate Peek: Set OpenRouter API Key.
4. Paste the key. It will be securely saved in your operating system.

Technical Documentation

For details on architecture and security decisions, refer to the docs/ folder:

• Architecture and Diagrams (ADR)
• Security and Privacy Policies

Roadmap (Future Implementations)

The project is under active development. The next milestones include:

• Inline Hover Translation: Display translations in a hover tooltip over the selected text, eliminating the need to open the side panel for quick checks.
• Custom Prompt Configuration: Allow users to define custom prompts for the OpenRouter LLM (e.g., "Explain this code" instead of just translating).
• Markdown Structure Preservation: Enhance the formatting engine to preserve tables, lists, and code blocks when translating entire Markdown files.
• Multi-Provider Support: Add native support for other translation APIs (DeepL, Azure Translator).

Contributing

Issues and Pull Requests are welcome. The project uses GitHub Actions to automatically validate the code (TypeScript).

License

Distributed under the MIT License. See LICENSE for more information.

Author

Jacivaldo Carvalho

Telecommunications Engineer | DevOps Engineer | SRE | Networking

GitHub | LinkedIn | Website