Wagtail Localize

https://wagtail-localize.org/stable
Admin
Wagtail Localize is a Django app that provides tools for translating Wagtail CMS content, including...
Tokens:54,745
Snippets:214
Trust Score:6.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Create Wagtail Project (macOS/Linux)

Source: https://wagtail-localize.org/stable/tutorial/1-project-set-up

Commands to set up a new Wagtail project on macOS and GNU/Linux. This includes creating a virtual environment, activating it, installing Wagtail and Wagtail-localize, and starting a new Wagtail project.

```bash
# Create a new virtual environment in a 'tutorial-venv' folder
# This isolates installed dependencies from other projects
python3 -m venv tutorial-venv
# Activate the virtual environment
# Note: If you come back to this tutorial later, you will need to
# run this again to reactivate the environment
source tutorial-venv/bin/activate
# Install Wagtail and Wagtail Localize
pip install wagtail wagtail-localize
# Start a new project
wagtail start tutorial
cd tutorial

```

--------------------------------

### Create Wagtail Project (Windows PowerShell)

Source: https://wagtail-localize.org/stable/tutorial/1-project-set-up

Commands to set up a new Wagtail project on Windows using PowerShell. This includes creating a virtual environment, activating it, installing Wagtail and Wagtail-localize, and starting a new Wagtail project.

```powershell
# Create a new virtual environment in a 'tutorial-venv' folder
# This isolates installed dependencies from other projects
python -m venv tutorial-venv
# Activate the virtual environment
# Note: If you come back to this tutorial later, you will need to
# run this again to reactivate the environment
.\tutorial-venv\Script\Activate.ps1
# Install Wagtail and Wagtail Localize
pip install wagtail wagtail-localize
# Start a new project
wagtail start tutorial
cd .\tutorial

```

--------------------------------

### Start Wagtail Development Server

Source: https://wagtail-localize.org/stable/tutorial/1-project-set-up

Command to start the local development server for a Wagtail project.

```python
python manage.py runserver

```

--------------------------------

### Install Wagtail Localize Python Package

Source: https://wagtail-localize.org/stable/how-to/installation

Installs the wagtail-localize Python package using pip. This is the first step in setting up Wagtail Localize.

```shell
pip install wagtail-localize
```

--------------------------------

### Add Wagtail Localize to INSTALLED_APPS

Source: https://wagtail-localize.org/stable/how-to/installation

Configures the Django project to recognize Wagtail Localize by adding it to the INSTALLED_APPS setting in settings.py.

```python
INSTALLED_APPS = [
    # ...
    "wagtail_localize",
    # ...
]
```

--------------------------------

### Install Testing Dependencies for Wagtail Localize

Source: https://wagtail-localize.org/stable/index

Installs the necessary testing dependencies for Wagtail Localize using pip, including the testing extras.

```bash
pip"pip>=21.3"
pip'.[testing]'
```

--------------------------------

### Migrate Database for Wagtail

Source: https://wagtail-localize.org/stable/tutorial/1-project-set-up

Command to perform the initial database migration for a Wagtail project, creating the 'db.sqlite3' file.

```python
python manage.py migrate

```

--------------------------------

### Create Admin User for Wagtail

Source: https://wagtail-localize.org/stable/tutorial/1-project-set-up

Command to create an administrator user for the Wagtail project.

```python
python manage.py createsuperuser

```

--------------------------------

### Install Wagtail Localize using Flit

Source: https://wagtail-localize.org/stable/index

Instructions for installing Wagtail Localize using Flit, a tool for packaging Python projects. Requires Flit version 3.8.0 or higher.

```bash
pip"flit>=3.8.0"
flit
```

--------------------------------

### Install Wagtail Localize with Pip

Source: https://wagtail-localize.org/stable/index

Instructions for installing Wagtail Localize using pip. This involves adding the package to your project's dependencies.

```bash
pip
```

--------------------------------

### Install Wagtail Localize Google Plugin

Source: https://wagtail-localize.org/stable/how-to/integrations/machine-translation

Installs the necessary dependencies for Wagtail Localize to integrate with Google Cloud Translation.

```Shell
pip install wagtail-localize[google]
```

--------------------------------

### Control Translation Cleanup Mode

Source: https://wagtail-localize.org/stable/how-to/installation

Configures Wagtail Localize's behavior when deleting translation sources or destinations. Setting this to True keeps related translation data.

```python
WAGTAILLOCALIZE_DISABLE_ON_DELETE = True
```

--------------------------------

### Install wagtail-localize-git Plugin

Source: https://wagtail-localize.org/stable/how-to/integrations/pontoon

Installs the `wagtail-localize-git` plugin using pip and adds it to your project's requirements. This plugin is necessary for Wagtail Localize to interact with Git repositories for translation workflows.

