Core_Translation_Engine.md

graph LR
    Translation_Registration_Entry_Point["Translation Registration Entry Point"]
    Model_Patching_Orchestrator["Model Patching Orchestrator"]
    Translated_Field_Injector_Schema_Adapter["Translated Field Injector & Schema Adapter"]
    ORM_Manager_Patcher["ORM Manager Patcher"]
    Model_Instance_Initializer_Populator["Model Instance Initializer & Populator"]
    Translation_Options_Registry["Translation Options Registry"]
    Translation_Unregistration_Handler["Translation Unregistration Handler"]
    Translation_Registration_Entry_Point -- "delegates tasks to" --> Model_Patching_Orchestrator
    Translation_Registration_Entry_Point -- "utilizes" --> Translation_Options_Registry
    Model_Patching_Orchestrator -- "calls" --> Translated_Field_Injector_Schema_Adapter
    Model_Patching_Orchestrator -- "triggers" --> ORM_Manager_Patcher
    Model_Patching_Orchestrator -- "invokes" --> Model_Instance_Initializer_Populator
    Model_Patching_Orchestrator -- "relies on" --> Translation_Options_Registry
    Translated_Field_Injector_Schema_Adapter -- "queries" --> Translation_Options_Registry
    ORM_Manager_Patcher -- "uses" --> Translation_Options_Registry
    Model_Instance_Initializer_Populator -- "utilizes" --> Translation_Options_Registry
    Translation_Unregistration_Handler -- "interacts with" --> Translation_Options_Registry

Loading

Details

The Core Translation Engine subsystem is primarily defined by the modeltranslation.translator, modeltranslation.decorators, and modeltranslation.models modules. Its boundaries encompass the mechanisms responsible for registering models for translation, dynamically modifying their structure and behavior at runtime, and managing the associated translation configurations.

Translation Registration Entry Point

This component serves as the primary interface for initiating the translation process. It handles the auto-discovery of translatable models during Django application startup (handle_translation_registrations) and provides the public API (register) for users to explicitly mark models for translation. The decorators module simplifies this interaction.

Related Classes/Methods:

• modeltranslation.models
• modeltranslation.translator:handle_translation_registrations
• modeltranslation.translator:register
• modeltranslation.decorators

Model Patching Orchestrator

The core internal component responsible for coordinating the dynamic modification of Django models. It orchestrates various patching functions (_register_single_model) to inject translation-aware behaviors and fields into the model's structure and runtime, embodying the "Extension/Plugin Pattern".

Related Classes/Methods:

• modeltranslation.translator:_register_single_model

Translated Field Injector & Schema Adapter

This component is responsible for dynamically adding language-specific fields (e.g., my_field_en) to the registered model's definition, effectively altering the in-memory database schema (add_translation_fields). It also handles patching model constraints (patch_constraints) to account for these new fields, ensuring data integrity.

Related Classes/Methods:

• modeltranslation.translator:add_translation_fields
• modeltranslation.translator:patch_constraints

ORM Manager Patcher

Modifies Django's Manager and custom managers (patch_manager_class) to ensure that ORM queries and updates correctly handle translated fields. This makes the ORM translation-aware, providing a seamless interaction layer with translated data in the database.

Related Classes/Methods:

• modeltranslation.translator:patch_manager_class

Model Instance Initializer & Populator

Patches the model's __init__ method (patch_constructor) and related logic (populate_translation_fields) to ensure that translation fields are correctly populated when model instances are created or retrieved, including handling fallback values based on configured language settings.

Related Classes/Methods:

• modeltranslation.translator:patch_constructor
• modeltranslation.translator:populate_translation_fields

Translation Options Registry

Acts as the central registry and lookup for all translation-related configurations and options for any given model (get_options_for_model, _get_options_for_model). It stores information such as translatable fields, fallback languages, and other settings.

Related Classes/Methods:

• modeltranslation.translator:get_options_for_model
• modeltranslation.translator:_get_options_for_model

Translation Unregistration Handler

Provides the functionality to reverse the translation setup for a model (unregister). It removes dynamically added fields and reverts patched behaviors, which is important for testing and dynamic application scenarios.

Related Classes/Methods:

• modeltranslation.translator:unregister

FAQ