mindroot.coreplugins.l8n package - MindRoot 9.10.0 documentation

Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# mindroot.coreplugins.l8n package

## Submodules

## mindroot.coreplugins.l8n.debug_loader module

Debug script to simulate the plugin loader behavior.

## mindroot.coreplugins.l8n.debug_middleware module

Debug script to test middleware import and functionality.

## mindroot.coreplugins.l8n.l8n_constants module

## mindroot.coreplugins.l8n.language_detection module

mindroot.coreplugins.l8n.language_detection.get_current_language_from_request() → str

  Get the current language from various request sources.

  This function checks multiple sources in order of priority: 1. Environment variable MINDROOT_LANGUAGE 2. FastAPI request context (if available) 3. HTTP Accept-Language header 4. URL parameters (?lang=es) 5. Cookie values 6. User preferences from database/session

  Returns:

    Language code (e.g., ‘en’, ‘es’, ‘fr’)

mindroot.coreplugins.l8n.language_detection.get_fallback_language(language: str) → str

  Get a fallback language if the requested language is not supported.

  Parameters:

    language – Requested language code

  Returns:

    Fallback language code

mindroot.coreplugins.l8n.language_detection.get_supported_languages() → list

  Get the list of supported languages.

  Returns:

    List of supported language codes

mindroot.coreplugins.l8n.language_detection.is_language_supported(language: str) → bool

  Check if a language is supported.

  Parameters:

    language – Language code to check

  Returns:

    True if language is supported, False otherwise

mindroot.coreplugins.l8n.language_detection.set_language_for_request(language: str)

  Set the language for the current request context.

  This function would be called by middleware or route handlers to set the language for the current request.

  Parameters:

    language – Language code to set

## mindroot.coreplugins.l8n.middleware module

mindroot.coreplugins.l8n.middleware.detect_language_from_request(request: Request) → str

  Detect the preferred language from a FastAPI request.

  Checks multiple sources in order of priority: 1. URL parameter (?lang=es) 2. Cookie value (mindroot_language) 3. Accept-Language header 4. Environment variable 5. Default to ‘en’

  Parameters:

    request – FastAPI Request object

  Returns:

    Detected language code

mindroot.coreplugins.l8n.middleware.get_request_language() → str

  Get the language that was detected for the current request.

  This function is called by the monkey patch system to get the language for template translation.

  Returns:

    Language code for the current request

async mindroot.coreplugins.l8n.middleware.middleware(request: Request, call_next)

  L8n middleware for language detection and setting.

  This middleware runs early in the request pipeline to: 1. Detect the preferred language for the request 2. Store it globally for use by the template system 3. Set it in the request state for other components

  Parameters:

    - request – FastAPI Request object

    - call_next – Next middleware/handler in the chain

  Returns:

    Response from the next handler

## mindroot.coreplugins.l8n.mod module

async mindroot.coreplugins.l8n.mod.append_localized_file(original_path: str, content: str, context=None)

  Append content to an existing localized file.

  Use this for large files that need to be built incrementally. Follow the same placeholder format rules as write_localized_file.

  Parameters:

    - original_path – Absolute path to the original file

    - content – Content to append with __TRANSLATE_key__ placeholders

    - context – Command context (optional)

  Example

  # First write the beginning await write_localized_file(

  > “/path/to/large_template.jinja2”, “<html><head><title>__TRANSLATE_page_title__</title></head>”

  )

  # Then append more sections await append_localized_file(

  > “/path/to/large_template.jinja2”, “<body><h1>__TRANSLATE_main_heading__</h1></body></html>”

  )

async mindroot.coreplugins.l8n.mod.get_translations(original_path: str = None, language: str = None, context=None)

  Get translations for a specific plugin and language.

  Parameters:

    - original_path – Absolute path to a file in the plugin (optional) If not provided, returns all cached translations

    - language – Language code to get translations for (optional)

    - context – Command context (optional)

  Returns:

    Dictionary of translations

  Examples

  # Get all translations for a plugin translations = await get_translations(

  > “/files/mindroot/src/mindroot/coreplugins/chat/templates/chat.jinja2”

  )

  # Get Spanish translations for a plugin spanish = await get_translations(

  > “/files/mindroot/src/mindroot/coreplugins/chat/templates/chat.jinja2”, ‘es’

  )

  # Get all cached translations all_cached = await get_translations()

