Международная локализация

• Многоязычный контент
  • Обзор
  • Подход Wagtail к многоязычному контенту
    • Структура страницы
    • Как локали и переводы записываются в базе данных
    • Переведённые главные страницы
    • Обнаружение и маршрутизация языка
  • Настройка
    • Включение международной локализации
    • Настройка доступных языков
    • Включение пользовательского интерфейса управления локалями (необязательно)
    • Добавление префикса языка в URL-адреса
    • Автоматическое определение языка пользователя
    • Настраиваемая маршрутизация/обнаружение языка
  • Рецепты для интернационализированных сайтов
    • Выбор языка/региона
    • Фильтры API для сайтов без фронтенда
    • Переводимые фрагменты
  • Процесс перевода
    • Wagtail Localize
• Альтернативные плагины международной локализации
• Переводы Wagtail администрирования
• Изменение языка Wagtail администрирования для каждого пользователя
• Изменение основного языка вашей установки Wagtail

Многоязычный контент

Обзор

По умолчанию Wagtail предполагает, что весь контент будет написан на одном языке. Этот документ описывает, как настроить Wagtail для создания контента на нескольких языках.

Этот документ охватывает только интернационализацию контента, управляемого Wagtail. Для получения информации о переводе статического контента в файлах шаблонов, коде JavaScript и т.д. обратитесь к документации Django по международной локализации https://docs.djangoproject.com/en/3.1/topics/i18n/translation/. Или, если вы создаёте сайт без фронтенда, обратитесь к документации используемой вами фронтенд-рамки.

Подход Wagtail к многоязычному контенту

Этот раздел содержит объяснение подхода Wagtail к интернационализации. Если вы спешите, можете перейти к разделу Настройка.

Вкратце:

• Wagtail хранит контент в отдельном дереве страниц для каждой локали
• Он имеет встроенную Locale модель, и все страницы связаны с Locale с полем внешнего ключа locale
• Он записывает, какие страницы являются переводами друг друга, используя общий UUID, хранящийся в поле translation_key
• Он автоматически перенаправляет запросы через переводы главной страницы сайта
• Он использует встроенные инструменты Django i18n_patterns и LocaleMiddleware для обнаружения языка

Структура страницы

Wagtail хранит контент в отдельном дереве страниц для каждой локали.

Например, если у вас есть два сайта на двух локалях, то вы увидите четыре главные страницы на верхнем уровне иерархии страниц в проводнике.

Этот подход также имеет некоторые преимущества для работы редактора:

• Нет языка по умолчанию для редактирования, поэтому контент может быть написан на любом языке, а затем переведён на любой другой.
• Переводы страницы — отдельные страницы, поэтому они могут быть опубликованы в разное время.
• Редакторам можно предоставлять разрешения на редактирование контента в одной локали и не в других.

Как локали и переводы записываются в базе данных

Все страницы (и любые фрагменты, у которых включён перевод) имеют поля locale и translation_key.

• locale — внешний ключ к модели Locale
• translation_key — UUID, который используется для поиска переводов фрагмента контента. Переводы одной и той же страницы/фрагмента имеют одинаковое значение в этом поле

Эти два поля имеют ограничение «уникально вместе», поэтому вы не можете иметь более одного перевода в одной локали.

Переведённые главные страницы

При настройке сайта в Wagtail вы выбираете главную страницу сайта в поле «корневая страница», и все запросы к корневому URL-адресу этого сайта будут перенаправлены на эту страницу.

Многоязычные сайты имеют отдельную главную страницу для каждой локали, которые существуют как сиблинги в дереве страниц. Wagtail находит другие главные страницы, ища переводы корневой страницы сайта.

Это означает, что для того, чтобы сделать сайт доступным на другой локали, вам нужно только перевести и опубликовать его главную страницу на новой локали.

Если Wagtail не может найти главную страницу, соответствующую языку пользователя, он вернётся к странице, выбранной в качестве корневой страницы на записи сайта, поэтому вы можете использовать это поле для указания языка по умолчанию для сайта.

Обнаружение и маршрутизация языка