```Shell
pip
```

--------------------------------

### Set Wagtail Localize Default Translation Mode on Model

Source: https://wagtail-localize.org/stable/how-to/installation

Defines the default translation mode for a specific Wagtail Page model to 'simple'. This overrides the global setting for this model.

```python
from wagtail.models import Page


class MyPage(Page):
    localize_default_translation_mode = "simple"
    # ...
```

--------------------------------

### Disable Live Status Sync on Translation

Source: https://wagtail-localize.org/stable/how-to/installation

Prevents Wagtail Localize from automatically making translated models live. Submitted translations will remain as drafts for manual publication.

```python
WAGTAILLOCALIZE_SYNC_LIVE_STATUS_ON_TRANSLATE = False
```

--------------------------------

### Heroku App Setup Script for SSH Key (Container Apps)

Source: https://wagtail-localize.org/stable/how-to/integrations/pontoon

A bash script intended for use as a Docker entrypoint in container-based Heroku apps. Similar to the regular app script, it handles the creation of the SSH directory and key files from the `SSH_PRIVATE_KEY` environment variable.

```bash
#!/usr/bin/env bash

# Copy SSH private key to file, if set
# This is used for talking to GitHub over an SSH connection
if[$SSH_PRIVATE_KEY];then
echo"Generating SSH config"
SSH_DIR=/app/.ssh

$SSH_DIR
700$SSH_DIR

echo$SSH_PRIVATE_KEY|$SSH_DIR/id_rsa

400$SSH_DIR/id_rsa

<< EOF > $SSH_DIR/config
StrictHostKeyChecking no
EOF

600$SSH_DIR/config

echo"Done!"
fi

exec"@"

```

--------------------------------

### Configure Wagtail Localize Default Translation Mode

Source: https://wagtail-localize.org/stable/how-to/installation

Sets the global default translation mode for Wagtail Localize to 'simple' in the Django settings. This can also be set per model.

```python
WAGTAIL_LOCALIZE_DEFAULT_TRANSLATION_MODE = "simple"
```

--------------------------------

### Heroku App Setup Script for SSH Key (Regular Apps)

Source: https://wagtail-localize.org/stable/how-to/integrations/pontoon

A bash script for the `.profile` file in regular Heroku apps. It checks if the `SSH_PRIVATE_KEY` environment variable is set, creates an SSH directory, writes the decoded private key and configuration to files, and sets appropriate permissions.

```bash
#!/usr/bin/env bash

# Copy SSH private key to file, if set
# This is used for talking to GitHub over an SSH connection
if[$SSH_PRIVATE_KEY];then
echo"Generating SSH config"
SSH_DIR=/app/.ssh

$SSH_DIR
700$SSH_DIR

echo$SSH_PRIVATE_KEY|$SSH_DIR/id_rsa

400$SSH_DIR/id_rsa

<< EOF > $SSH_DIR/config
StrictHostKeyChecking no
EOF

600$SSH_DIR/config

echo"Done!"
fi

```

--------------------------------

### Creating StringTranslation from Text

Source: https://wagtail-localize.org/stable/ref/models/translation-memory

A class method to get or create a StringTranslation instance. It takes the source string, locale, context, and the translated text as input. It returns the created or existing String instance.

```Python
@classmethod
def from_text(cls, translation_of, locale, context, data):
    """
    Gets or creates a StringTranslation instance from the given parameters.

    Args:
        translation_of (ForeignKey to String): The String that this is a translation of.
        locale (ForeignKey to Locale): The Locale of this translation.
        context (ForeignKey to TranslationContext): The context that this translation was made in. This allows different
            fields/pages to have different translations of the same source string.
        data (TextField): The translation.

    Returns:
        String: The String instance that corresponds with the given stringvalue and locale.
    """
    segment, created = cls.objects.get_or_create(
        translation_of=translation_of,
        locale_id=pk(locale),
        context_id=pk(context),
        defaults={"data": data},
    )

    return segment
```

--------------------------------

### Install Wagtail Localize ModelAdmin

Source: https://wagtail-localize.org/stable/how-to/modeladmin

This snippet shows how to add the Wagtail Localize modeladmin integration to your Django project's INSTALLED_APPS. This is a necessary step for enabling translation of custom ModelAdmin models.

```Python
INSTALLED_APPS = [
    # ...
    "wagtail_localize.modeladmin",
]
```

--------------------------------

### Get or Create StringTranslation Instance

Source: https://wagtail-localize.org/stable/ref/models/translation-memory

The `from_text` class method retrieves an existing StringTranslation or creates a new one based on the provided translation_of, locale, context, and data. It ensures that translations are correctly associated with their source strings, locales, and contexts, handling potential creation of new entries.