async mindroot.coreplugins.l8n.mod.list_localized_files(context=None)

  List all localized files that have been created.

  Returns:

    List of paths to localized files

mindroot.coreplugins.l8n.mod.save_plugin_translations(plugin_path: str, translations: dict)

  Save translations for a specific plugin to disk.

async mindroot.coreplugins.l8n.mod.set_translations(original_path: str, language: str, translations: dict, context=None)

  Set translations for a specific language and plugin.

  This command stores the translation mappings that will be used to replace __TRANSLATE_key__ placeholders in localized files. Translations are stored per plugin based on the provided file path.

  Parameters:

    - original_path – Absolute path to a file in the plugin (used to identify the plugin)

    - language – Language code (e.g., ‘en’, ‘es’, ‘fr’, ‘de’)

    - translations – Dictionary mapping translation keys to translated text

    - context – Command context (optional)

  Examples

  await set_translations(

    “/files/mindroot/src/mindroot/coreplugins/chat/templates/chat.jinja2”, ‘es’, {

    > ‘chat_title’: ‘Interfaz de Chat’, ‘buttons_send’: ‘Enviar Mensaje’, ‘nav_home’: ‘Inicio’, ‘error_connection_failed’: ‘Error de conexión’

    }

  )

  await set_translations(

    “/some/path/src/my_plugin/templates/dashboard.jinja2”, ‘fr’, {

    > ‘dashboard_welcome’: ‘Bienvenue au Tableau de Bord’, ‘buttons_save’: ‘Enregistrer’, ‘nav_home’: ‘Accueil’

    }

  )

async mindroot.coreplugins.l8n.mod.write_localized_file(original_path: str, content: str, context=None)

  Write a localized version of a file with static placeholders.

  This command creates a localized version of a template or source file with __TRANSLATE_key__ placeholders that will be replaced with actual translations when the file is loaded.

  PLACEHOLDER FORMAT RULES: - Always use the exact format: __TRANSLATE_key_name__ - Must start with __TRANSLATE_ and end with __ - Use lowercase letters, numbers, and underscores only for the key name - Use descriptive, hierarchical key names like section_element or buttons_save - NO spaces, hyphens, or special characters in key names

  Parameters:

    - original_path – Absolute path to the original file

    - content – File content with __TRANSLATE_key__ placeholders

    - context – Command context (optional)

  Examples

  await write_localized_file(

    “/files/mindroot/src/mindroot/coreplugins/chat/templates/chat.jinja2”, “<h1>__TRANSLATE_chat_title__</h1><button>__TRANSLATE_buttons_send__</button>”

  )

  await write_localized_file(

    “/some/path/src/my_plugin/templates/dashboard.jinja2”, “<div>__TRANSLATE_dashboard_welcome__</div>”

  )

## mindroot.coreplugins.l8n.monkey_patch_to_delete module

## mindroot.coreplugins.l8n.test_enhanced module

Enhanced test script for the l8n localization plugin with language detection.

async mindroot.coreplugins.l8n.test_enhanced.main()

  Run all enhanced tests.

async mindroot.coreplugins.l8n.test_enhanced.test_file_integration()

  Test creating localized files and using language detection.

async mindroot.coreplugins.l8n.test_enhanced.test_integrated_translation()

  Test the integrated translation system with language detection.

async mindroot.coreplugins.l8n.test_enhanced.test_language_detection()

  Test the enhanced language detection functionality.

## mindroot.coreplugins.l8n.test_l8n module

## mindroot.coreplugins.l8n.test_l8n_standalone module

Standalone test script for the l8n localization plugin.

This script tests the core functionality without MindRoot dependencies.

async mindroot.coreplugins.l8n.test_l8n_standalone.append_localized_file(original_path: str, content: str, context=None)

  Append content to an existing localized file.

mindroot.coreplugins.l8n.test_l8n_standalone.command()

mindroot.coreplugins.l8n.test_l8n_standalone.extract_plugin_root(absolute_path: str) → str

  Extract the plugin root from an absolute path.