Для обнаружения языка пользователя и добавления префикса к URL-адресам (/en/, /fr-fr/, например), Wagtail разработан для работы со встроенными инструментами интернационализации Django, такими как i18n_patterns и LocaleMiddleware. Это означает, что Wagtail должен беспрепятственно работать с другими интернационализированными приложениями Django на вашем сайте.

Локали

Локали, которые включены на сайте, записываются в модели Locale в wagtailcore. Эта модель имеет всего два поля: ID и language_code, которое хранит тег языка BCP-47, представляющий эту локаль.

Записи локали можно настроить с помощью дополнительного пользовательского интерфейса управления или создать в консоли. Возможные значения поля language_code контролируются настройкой WAGTAIL_CONTENT_LANGUAGES

Настройка

В этом разделе мы пройдёмся по минимальной настройке, необходимой для создания контента на нескольких языках.

• Включение интернационализации
• Настройка доступных языков
• Включение пользовательского интерфейса управления локалями (необязательно)
• Добавление префикса языка в URL-адреса
• Автоматическое определение языка пользователя
• Настраиваемая маршрутизация/обнаружение языка

Включение интернационализации

Для включения интернационализации в Django и Wagtail установите следующие настройки в True:

# my_project/settings.py

USE_I18N = True
WAGTAIL_I18N_ENABLED = True

Кроме того, вы можете включить поддержку локализации Django. Это позволит отображать даты и числа в формате локали пользователя:

# my_project/settings.py

USE_L10N = True

Настройка доступных языков

Далее нам нужно настроить доступные языки. Для этого существуют две настройки, которые используются для разных целей:

• LANGUAGES — устанавливает, какие языки доступны на переднем плане сайта.
• WAGTAIL_CONTENT_LANGUAGES — устанавливает, на каких языках можно создавать контент Wagtail.

Вы можете установить обе эти настройки в одинаковое значение. Например, для включения английского, французского и испанского:

# my_project/settings.py

WAGTAIL_CONTENT_LANGUAGES = LANGUAGES = [
    ('en', "English"),
    ('fr', "French"),
    ('es', "Spanish"),
]

Вы также можете установить эти значения в различные значения. Возможно, вам захочется сделать это, если вы хотите иметь программную локализацию (например, форматирование дат или валюты), но использовать одинаковый контент Wagtail в нескольких регионах:

# my_project/settings.py

LANGUAGES = [
    ('en-GB', "English (Great Britain)"),
    ('en-US', "English (United States)"),
    ('en-CA', "English (Canada)"),
    ('fr-FR', "French (France)"),
    ('fr-CA', "French (Canada)"),
]

WAGTAIL_CONTENT_LANGUAGES = [
    ('en-GB', "English"),
    ('fr-FR', "French"),
]

При такой конфигурации сайт будет доступен во всех различных языковых вариантах в первом списке, но в Wagtail будет только два языковых дерева.

Все en- языковые варианты будут использовать языковое дерево «Английский», а fr- языковые варианты — языковое дерево «Французский». Различия между каждым языковым вариантом в языке будут программными. Например: какой формат дат/чисел использовать и какую валюту использовать для отображения цен.

Включение пользовательского интерфейса управления локализацией (необязательно)

Существует необязательное приложение для управления локализацией, которое позволяет администратору Wagtail настроить языковые варианты в интерфейсе администрирования Wagtail.

Чтобы включить его, добавьте wagtail.locales в INSTALLED_APPS:

# my_project/settings.py

INSTALLED_APPS = [
    # ...
    'wagtail.locales',
    # ...
]

Добавление префикса языка к URL-адресам

Чтобы все деревья страниц могли быть доступны по одному домену, нам необходимо добавить префикс URL-адреса для каждого языка.

Для этого мы можем использовать встроенную функцию Django i18n_patterns, которая добавляет префикс языка ко всем URL-образцам, переданным в нее. Это активирует код языка, указанный в URL-адресе, и Wagtail учитывает это, когда решает, как обработать запрос.

В файле urls.py вашего проекта добавьте основные URL-адреса Wagtail (и любые другие URL-адреса, которые вы хотите перевести) в блок i18n_patterns:

# /my_project/urls.py

...

from django.conf.urls.i18n import i18n_patterns

