Localization and Translations

Relevant source files

The following files were used as context for generating this wiki page:

• locales/en.json
• fill_missing_translations.py
• main.py
• config.py
• locales/fr.json
• locales/de.json
• totally_reset_cursor.py

The localization and translation system in cursor-free-vip is designed to provide multi-language support for the application's command-line interface. It uses a set of JSON files to store language strings, a central Translator class to manage and serve these strings, and a configuration file to control language settings. The system is extensible, with a dedicated script to help maintain and add new translations by automatically filling in missing text using an external translation service.

The core of the system is the Translator class, which is instantiated at startup. It detects the user's system language or uses a configured language, loads the corresponding translation file, and provides a simple method to retrieve translated strings. This translator instance is then passed to various modules to ensure all user-facing text is displayed in the selected language.

Architecture Overview

The localization system is composed of several key components that work together to deliver translated content to the user. The main.py script initializes the Translator class, which reads settings from the config.ini file (managed by config.py). The Translator then loads the appropriate language file from the locales directory. Other modules receive the translator instance to request and display localized strings. The fill_missing_translations.py script is a standalone utility for developers to maintain the language files.

This diagram illustrates the high-level architecture of the translation system.

The Translator Class

The Translator class is the central component responsible for managing all aspects of translation at runtime. It is defined in main.py.

Sources: main.py:82-255

This class diagram shows the structure and methods of the Translator class.
Sources: main.py:82-255

Initialization (__init__)

When a Translator object is created, it performs the following steps:

1. Reads the application configuration using get_config().
2. Determines the fallback_language from the configuration, defaulting to en.
3. Checks the configuration for a current_language. If not set, it calls detect_system_language() to determine the language and saves it back to the configuration.
4. Calls load_translations() to load all available language files from the locales/ directory into the self.translations dictionary.

Sources: main.py:84-111

Language Detection

The system attempts to automatically detect the user's language if one is not explicitly configured.

• On Windows: It uses the ctypes library to call the user32.GetKeyboardLayout function to get the active keyboard layout ID and maps it to a language code.
  Sources: main.py:119-144
• On Unix-like systems (Linux/macOS): It uses the locale.getlocale() function to get the system's locale setting (e.g., en_US.UTF-8). It also checks the LANG environment variable as a fallback.
  Sources: main.py:146-193

Translation Retrieval (get)

The get(key, **kwargs) method is the primary way modules retrieve translated strings.

1. It takes a key in dot-notation (e.g., reset.title).
2. It first attempts to find the key in the current_language dictionary.
3. If the key is not found, it falls back to the fallback_language (typically 'en').
4. If the key is still not found, it returns the key itself.
5. It supports string formatting by passing keyword arguments.
6. It includes special handling for Arabic (ar) to ensure correct right-to-left display using the arabic_reshaper and bidi libraries.

The following sequence diagram shows the process of a module requesting a translated string.

Language Configuration

Language settings are managed in the config.ini file, located in the user's Documents/.cursor-free-vip directory. The schema for this configuration is defined in config.py.

Sources: config.py:78-83

Section	Key	Description	Default Value
Language	current_language	The language to use. If empty, the system language is detected automatically.	'' (empty string)
Language	fallback_language	The language to use if a translation key is missing in the current language.	en
Language	auto_update_languages	Controls whether to automatically update language files (functionality deprecated).	True
Language	language_cache_dir	Directory for caching language files (functionality deprecated).	.../.cursor-free-vip/language_cache

Sources: config.py:78-83

Translation Files

All translation strings are stored in JSON files within the locales/ directory. The English file, en.json, serves as the source of truth for all translations.

Sources: locales/en.json, locales/fr.json, locales/de.json

File Format

The JSON files use a nested object structure. Keys can be accessed using a dot-separated path.

Example from locales/en.json:

{
    "reset": {
        "title": "Cursor Machine ID Reset Tool",
        "checking": "Checking Config File",
        "not_found": "Config File Not Found",
        "no_permission": "Cannot Read or Write Config File, Please Check File Permissions",
        "reading": "Reading Current Config",
        "creating_backup": "Creating Config Backup",
        "success": "Machine ID Reset Successfully",
        "new_id": "New Machine ID"
    }
}

To access the title, the key reset.title would be used.
Sources: locales/en.json:36-45

Supported Languages

The repository includes files for several languages, including:

• en.json (English)
• fr.json (French)
• de.json (German)
• zh_cn.json (Simplified Chinese)
• zh_tw.json (Traditional Chinese)
• And others as seen in the locales directory and LANGUAGE_MAPPING.

Sources: locales/en.json, locales/fr.json, locales/de.json, fill_missing_translations.py:28-48

Translation Management Script

The fill_missing_translations.py script is a utility designed to help developers maintain and expand language support. It automates the process of finding and translating missing keys.

Sources: fill_missing_translations.py

Workflow

The script follows this process when run:

1. It presents an interactive menu to the user to select a target language file to update or to update all existing files.
2. It loads the source en.json file and the chosen target language file (e.g., fr.json).
3. It recursively scans both files to build a set of all keys.
4. It identifies keys that exist in en.json but are missing from the target file.
5. For each missing key, it submits the English text to a translation service. It uses a web scraping method as a fallback to Google Translate's API.
6. The translated text is inserted into the target language's JSON data structure.
7. The user is prompted to create a backup of the original target file.
8. The updated JSON object is written back to the target language file with proper formatting.

This flowchart visualizes the translation update process.

Language Mapping

The script uses a LANGUAGE_MAPPING dictionary to map the project's language codes (e.g., zh_cn) to the codes expected by the Google Translate service (e.g., zh-CN). This ensures correct translation direction.

# From fill_missing_translations.py
LANGUAGE_MAPPING = {
    "zh_cn": "zh-CN",  # Simplified Chinese
    "zh_tw": "zh-TW",  # Traditional Chinese
    "ar": "ar",        # Arabic
    "de": "de",        # German
    "en": "en",        # English
    "es": "es",        # Spanish
    "fr": "fr",        # French
    # ... and more
}

Sources: fill_missing_translations.py:28-48

Summary

The localization system is a well-structured feature of cursor-free-vip. It effectively decouples text strings from the application logic by using external JSON files. The Translator class provides a robust, centralized service for language detection and string retrieval, complete with fallback and special text handling. Furthermore, the fill_missing_translations.py script provides essential tooling that simplifies the maintenance and expansion of language support, making the project more accessible to a global audience.