mindroot.coreplugins.l8n.test_l8n_standalone.get_localized_file_path(original_path: str) → Path

  Convert an original file path to its localized version path.

async mindroot.coreplugins.l8n.test_l8n_standalone.get_translations(language: str = None, context=None)

  Get translations for a specific language or all languages.

async mindroot.coreplugins.l8n.test_l8n_standalone.list_localized_files(context=None)

  List all localized files that have been created.

mindroot.coreplugins.l8n.test_l8n_standalone.replace_placeholders(content: str, language: str) → str

  Replace __TRANSLATE_key__ placeholders with actual translations.

async mindroot.coreplugins.l8n.test_l8n_standalone.set_translations(language: str, translations: dict, context=None)

  Set translations for a specific language.

async mindroot.coreplugins.l8n.test_l8n_standalone.test_basic_functionality()

  Test the basic l8n functionality.

async mindroot.coreplugins.l8n.test_l8n_standalone.write_localized_file(original_path: str, content: str, context=None)

  Write a localized version of a file with static placeholders.

## mindroot.coreplugins.l8n.test_middleware module

Test script for the l8n middleware functionality.

This script simulates FastAPI request objects to test the middleware.

class mindroot.coreplugins.l8n.test_middleware.MockRequest(path='/', query_params=None, cookies=None, headers=None)

  Bases: `object`

class mindroot.coreplugins.l8n.test_middleware.MockResponse

  Bases: `object`

  set_cookie(key, value, max_age=None, httponly=None, samesite=None)

async mindroot.coreplugins.l8n.test_middleware.main()

  Run all middleware tests.

async mindroot.coreplugins.l8n.test_middleware.mock_call_next(request)

  Mock the next handler in the middleware chain.

async mindroot.coreplugins.l8n.test_middleware.test_integration_with_templates()

  Test integration with the template system.

async mindroot.coreplugins.l8n.test_middleware.test_language_detection()

  Test language detection from various request sources.

async mindroot.coreplugins.l8n.test_middleware.test_middleware_functionality()

  Test the complete middleware functionality.

## mindroot.coreplugins.l8n.utils module

mindroot.coreplugins.l8n.utils.extract_plugin_root(absolute_path: str) → str

  Extract the plugin root from an absolute path.

  For core plugins: everything after ‘coreplugins/’ For external plugins: everything after ‘src/[plugin_name]/’

  Examples: - /files/mindroot/src/mindroot/coreplugins/chat/templates/chat.jinja2 -> chat/templates/chat.jinja2 - /some/path/src/my_plugin/templates/page.jinja2 -> my_plugin/templates/page.jinja2

mindroot.coreplugins.l8n.utils.extract_translation_keys(content: str) → set

  Extract all __TRANSLATE_key__ placeholders from content.

  Parameters:

    content – Content to scan for translation keys

  Returns:

    Set of translation keys found in the content

mindroot.coreplugins.l8n.utils.get_localized_file_path(original_path: str) → Path

  Convert an original file path to its localized version path.

  Examples: - chat/templates/chat.jinja2 -> localized_files/coreplugins/chat/templates/chat.i18n.jinja2 - my_plugin/templates/page.jinja2 -> localized_files/external_plugins/my_plugin/templates/page.i18n.jinja2

mindroot.coreplugins.l8n.utils.get_plugin_translations_path(original_path: str) → Path

  Get the path where translations should be stored for a given file.

  Example: /files/mindroot/src/mindroot/coreplugins/check_list/inject/admin.jinja2 -> translations/coreplugins/check_list/translations.json

mindroot.coreplugins.l8n.utils.load_plugin_translations(plugin_path: str)

  Load translations for a specific plugin from disk.

mindroot.coreplugins.l8n.utils.replace_placeholders(content: str, language: str, plugin_path: str = None) → str

  Replace __TRANSLATE_key__ placeholders with actual translations.

  This function now validates that ALL required translations are available for the specified language. If any translations are missing, it logs a strong warning and returns None to indicate fallback is needed.

  Parameters:

    - content – Template content with placeholders

    - language – Language code for translations

    - plugin_path – Path to the localized file (used to determine which plugin’s translations to use)

  Returns:

    Content with placeholders replaced by translations, or None if translations are incomplete

## Module contents