```Python
@classmethod
def from_text(cls, translation_of, locale, context, data):
    """
    Gets or creates a StringTranslation instance from the given parameters.

    Args:
        translation_of (ForeignKey to String): The String that this is a translation of.
        locale (ForeignKey to Locale): The Locale of this translation.
        context (ForeignKey to TranslationContext): The context that this translation was made in. This allows different
            fields/pages to have different translations of the same source string.
        data (TextField): The translation.

    Returns:
        String: The String instance that corresponds with the given stringvalue and locale.
    """
    segment, created = cls.objects.get_or_create(
        translation_of=translation_of,
        locale_id=pk(locale),
        context_id=pk(context),
        defaults={"data": data},
    )

    return segment

```

--------------------------------

### Initialize Pre-commit Hooks for Wagtail Localize

Source: https://wagtail-localize.org/stable/index

Commands to set up and initialize pre-commit hooks for the Wagtail Localize project, ensuring code quality checks before commits.

```bash
# go to the project directory
$cd# initialize pre-commit
$# Optional, run all checks once for this, then the checks will run only on the changed files
$
```

--------------------------------

### Initialize PageIndex with Pages

Source: https://wagtail-localize.org/stable/ref/synctree

Constructs a PageIndex object by taking a list of page entries. This is the primary way to create an index, typically populated with data retrieved from the database or other sources.

```Python
def __init__(self, pages):
    self.pages = pages
```

--------------------------------

### Run Tests with Tox for Wagtail Localize

Source: https://wagtail-localize.org/stable/index

Commands to execute tests for Wagtail Localize using Tox. Allows running all tests, specific environments, or specific test cases.

```bash
tox

or, you can run them for a specific environment `tox -e python3.11-django4.2-wagtail5.2` or specific test `tox -e python3.11-django4.2-wagtail5.2-sqlite -- wagtail_localize.tests.test_edit_translation.TestGetEditTranslationView`
To run the test app interactively, use `tox -e interactive`, visit `http://127.0.0.1:8020/admin/` and log in with `admin`/`changeme`.
```

--------------------------------

### Migrate Database for Wagtail Localize

Source: https://wagtail-localize.org/stable/tutorial/2-configure-wagtail-localize

Command to run database migrations after setting up Wagtail Localize. This ensures that all necessary database tables for the new functionality are created.

```Shell
python manage.py migrate
```

--------------------------------

### Run Django Migrations

Source: https://wagtail-localize.org/stable/tutorial/3-content

This command initiates the database schema changes required for the newly defined blog models and Wagtail Localize features. It ensures that the database is updated to reflect the application's structure.

```bash
python manage.py makemigrations
python manage.py migrate
```

--------------------------------

### Clone Wagtail Localize Repository

Source: https://wagtail-localize.org/stable/index

Command to clone the Wagtail Localize Git repository to begin making changes or contributing to the project.

```bash
gitcd
```

--------------------------------

### Create OverridableSegment from Value

Source: https://wagtail-localize.org/stable/ref/models/translatable-segments

A class method 'from_value' to create an OverridableSegment instance. It handles getting or creating the associated TranslationContext and then creating the segment with JSON-encoded data.

```Python
    @classmethod
    def from_value(cls, source, value):
        context, context_created = TranslationContext.objects.get_or_create(
            object_id=source.object_id,
            path=value.path,
        )

        segment, created = cls.objects.get_or_create(
            source=source,
            context=context,
            order=value.order,
            data_json=json.dumps(value.data, cls=DjangoJSONEncoder),
        )

        return segment

```

--------------------------------

### Add Blog App to INSTALLED_APPS

Source: https://wagtail-localize.org/stable/tutorial/3-content

This snippet shows how to register the 'blog' application, along with Wagtail Localize modules and other necessary Wagtail components, in your Django project's settings.

```python
INSTALLED_APPS = [
    "home",
    "search",
    # Insert this
    "blog",
    "wagtail_localize",
    "wagtail_localize.locales",
    "wagtail.contrib.forms",
    "wagtail.contrib.redirects",
    # ...
]
```

--------------------------------

### Get Translatable HTML

Source: https://wagtail-localize.org/stable/ref/strings

Returns an HTML string representation of the StringValue without restoring any HTML attributes. If the string was initialized from plain text, special characters will be escaped.

```Python
def get_translatable_html(self):
    """
    Returns a HTML string without restoring any HTML attributes.

    Note: If the string was initialised from plain text, all special characters will be escaped.

    Returns:
        str: The HTML representation of the string without HTML attributes
    """
    return self.data

