An extension for wagtail-localize that integrates with the Smartling translation platform
Project description
Wagtail Localize Smartling
An extension for Wagtail Localize that integrates with the Smartling translation platform.
Links
Supported versions
- Python 3.8+
- Django 4.2+
- Wagtail 5.2+
Installation
-
Install the package from PyPI:
python -m pip install wagtail-localize-smartling
-
Add
"wagtail_localize_smartling"
toINSTALLED_APPS
in your Django settings. Make sure it's before"wagtail_localize"
and"wagtail_localize.locales"
:INSTALLED_APPS = [ ... "wagtail_localize_smartling", "wagtail_localize", "wagtail_localize.locales", ... ]
-
Configure the plugin in your Django settings:
WAGTAIL_LOCALIZE_SMARTLING = { # Required settings (get these from "Account settings" > "API" in the Smartling dashboard) "PROJECT_ID": "<project_id>", "USER_IDENTIFIER": "<user_identifier>", "USER_SECRET": "<user_secret>", # Optional settings and their default values "REQUIRED": False, # Set this to True to always send translations to Smartling "ENVIRONMENT": "production", # Set this to "staging" to use Smartling's staging API "API_TIMEOUT_SECONDS": 5.0, # Timeout in seconds for requests to the Smartling API }
If your project locales do not match those in Smartling (e.g. ro
in your project, ro-RO
in Smartling),
then you can provide a Wagtail locale id to Smartling locale id mapping via the LOCALE_TO_SMARTLING_LOCALE
setting:
WAGTAIL_LOCALIZE_SMARTLING = {
"LOCALE_TO_SMARTLING_LOCALE": {
"ro": "ro-RO"
}
}
or you can specify a callable or a dotted path to a callable in the LOCALE_MAPPING_CALLBACK
setting
def map_project_locale_to_smartling(locale: str) -> str:
if locale == "ro":
return "ro-RO"
return locale
WAGTAIL_LOCALIZE_SMARTLING = {
# ...
"LOCALE_MAPPING_CALLBACK": "settings.map_project_locale_to_smartling"
}
The callback receives a WAGTAIL_CONTENT_LANGUAGES
local code string and is expected to return
a valid mapped locale id (or the original locale id).
-
Run migrations:
./manage.py migrate
Setup
Smartling project setup
For the plugin to work with a Smartling project, the Django/Wagtail internationalization- and localization-related settings must be compatible with the project's language settings:
- Only Wagtail content authored in the same language as the Smartling project's source language can be translated.
- Ideally, the language tags in
WAGTAIL_CONTENT_LANGUAGES
should be the exact, case-insensitive matches for the Smartling projects target locales. For example, if your Smartling project targetsfr-FR
, then you must have"fr-fr"
in yourWAGTAIL_CONTENT_LANGUAGES
, not just"fr"
. However, if that is not possible, use theLOCALE_TO_SMARTLING_LOCALE
orLOCALE_MAPPING_CALLBACK
settings to map your Wagtail language codes to the Smartling language codes.
Synchronization
The plugin provides a sync_smartling
management command that:
- Creates jobs in Smartling for new content that's awaiting translation
- Checks the status of pending translation jobs
- Downloads and applies translations for completed jobs
This command should be set to run periodically via cron
or similiar:
./manage.py sync_smartling
We recommend running this regularly, around once every 10 minutes.
Callbacks
As well as the sync_smartling
management command, the plugin sets the callbackUrl
field on the Smartling jobs it creates to the URL of webhook handler view. This handler will proactively download and apply translations from completed jobs without waiting for the next sync_smartling
run. This URL is based on the WAGTAILADMIN_BASE_URL
setting, so it's important that's set and accessible from the internet.
[!WARNING] Callbacks should not be relied on as the only method for downloading translations. Always make sure the
sync_smartling
command is run regularly to ensure your translations are up-to-date.
Usage
Submitting new content for translation
Updating translations
How it works
Workflow
Submitting pages for Smartling translation
flowchart LR
submitPageForTranslation["Page submitted for translation in Wagtail"]
submitToSmartling{"
User choses to submit
translation job to Smartling?
"}
enterSmartlingJobConfig["User enters Smartling job config"]
pendingSmartlingJobCreated["A pending Smartling job is created in Wagtail"]
wagtailSyncedTranslationEditView["
User is redirected to Wagtail's
synced translation edit view
"]
submitPageForTranslation-->submitToSmartling
submitToSmartling-->|Yes|enterSmartlingJobConfig
enterSmartlingJobConfig-->pendingSmartlingJobCreated
pendingSmartlingJobCreated-->wagtailSyncedTranslationEditView
submitToSmartling-->|No|wagtailSyncedTranslationEditView
Smartling sync
django-admin sync_smartling
, the below flowchart describes the logic run for each job
flowchart LR
jobSentToSmartling{"Has the job been
sent to Smartling yet?"}
sendJobToSmartling["Send job to Smartling"]
jobFinished{"Is the job finalised?"}
updateJobFromSmartling["Update job from Smartling"]
fin["End"]
jobSentToSmartling-->|Yes|jobFinished
jobSentToSmartling-->|No|sendJobToSmartling
sendJobToSmartling-->fin
jobFinished-->|Yes|fin
jobFinished-->|No|updateJobFromSmartling
Signals
This app provides a single wagtail_localize.signals.translation_imported
signal that is sent when translation are imported from Smartling.
Signal kwargs:
sender
: Thewagtail_localize_smartling.models.Job
classinstance
: TheJob
instance for which translation are being importedtranslation
: Thewagtail_localize.models.Translation
instance the translations are being imported to. Usetranslation.get_target_instance()
to get the model instance that the translation is for (e.g. a page or snippet)
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for wagtail_localize_smartling-0.2.2.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | e2104c4a5e8037e578afee8b3364fedbf197911ec89b574363258f778731d62f |
|
MD5 | 4f89ba717040e125e5ad9426ad186e86 |
|
BLAKE2b-256 | 031f2ff43272249840c0f47b4458a83e72cd80d5568428e14803f062c4927fa4 |
Hashes for wagtail_localize_smartling-0.2.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5cf9b23c40a59adea02ddd2aa560f49a5e26fce678a9edb939d9af2fb8338c7b |
|
MD5 | c1c281f3c2b4eb9b154a1b490aee0ac4 |
|
BLAKE2b-256 | d493ebd8c60caf437eede084b44ae8d435a6bc5525b6f2684b723b455b3ca273 |