# Non-translatable URLs
# Note: if you are using the Wagtail API or sitemaps,
# these should not be added to `i18n_patterns` either
urlpatterns = [
    path('django-admin/', admin.site.urls),

    path('admin/', include(wagtailadmin_urls)),
    path('documents/', include(wagtaildocs_urls)),
]

# Translatable URLs
# These will be available under a language code prefix. For example /en/search/
urlpatterns += i18n_patterns(
    path('search/', search_views.search, name='search'),
    path("", include(wagtail_urls)),
)

Автоопределение языка пользователя

После обертывания шаблонов URL-адресов i18n_patterns, ваш сайт теперь будет реагировать на префиксы URL-адресов. Но теперь он не будет реагировать на корневой путь.

Для исправления этого необходимо определить язык браузера пользователя и перенаправить его на лучший префикс языка. Рекомендуемый подход — использовать LocaleMiddleware из Django:

# my_project/settings.py

MIDDLEWARE = [
    # ...
    'django.middleware.locale.LocaleMiddleware',
    # ...
]

Настройка маршрутизации/определения языка

Вам строго не нужно использовать i18n_patterns или LocaleMiddleware, и вы можете написать свою собственную логику, если это необходимо.

Wagtail нужно только активировать язык (используя функцию django.utils.translation.activate из Django) перед вызовом представления wagtail.core.views.serve.

Рецепты для интернационализированных сайтов

Выбор языка/региона

Возможно, самая важная часть пользовательского интерфейса для интернационализации сайта — это выбор языка, который позволяет пользователям переключаться между различными языками.

Если вы не уверены, что вам это нужно, ознакомьтесь со статьей https://www.w3.org/International/questions/qa-site-conneg#yyyshortcomings, чтобы понять некоторые причины.

Базовый пример

Вот базовый пример добавления ссылок между переводами страницы.

Однако этот пример будет включать только языки, определенные в WAGTAIL_CONTENT_LANGUAGES и не будет включать любые дополнительные языки, которые могут быть определены в LANGUAGES. Для получения дополнительной информации о значении этих параметров см. Настройка доступных языков.

Если оба параметра имеют одинаковое значение, этот пример должен хорошо работать для вас. В противном случае перейдите к следующему разделу, который содержит более сложный пример, учитывающий этот момент.