```

--------------------------------

### Get Decoded JSON Data

Source: https://wagtail-localize.org/stable/ref/models/translatable-segments

Provides a property 'data' to retrieve the decoded JSON data stored in the 'data_json' field. This allows easy access to the segment's content.

```Python
    @property
    def data(self):
        """
        Returns the decoded JSON data that's stored in .data_json
        """
        return json.loads(self.data_json)

```

--------------------------------

### Initialize Page Entry from Instance

Source: https://wagtail-localize.org/stable/ref/synctree

This class method initializes an `Entry` object from a given Wagtail `Page` instance. It extracts relevant page information, including content type, translation key, locale, and parent's translation key, and determines associated locales.

```Python
@classmethod
def from_page_instance(cls, page):
    """
    Initialises an Entry from the given page instance.
    """
    # Get parent, but only if the parent is not the root page. We consider the
    # homepage of each langauge tree to be the roots
    parent_page = page.get_parent() if page.depth > 2 else None

    return cls(
        page.content_type,
        page.translation_key,
        page.locale,
        parent_page.translation_key if parent_page else None,
        list(
            Page.objects.filter(
                translation_key=page.translation_key,
                alias_of__isnull=True,
            ).values_list("locale", flat=True)
        ),
        list(
            Page.objects.filter(
                translation_key=page.translation_key,
                alias_of__isnull=False,
            ).values_list("locale", flat=True)
        ),
    )
```

--------------------------------

### Get Pages Not Translated into Locale

Source: https://wagtail-localize.org/stable/ref/synctree

This method returns a new `PageIndex` containing only the pages that have not been translated into the specified locale. It iterates through the existing pages and filters them based on the presence of the locale ID.

```Python
def not_translated_into(self, locale):
    """
    Returns an index of pages that are not translated into the specified locale.
    This includes pages that have and don't have a placeholder
    """
    pages = [page for page in self.pages if locale.id not in page.locales]

    return PageIndex(pages)
```

--------------------------------

### Implement Custom Background Job Backend

Source: https://wagtail-localize.org/stable/how-to/configure-background-tasks

This Python code demonstrates how to create a custom job backend for Wagtail Localize by subclassing `BaseJobBackend`. It includes placeholders for initialization and task enqueuing logic, allowing integration with any queueing system.

```Python
from wagtail_localize.tasks import BaseJobBacked


class MyJobBackend(BaseJobBackend):
    def __init__(self, options):
        # Any set up code goes here. Note that the 'options' parameter contains the value of WAGTAILLOCALIZE_JOBS["OPTIONS"]
        pass

    def enqueue(self, func, args, kwargs):
        # func is a function object to call
        # args is a list of positional arguments to pass into the function when it's called
        # kwargs is is a dict of keyword arguments to pass into the function when it's called
        pass
```

--------------------------------

### Get Instance for Locale

Source: https://wagtail-localize.org/stable/ref/segments/types

Retrieves the translatable object instance corresponding to the segment for a given locale. It queries for the object using the stored translation key and content type, raising DoesNotExist if no such instance is found.

```Python
def get_instance(self, locale):
    """
    Gets an instance of the referenced translatable object for the given locale.

    Raises:
        Model.DoesNotExist: If there isn't an instance of the translatable object in the given locale.

    Returns:
        Model: The instance.
    """
    from ..models import pk

    return self.content_type.get_object_for_this_type(
        translation_key=self.translation_key, locale_id=pk(locale)
    )

```

--------------------------------

### Collect Static Assets for Wagtail Localize

Source: https://wagtail-localize.org/stable/index

Command to run after configuring INSTALLED_APPS to collect Wagtail Localize's static assets for the editing interface.

```python
python
```

--------------------------------

### Get or Create String from Value (from_value)

Source: https://wagtail-localize.org/stable/ref/models/translation-memory

Retrieves an existing String instance or creates a new one from a StringValue object, associating it with a specific locale. It utilizes the _get_data_hash method to ensure uniqueness.

```Python
@classmethod
def from_value(cls, locale, stringvalue):
    """
    Gets or creates a String instance from a StringValue object.

    Args:
        locale (ForeignKey to Locale) The locale of the string.
        stringvalue (StringValue): The value of the string.

    Returns:
        String: The String instance that corresponds with the given stringvalue and locale.
    """
    string, created = cls.objects.get_or_create(
        locale_id=pk(locale),
        data_hash=cls._get_data_hash(stringvalue.data),
        defaults={"data": stringvalue.data},
    )

    return string
```

--------------------------------

### Get Validation Error - Python

Source: https://wagtail-localize.org/stable/ref/models/translatable-segments

Retrieves any validation errors associated with a saved value. It checks for specific error conditions within the model's context and returns the field error if present.

```Python
def get_error(self):
    """
    Returns a string containing any validation errors on the saved value.

    Returns:
        str: The validation error if there is one.
        None: If there isn't an error.
    """
    # Check if a database error was raised when we last attempted to publish
    if self.has_error and self.context is not None and self.field_error:
        return self.field_error
```

--------------------------------

### Populate Page Index from Database

Source: https://wagtail-localize.org/stable/ref/synctree

This class method populates the page index by retrieving pages from the database. It filters out aliased pages and pages at the root depth, then creates `Entry` objects for each valid page.

```Python
@classmethod
def from_database(cls):
    """
    Populates the index from the database.
    """
    pages = []

    for page in Page.objects.filter(alias_of__isnull=True, depth__gt=1).only(
        *PageIndex.Entry.REQUIRED_PAGE_FIELDS
    ):
        pages.append(PageIndex.Entry.from_page_instance(page))

    return PageIndex(pages)
```

--------------------------------

### Migrate from wagtailtrans to wagtail-localize

Source: https://wagtail-localize.org/stable/how-to/migrate/wagtailtrans

This section provides a link to a blog post that explains how to migrate your Wagtail website from the wagtailtrans plugin to the new wagtail-localize plugin. It's a crucial step for users looking to update their translation infrastructure.

```Markdown
# Migrate from wagtailtrans
Please see this blog post: Migrate your Wagtail Website from wagtailtrans to the new wagtail-localize
```

--------------------------------

### Configure Wagtail Localize Translatable Fields

Source: https://wagtail-localize.org/stable/ref/translatable-fields

Provides the BaseTranslatableField class for configuring translatable fields in Wagtail. It includes methods to get field values, check editability, translation status, synchronization, and overrideability.

```Python
class BaseTranslatableField:
    def __init__(self, field_name):
        self.field_name = field_name

    def get_field(self, model):
        return model._meta.get_field(self.field_name)

    def get_value(self, obj):
        return self.get_field(obj.__class__).value_from_object(obj)

    def is_editable(self, obj):
        """
        Returns True if the field is editable on the given object
        """
        return True

    def is_translated(self, obj):
        """
        Returns True if the value of this field on the given object should be
        extracted and submitted for translation
        """
        return False

    def is_synchronized(self, obj):
        """
        Returns True if the value of this field on the given object should be
        copied when translations are created/updated
        """
        return False

    def is_overridable(self, obj):
        """
        Returns True if the value of this field can be overridden. This is only
        applicable to fields that are synchronized
        """
        return self.is_synchronized(obj)

    def __eq__(self, other):
        return self.__class__ == other.__class__ and self.field_name == other.field_name
```

--------------------------------

### Configure Django INSTALLED_APPS

Source: https://wagtail-localize.org/stable/how-to/integrations/pontoon

Adds the `wagtail_localize` and `wagtail_localize_git` applications to your Django project's `INSTALLED_APPS` setting. This enables Wagtail Localize and its Git integration features within your Wagtail project.

```Python
INSTALLED_APPS = [
    # ...
    "wagtail_localize",
    # Insert this
    "wagtail_localize_git",
    # ...
]
```

--------------------------------

### Wagtail Localize: Related Object Segments

Source: https://wagtail-localize.org/stable/tutorial/3-content

Details related object segments, which include translatable related objects linked to the original page. For example, a translatable `BlogCategory` model is automatically submitted for translation.

```text
Any translatable related objects that are linked to the original page are automatically submitted for translation when the page is submitted. For example, the `BlogCategory` model is translatable, so Wagtail Localize has automatically submitted the "Dog" blog category, that was linked from the original page, for translation:
```

--------------------------------

### Set Heroku SSH Private Key Environment Variable

Source: https://wagtail-localize.org/stable/how-to/integrations/pontoon

Assigns the base64 encoded SSH private key to the `SSH_PRIVATE_KEY` environment variable in Heroku. This variable will be used by a setup script to reconstruct the private key file.

```bash
herokuSSH_PRIVATE_KEY=<paste
```

--------------------------------

### Configure URL Patterns for i18n

Source: https://wagtail-localize.org/stable/tutorial/2-configure-wagtail-localize

Defines URL patterns for translatable and non-translatable paths using Django's `i18n_patterns`. This includes setting up patterns for search and Wagtail's page serving mechanism, with options for serving pages from a subpath.

```Python
from django.urls import path, include
from django.conf.urls.i18n import i18n_patterns

from . import views as search_views
from wagtail.urls import urls as wagtail_urls
from wagtail.admin import urls as wagtailadmin_urls
from wagtail.documents import urls as wagtaildocs_urls