{# make sure these are at the top of the file #}
{% load i18n wagtailcore_tags %}

{% if page %}
    {% for translation in page.get_translations.live %}
        {% get_language_info for translation.locale.language_code as lang %}
        <a href="{% pageurl translation %}" rel="alternate" hreflang="{{ language_code }}">
            {{ lang.name_local }}
        </a>
    {% endfor %}
{% endif %}

Давайте разберем это:

{% if page %}
    ...
{% endif %}

Если это часть общего шаблона базовой страницы, он может использоваться в ситуациях, когда объект страницы недоступен, например, при ответах с ошибкой 404, поэтому проверьте наличие страницы перед продолжением.

{% for translation in page.get_translations.live %}
    ...
{% endfor %}

Этот блок for перебирает все опубликованные переводы текущей страницы.

{% get_language_info for translation.locale.language_code as lang %}

Это встроенная метка Django, которая получает информацию о языке перевода. Для получения дополнительной информации см. get_language_info() в документации Django.

<a href="{% pageurl translation %}" rel="alternate" hreflang="{{ language_code }}">
    {{ lang.name_local }}
</a>

Это добавляет ссылку на перевод. Мы используем {{ lang.name_local }} для отображения названия языкового варианта на его собственном языке. Мы также добавляем атрибуты rel и hreflang в тег <a> для SEO.

Обработка языковых вариантов, которые используют общий контент

Вместо перебора страниц этот пример перебирает все настроенные языки и находит страницу для каждого из них. Это работает лучше, чем пример Базовый пример выше на сайтах, где дополнительные Django LANGUAGES используют тот же контент Wagtail.

Для работы этого примера сначала необходимо добавить процессор контекста Django django.template.context_processors.i18n в настройку TEMPLATES:

# myproject/settings.py

TEMPLATES = [
    {
        # ...
        'OPTIONS': {
            'context_processors': [
                # ...
                'django.template.context_processors.i18n',
            ],
        },
    },
]

Теперь сам пример:

{% for language_code, language_name in LANGUAGES %}
    {% get_language_info for language_code as lang %}

    {% language language_code %}
        <a href="{% pageurl page.localized %}" rel="alternate" hreflang="{{ language_code }}">
            {{ lang.name_local }}
        </a>
    {% endlanguage %}
{% endfor %}

Давайте разберем это:

{% for language_code, language_name in LANGUAGES %}
    ...
{% endfor %}

Этот блок for перебирает все настроенные языки на сайте. Переменная LANGUAGES поступает от процессора контекста django.template.context_processors.i18n.

{% get_language_info for language_code as lang %}

Делает точно то же самое, что и предыдущий пример.

{% language language_code %}
    ...
{% endlanguage %}

Этот тег language взят из библиотеки тегов Django i18n. Он изменяет активный язык только для кода, заключенного внутри него.

<a href="{% pageurl page.localized %}" rel="alternate" hreflang="{{ language_code }}">
    {{ lang.name_local }}
</a>

Единственное различие тега <a> здесь от тега <a> в предыдущем примере заключается в том, как мы получаем URL страницы: {% pageurl page.localized %}.

У всех экземпляров страниц в Wagtail есть атрибут .localized, который извлекает перевод страницы на текущем активном языке. Именно поэтому мы активировали язык ранее.

Еще одно отличие здесь состоит в том, что если одна и та же переведенная страница используется в двух языковых вариантах, Wagtail сгенерирует правильный URL-адрес страницы на основе текущего активного языкового варианта. Это ключевое различие между этим примером и предыдущим, так как предыдущий пример может получить только URL-адрес страницы в ее стандартном языковом варианте.

Фильтры API для сайтов без головки

Для сайтов без головки API Wagtail поддерживает два дополнительных фильтра для интернационализированных сайтов:

• ?locale= Фильтрует страницы по заданному языковому варианту
• ?translation_of= Фильтрует страницы, чтобы включать только переводы заданного идентификатора страницы

Для получения дополнительной информации см. Специальные фильтры для интернационализированных сайтов.

Переводимые фрагменты

Вы можете сделать фрагмент переводимым, унаследовав его от wagtail.core.models.TranslatableMixin. Например:

# myapp/models.py

from django.db import models

from wagtail.core.models import TranslatableMixin
from wagtail.snippets.models import register_snippet


@register_snippet
class Advert(TranslatableMixin, models.Model):
    name = models.CharField(max_length=255)

Модель TranslatableMixin добавляет поля locale и translation_key в модель.

Преобразование фрагментов с существующими данными в переводимые

Для фрагментов с существующими данными невозможно просто добавить TranslatableMixin, выполнить миграцию и запустить ее. Это связано с тем, что поля locale и translation_key являются обязательными, и translation_key требует уникального значения для каждого экземпляра.

Чтобы правильно мигрировать существующие данные, нам сначала нужно использовать BootstrapTranslatableMixin, что исключает эти ограничения, затем добавить миграцию данных для установки двух полей, а затем переключиться на TranslatableMixin.

Это необходимо только в том случае, если в базе данных есть записи. Так что если модель пуста, вы можете сразу добавить TranslatableMixin и пропустить этот раздел.

Шаг 1: Добавление BootstrapTranslatableMixin в модель

Это добавит два поля без каких-либо ограничений:

# myapp/models.py

from django.db import models

from wagtail.core.models import BootstrapTranslatableMixin
from wagtail.snippets.models import register_snippet


@register_snippet
class Advert(BootstrapTranslatableMixin, models.Model):
    name = models.CharField(max_length=255)

    # if the model has a Meta class, ensure it inherits from
    # BootstrapTranslatableMixin.Meta too
    class Meta(BootstrapTranslatableMixin.Meta):
        verbose_name = 'adverts'

Запустите python manage.py makemigrations myapp для генерации миграции схемы.

Шаг 2: Создание миграции данных

Создайте миграцию данных с помощью следующей команды:

python manage.py makemigrations myapp --empty

Это создаст новую пустую миграцию в папке migrations приложения. Откройте эту миграцию и добавьте BootstrapTranslatableModel для каждой модели для инициализации в этом приложении:

from django.db import migrations
from wagtail.core.models import BootstrapTranslatableModel

class Migration(migrations.Migration):
    dependencies = [
        ('myapp', '0002_bootstraptranslations'),
    ]

    # Add one operation for each model to bootstrap here
    # Note: Only include models that are in the same app!
    operations = [
        BootstrapTranslatableModel('myapp.Advert'),
    ]

Повторите это для всех других приложений, содержащих модели, которые необходимо инициализировать.

Шаг 3: Изменение BootstrapTranslatableMixin на TranslatableMixin

Теперь, когда у нас есть миграция, заполняющая необходимые поля, мы можем заменить BootstrapTranslatableMixin на TranslatableMixin с всеми ограничениями:

# myapp/models.py

from wagtail.core.models import TranslatableMixin  # Change this line

@register_snippet
class Advert(TranslatableMixin, models.Model):  # Change this line
    name = models.CharField(max_length=255)

    class Meta(TranslatableMixin.Meta):  # Change this line, if present
        verbose_name = 'adverts'

Шаг 4: Запуск makemigrations для генерации миграций схемы, а затем миграции!

Запустите makemigrations для генерации миграции схемы, которая добавляет ограничения в базу данных, а затем запустите migrate для выполнения всех миграций:

python manage.py makemigrations myapp
python manage.py migrate

При запросе выбора исправления для поля 'locale', которое становится не nullable, выберите параметр «Игнорировать на данный момент» (так как это было обработано миграцией данных).

Процесс перевода

Как упоминалось в начале, Wagtail предоставляет wagtail.contrib.simple_translation.

Модуль simple_translation предоставляет пользовательский интерфейс, который позволяет пользователям копировать страницы и переводимые фрагменты на другой язык.

• Копии создаются на языке источника (не переведены)
• Копии страниц имеют статус черновика

Редакторам контента необходимо перевести контент и опубликовать страницы.

Для активации добавьте "wagtail.contrib.simple_translation" в INSTALLED_APPS и запустите python manage.py migrate для создания разрешений submit_translation. В интерфейсе администрирования Wagtail перейдите в настройки и предоставьте некоторым пользователям или группам разрешение «Может отправлять переводы».

Wagtail Localize

В рамках первоначальной работы по реализации интернационализации для Wagtail core, мы также создали пакет перевода под названием wagtail-localize. Он поддерживает перевод страниц в Wagtail с использованием файлов PO, машинного перевода и внешней интеграции с сервисами перевода.

Github: https://github.com/wagtail/wagtail-localize

Альтернативные плагины для интернационализации

Перед добавлением официальной поддержки нескольких языков в Wagtail, разработчики сайтов должны были использовать сторонние плагины. Они не были заменены собственными реализациями Wagtail, так как используют несколько отличные подходы, и один из них может лучше подойти для вашего случая:

• Wagtailtrans
• wagtail-modeltranslation

Для сравнения этих вариантов, обратитесь к записи в блоге AccordBox Как поддержать несколько языков в CMS Wagtail.

Переводы админ-панели Wagtail

Админ-панель Wagtail переведена на многие языки. Список доступных переводов можно найти на странице Transifex. (Обратите внимание: если вы используете старую версию Wagtail, эта страница может не отражать доступные языки).

Если вашего языка нет в этом списке, вы можете легко внести вклад в новые языки или исправить ошибки. Зарегистрируйтесь и отправьте изменения на Transifex. Обновления переводов обычно включаются в официальный релиз в течение месяца после отправки.

Изменение языка админ-панели Wagtail для каждого пользователя

Авторизованные пользователи могут установить свой предпочтительный язык в /admin/account/. По умолчанию Wagtail предоставляет список языков с покрытием переводов >= 90%. Этот список можно переопределить через настройку WAGTAILADMIN_PERMITTED_LANGUAGES.

В случае, если разрешено только один или ноль языков, форма будет скрыта.

Если пользователь не выбрал язык, будет использоваться LANGUAGE_CODE.

Изменение основного языка вашей установки Wagtail

По умолчанию язык Wagtail — en-us (американский английский). Вы можете изменить его, внеся несколько изменений в настройки Django:

• Убедитесь, что USE_I18N установлено в True.
• Установите LANGUAGE_CODE на основной язык вашего сайта.

Если для вашего языка есть перевод, админ-панель Wagtail теперь должна быть на выбранном языке.