# Translatable urlpatterns
urlpatterns = i18n_patterns(
    path("search/", search_views.search, name="search"),
    # For anything not caught by a more specific rule above, hand over to
    # Wagtail's page serving mechanism. This should be the last pattern in
    # the list:
    path("", include(wagtail_urls)),
    # Alternatively, if you want Wagtail pages to be served from a subpath
    # of your site, rather than the site root:
    #    path("pages/", include(wagtail_urls)),
)

# Non-translatable urlpatterns
urlpatterns += [
    path("django-admin/", admin.site.urls),
    path("admin/", include(wagtailadmin_urls)),
    path("documents/", include(wagtaildocs_urls)),
]
```

--------------------------------

### Get Translation Comment

Source: https://wagtail-localize.org/stable/ref/models/translation-memory

The `get_comment` method generates a user-friendly comment indicating how and when a string was translated. It supports different translation types, including manual, machine, and tool-assisted translations, providing context for the translation process.

```Python
def get_comment(self):
    """
    Returns a comment to display to the user containing info on how and when the string was translated.

    Returns:
        str: A comment to display to the user.
    """
    if self.tool_name:
        return _("Translated with {tool_name} on {date}").format(
            tool_name=self.tool_name, date=self.updated_at.strftime(DATE_FORMAT)
        )

    elif self.translation_type == self.TRANSLATION_TYPE_MANUAL:
        return _("Translated manually on {date}").format(
            date=self.updated_at.strftime(DATE_FORMAT)
        )

    elif self.translation_type == self.TRANSLATION_TYPE_MACHINE:
        return _("Machine translated on {date}").format(
            date=self.updated_at.strftime(DATE_FORMAT)
        )

```

--------------------------------

### PageIndex Entry Initialization

Source: https://wagtail-localize.org/stable/ref/synctree

Initializes a PageIndex.Entry object, which represents a single page within the index. It stores details such as content type, translation key, source locale, parent information, and lists of locales for which the page is translated or aliased.

```Python
def __init__(
            self,
            content_type,
            translation_key,
            source_locale,
            parent_translation_key,
            locales,
            aliased_locales,
        ):
            self.content_type = content_type
            self.translation_key = translation_key
            self.source_locale = source_locale
            self.parent_translation_key = parent_translation_key
            self.locales = locales
            self.aliased_locales = aliased_locales
```

--------------------------------

### Enable Django LocaleMiddleware

Source: https://wagtail-localize.org/stable/tutorial/2-configure-wagtail-localize

This snippet shows how to enable Django's LocaleMiddleware by inserting it into the MIDDLEWARE setting to handle browser language detection.

```Python
MIDDLEWARE = [
    "django.contrib.sessions.middleware.SessionMiddleware",
    "django.middleware.common.CommonMiddleware",
    "django.middleware.csrf.CsrfViewMiddleware",
    "django.contrib.auth.middleware.AuthenticationMiddleware",
    "django.contrib.messages.middleware.MessageMiddleware",
    "django.middleware.clickjacking.XFrameOptionsMiddleware",
    "django.middleware.security.SecurityMiddleware",
    # Insert this here
    "django.middleware.locale.LocaleMiddleware",
    "wagtail.contrib.redirects.middleware.RedirectMiddleware",
]
```

--------------------------------

### Get Field Path from StreamField Block (Python)

Source: https://wagtail-localize.org/stable/ref/models/translation-memory

Retrieves the field path from a StreamField block within a Wagtail instance. It handles different field types, including ManyToOneRel relationships with ParentalKey, to construct the complete path.

```Python
return [field_name] + get_field_path_from_streamfield_block(
                        field.value_from_object(instance), path_components[1:]
                    )

                elif (
                    isinstance(field, models.ManyToOneRel)
                    and isinstance(field.remote_field, ParentalKey)
                    and issubclass(field.related_model, TranslatableMixin)
                ):
                    manager = getattr(instance, field_name)
                    child_instance = manager.get(translation_key=path_components[1])
                    return [field_name] + get_field_path_from_field(
                        child_instance, path_components[2:]
                    )

                else:
                    return [field_name]

            self.field_path = ".".join(
                get_field_path_from_field(instance, self.path.split("."))
            )
            self.save(update_fields=["field_path"])

        return self.field_path
```

--------------------------------

### Get Validation Errors - wagtail_localize/models.py

Source: https://wagtail-localize.org/stable/ref/models/overridable-segments

The get_error method returns a string containing any validation errors associated with a saved value. It checks for database errors during the last publish attempt and returns the specific field error if present.

```Python
def get_error(self):
    """
    Returns a string containing any validation errors on the saved value.

    Returns:
        str: The validation error if there is one.
        None: If there isn't an error.
    """
    # Check if a database error was raised when we last attempted to publish
    if self.has_error and self.context is not None and self.field_error:
        return self.field_error
```

--------------------------------

### Configure INSTALLED_APPS for Wagtail Localize

Source: https://wagtail-localize.org/stable/index

Demonstrates how to add 'wagtail_localize' and 'wagtail_localize.locales' to your Django project's INSTALLED_APPS setting. This is necessary for Wagtail Localize to function correctly.

```python
INSTALLED_APPS = [
    # ...
    "wagtail_localize",
    "wagtail_localize.locales",  # This replaces "wagtail.locales"
    # ...
]
```

--------------------------------

### Create TemplateSegment from Value

Source: https://wagtail-localize.org/stable/ref/models/translatable-segments

Gets or creates a TemplateSegment instance from a TemplateValue object. It requires a TranslationSource and a TemplateValue as input. The method ensures that a corresponding TranslationContext exists and then creates or retrieves a TemplateSegment associated with the source, context, order, and template.

```Python
@classmethod
def from_value(cls, source, value):
    """
    Gets or creates a TemplateSegment instance from a TemplateValue object.

    Args:
        source (TranslationSource): The source the template value was extracted from.
        template_value (TemplateValue): The value of the template.

    Returns:
        TemplateSegment: The TemplateSegment instance that corresponds with the given template_value and source.
    """
    template = Template.from_value(value)
    context, context_created = TranslationContext.objects.get_or_create(
        object_id=source.object_id,
        path=value.path,
    )

    segment, created = cls.objects.get_or_create(
        source=source,
        context=context,
        order=value.order,
        template=template,
    )

    return segment
```

--------------------------------

### Add Wagtail Localize to INSTALLED_APPS

Source: https://wagtail-localize.org/stable/tutorial/2-configure-wagtail-localize

This snippet shows how to add 'wagtail_localize' and 'wagtail_localize.locales' to the INSTALLED_APPS setting in Django's settings file.

```Python
INSTALLED_APPS = [
    "home",
    "search",
    # Insert these here
    "wagtail_localize",
    "wagtail_localize.locales",
    "wagtail.contrib.forms",
    "wagtail.contrib.redirects",
    # ...
]
```

--------------------------------

### Enable Wagtail's Internationalisation

Source: https://wagtail-localize.org/stable/tutorial/2-configure-wagtail-localize

This snippet demonstrates enabling Wagtail's internationalization features by setting WAGTAIL_I18N_ENABLED to True, along with USE_I18N and USE_L10N.

```Python
USE_I18N = True

USE_L10N = True  # only if using Django < 4.0

# Add this
WAGTAIL_I18N_ENABLED = True

USE_TZ = True
```

--------------------------------

### Create TemplateSegment from Value (Python)

Source: https://wagtail-localize.org/stable/ref/models/translatable-segments

The `from_value` class method in `TemplateSegment` is used to get or create a `TemplateSegment` instance from a `TemplateValue` object. It handles the creation of associated `String` and `TranslationContext` objects if they don't exist, ensuring data integrity for localization.

```Python
@classmethod
def from_value(cls, source, language, value):
    """
    Gets or creates a TemplateSegment instance from a TemplateValue object.

    Args:
        source (TranslationSource): The source the template value was extracted from.
        template_value (TemplateValue): The value of the template.

    Returns:
        TemplateSegment: The TemplateSegment instance that corresponds with the given template_value and source.
    """
    string = String.from_value(language, value.string)
    context, context_created = TranslationContext.objects.get_or_create(
        object_id=source.object_id,
        path=value.path,
    )

    segment, created = cls.objects.get_or_create(
        source=source,
        context=context,
        order=value.order,
        string=string,
        attrs=json.dumps(value.attrs, cls=DjangoJSONEncoder),
    )

    return segment
```

```Python
class TemplateSegment(BaseSegment):
    """
    Represents a template segment that was extracted from a TranslationSource.

    Attributes:
        template (ForeignKey to Template): The template that was extracted.
        source (ForeignKey[TranslationSource]): The source content that the string was extracted from.
        context (ForeignKey to TranslationContext): The context, which contains the position of the string in the source content.
        order (PositiveIntegerField): The index that this segment appears on the page.
    """

    template = models.ForeignKey(
        Template, on_delete=models.CASCADE, related_name="segments"
    )

    def __str__(self):
        return f"TemplateSegment({self.pk}) from Template({self.template_id})"

    @classmethod
    def from_value(cls, source, value):
        """
        Gets or creates a TemplateSegment instance from a TemplateValue object.

        Args:
            source (TranslationSource): The source the template value was extracted from.
            template_value (TemplateValue): The value of the template.

        Returns:
            TemplateSegment: The TemplateSegment instance that corresponds with the given template_value and source.
        """
        template = Template.from_value(value)
        context, context_created = TranslationContext.objects.get_or_create(
            object_id=source.object_id,
            path=value.path,
        )

        segment, created = cls.objects.get_or_create(
            source=source,
            context=context,
            order=value.order,
            template=template,
        )

        return segment
```

--------------------------------

### Get Translation Validation Errors

Source: https://wagtail-localize.org/stable/ref/models/translation-memory

The `get_error` method checks for and returns any validation errors associated with a translated string. It performs checks for HTML validity and translation link integrity, returning a descriptive error message if issues are found, or None if the translation is valid.

```Python
def get_error(self):
    """
    Returns a string containing any validation errors on the saved value.

    Returns:
        str: The validation error if there is one.
        None: If there isn't an error.
    """
    if not self.has_error:
        return

    # Check for HTML validation errors
    try:
        StringValue.from_translated_html(self.data)
        validate_translation_links(self.translation_of.data, self.data)
    except ValueError as e:
        return e.args[0]

    # Check if a database error was raised when we last attempted to publish
    if self.context is not None and self.field_error:
        return self.field_error

```

--------------------------------

### Create PageIndex Entry from Page Instance

Source: https://wagtail-localize.org/stable/ref/synctree

A class method to create an index entry from a given Wagtail page object. It extracts necessary fields like content type, translation key, locale, and parent information, and also queries for related translated pages.

```Python
@classmethod
def from_page_instance(cls, page):
            """
            Initialises an Entry from the given page instance.
            """
            # Get parent, but only if the parent is not the root page. We consider the
            # homepage of each langauge tree to be the roots
            parent_page = page.get_parent() if page.depth > 2 else None

            return cls(
                page.content_type,
                page.translation_key,
                page.locale,
                parent_page.translation_key if parent_page else None,
                list(
                    Page.objects.filter(
                        translation_key=page.translation_key,
                        alias_of__isnull=True,
                    ).values_list("locale", flat=True)
                ),
                list(
                    Page.objects.filter(
                        translation_key=page.translation_key,
                        alias_of__isnull=False,
                    ).values_list("locale", flat=True)
                ),
            )
```

--------------------------------

### Define Wagtail Page Models and Snippets

Source: https://wagtail-localize.org/stable/tutorial/3-content

This Python code defines the data models for a blog application within Wagtail, including page types for blog posts and index pages, and a translatable snippet for blog categories. It utilizes Wagtail's StreamField for flexible content composition and integrates with Wagtail Localize's TranslatableMixin.

```python
from django.db import models
from wagtail import blocks
from wagtail.admin.panels import FieldPanel
from wagtail.fields import StreamField
from wagtail.models import Page, TranslatableMixin
from wagtail.images.blocks import ImageChooserBlock
from wagtail.snippets.models import register_snippet


class ImageBlock(blocks.StructBlock):
    image = ImageChooserBlock()
    caption = blocks.CharBlock(required=False)

    class Meta:
        icon = "image"


class StoryBlock(blocks.StreamBlock):
    heading = blocks.CharBlock()
    paragraph = blocks.RichTextBlock()
    image = ImageBlock()


@register_snippet
class BlogCategory(TranslatableMixin):
    name = models.CharField(max_length=255)

    def __str__(self):
        return self.name


class BlogPostPage(Page):
    publication_date = models.DateField(null=True, blank=True)
    image = models.ForeignKey(
        "wagtailimages.Image", on_delete=models.SET_NULL, null=True
    )
    body = StreamField(StoryBlock())
    category = models.ForeignKey(
        BlogCategory, on_delete=models.SET_NULL, null=True, related_name="blog_posts"
    )

    content_panels = Page.content_panels + [
        FieldPanel("publication_date"),
        FieldPanel("image"),
        FieldPanel("body"),
        FieldPanel("category"),
    ]

    parent_page_types = ["blog.BlogIndexPage"]


class BlogIndexPage(Page):
    introduction = models.TextField(blank=True)

    content_panels = Page.content_panels + [
        FieldPanel("introduction"),
    ]

    parent_page_types = ["home.HomePage"]

```

--------------------------------

### Synchronize Slug Field in Wagtail Page

Source: https://wagtail-localize.org/stable/how-to/field-configuration

This example demonstrates how to override Wagtail Localize's default behavior to synchronize the 'slug' field instead of translating it. It defines a `BlogPage` model that inherits from `wagtail.models.Page` and uses `SynchronizedField` to mark the 'slug' field for synchronization.

```Python
from wagtail.models import Page

from wagtail_localize.fields import SynchronizedField


class BlogPage(Page):
    body = RichTextField()

    # Make the slug synchronised, but let Wagtail decide what to do with title/body
    override_translatable_fields = [
        SynchronizedField("slug"),
    ]

```
Tokens:
Raw