wagtail-sidebyside 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- wagtail_sidebyside-0.1.0/.gitignore +10 -0
- wagtail_sidebyside-0.1.0/CHANGELOG.md +11 -0
- wagtail_sidebyside-0.1.0/LICENSE +21 -0
- wagtail_sidebyside-0.1.0/PKG-INFO +270 -0
- wagtail_sidebyside-0.1.0/README.md +243 -0
- wagtail_sidebyside-0.1.0/pyproject.toml +63 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/__init__.py +0 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/action_menu.py +57 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/apps.py +13 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/conf.py +16 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/fields.py +406 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/forms.py +170 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/locale/fr/LC_MESSAGES/django.mo +0 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/locale/fr/LC_MESSAGES/django.po +637 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/locale/nl/LC_MESSAGES/django.mo +0 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/locale/nl/LC_MESSAGES/django.po +633 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/management/__init__.py +0 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/management/commands/__init__.py +0 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/management/commands/import_localize_drafts.py +64 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/managers.py +35 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/migrations/0001_initial.py +40 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/migrations/0002_translationsettings.py +53 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/migrations/0003_drop_wagtail_localize.py +11 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/migrations/0004_removed_translations.py +17 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/migrations/0005_instructions_help_text.py +21 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/migrations/0006_ai_usage.py +46 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/migrations/0007_awaiting_source.py +17 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/migrations/__init__.py +0 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/models.py +103 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/panels.py +24 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/signals.py +16 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/static/sidebyside/sidebyside.css +533 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/static/sidebyside/translate.js +143 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/templates/sidebyside/create.html +22 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/templates/sidebyside/dashboard_panel.html +21 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/templates/sidebyside/includes/object_preview.html +11 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/templates/sidebyside/includes/translation_bar.html +27 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/templates/sidebyside/includes/translation_bar_button.html +7 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/templates/sidebyside/overview.html +47 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/templates/sidebyside/panels/machine_translation_status.html +3 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/templates/sidebyside/translate.html +236 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/templates/sidebyside/translators/claude_status.html +64 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/templates/sidebyside/translators/status.html +9 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/templates/sidebyside/translators/usage.html +32 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/templates/wagtailadmin/pages/edit.html +12 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/templates/wagtailadmin/pages/explorable_index.html +12 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/templatetags/__init__.py +0 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/templatetags/sidebyside_tags.py +64 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/translators/__init__.py +68 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/translators/claude.py +233 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/use_cases/__init__.py +0 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/use_cases/machine_translate.py +86 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/use_cases/page_status.py +99 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/use_cases/sync_tree.py +83 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/use_cases/translate_page.py +359 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/views.py +323 -0
- wagtail_sidebyside-0.1.0/src/wagtail_sidebyside/wagtail_hooks.py +161 -0
- wagtail_sidebyside-0.1.0/tests/__init__.py +0 -0
- wagtail_sidebyside-0.1.0/tests/demo.py +102 -0
- wagtail_sidebyside-0.1.0/tests/demo_settings.py +8 -0
- wagtail_sidebyside-0.1.0/tests/demo_translator.py +21 -0
- wagtail_sidebyside-0.1.0/tests/settings.py +87 -0
- wagtail_sidebyside-0.1.0/tests/test_extension.py +85 -0
- wagtail_sidebyside-0.1.0/tests/test_translate.py +1238 -0
- wagtail_sidebyside-0.1.0/tests/testapp/__init__.py +0 -0
- wagtail_sidebyside-0.1.0/tests/testapp/apps.py +6 -0
- wagtail_sidebyside-0.1.0/tests/testapp/migrations/0001_initial.py +107 -0
- wagtail_sidebyside-0.1.0/tests/testapp/migrations/__init__.py +0 -0
- wagtail_sidebyside-0.1.0/tests/testapp/models.py +60 -0
- wagtail_sidebyside-0.1.0/tests/testapp/templates/testapp/chart_block.html +1 -0
- wagtail_sidebyside-0.1.0/tests/testapp/templates/testapp/test_page.html +17 -0
- wagtail_sidebyside-0.1.0/tests/urls.py +10 -0
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.1.0 (2026-11-17)
|
|
4
|
+
|
|
5
|
+
First release.
|
|
6
|
+
|
|
7
|
+
- Side-by-side translation screen, tree sync, live preview.
|
|
8
|
+
- Machine translation with Claude (optional extra `claude`), pluggable backends.
|
|
9
|
+
- Hooks: `sidebyside_block_kind`, `sidebyside_construct_rows`,
|
|
10
|
+
`sidebyside_before_save_translation`, `sidebyside_after_save_translation`.
|
|
11
|
+
- `import_localize_drafts` command for moving from wagtail-localize.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 PythonUnited
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,270 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: wagtail-sidebyside
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Translate Wagtail pages side by side: one main language, translations next to the source, optional AI.
|
|
5
|
+
Project-URL: Homepage, https://github.com/PythonUnited/wagtail-sidebyside
|
|
6
|
+
Project-URL: Issues, https://github.com/PythonUnited/wagtail-sidebyside/issues
|
|
7
|
+
Project-URL: Changelog, https://github.com/PythonUnited/wagtail-sidebyside/blob/main/CHANGELOG.md
|
|
8
|
+
Author: PythonUnited
|
|
9
|
+
License-Expression: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Environment :: Web Environment
|
|
13
|
+
Classifier: Framework :: Django
|
|
14
|
+
Classifier: Framework :: Wagtail
|
|
15
|
+
Classifier: Intended Audience :: Developers
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
21
|
+
Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
|
|
22
|
+
Requires-Python: >=3.12
|
|
23
|
+
Requires-Dist: wagtail<9,>=8.1
|
|
24
|
+
Provides-Extra: claude
|
|
25
|
+
Requires-Dist: anthropic>=2.9; extra == 'claude'
|
|
26
|
+
Description-Content-Type: text/markdown
|
|
27
|
+
|
|
28
|
+
# wagtail-sidebyside
|
|
29
|
+
|
|
30
|
+
> **Why this exists:** we built it because the existing translation solutions
|
|
31
|
+
> for Wagtail were simply not good enough for us. Editors translated one string
|
|
32
|
+
> at a time without seeing the page, saving and publishing were separate from
|
|
33
|
+
> Wagtail's own flow, So we made the editor we wanted: the whole page,
|
|
34
|
+
> side by side, one save.
|
|
35
|
+
>
|
|
36
|
+
> **Made with Claude:** this package was designed and written together with
|
|
37
|
+
> [Claude Opus 5.5](https://www.anthropic.com/claude) (Anthropic), in Claude
|
|
38
|
+
> Code, by a developer at [PythonUnited](https://github.com/PythonUnited).
|
|
39
|
+
|
|
40
|
+
Translate Wagtail pages side by side. One main language, every other language
|
|
41
|
+
is a translation of it. The editor sees the source next to the translation,
|
|
42
|
+
field by field, and saves or publishes the whole page at once. Optional machine
|
|
43
|
+
translation with AI.
|
|
44
|
+
|
|
45
|
+

|
|
46
|
+
|
|
47
|
+
- **Side by side**: every text of the page in one screen, including StreamField
|
|
48
|
+
blocks, the slug and the SEO fields, in the order of the editor.
|
|
49
|
+
- **One save**: "Save draft" and "Publish" for the whole translation, with
|
|
50
|
+
Wagtail's own action menu, revisions, history and live preview.
|
|
51
|
+
- **Knows what changed**: every field is *to do*, *done*, *outdated* (with a
|
|
52
|
+
word diff of the source change) or *to review* (AI or reused text).
|
|
53
|
+
- **Tree in sync**: new source pages get their translations; moving,
|
|
54
|
+
unpublishing and deleting cascade. A translation is never published ahead of
|
|
55
|
+
its source.
|
|
56
|
+
- **AI** (optional): translate one field or all empty fields with Claude, with a
|
|
57
|
+
glossary, house style instructions and a monthly budget.
|
|
58
|
+
- **Built on Wagtail core i18n** (`Locale`, `TranslatableMixin`): no extra
|
|
59
|
+
translation tables, no monkey patching. Extend it with hooks.
|
|
60
|
+
|
|
61
|
+
| The source page | All translations |
|
|
62
|
+
| --- | --- |
|
|
63
|
+
|  |  |
|
|
64
|
+
|
|
65
|
+
Live preview while translating:
|
|
66
|
+
|
|
67
|
+

|
|
68
|
+
|
|
69
|
+
## Requirements
|
|
70
|
+
|
|
71
|
+
Python 3.12+, Wagtail 8.1+.
|
|
72
|
+
|
|
73
|
+
## Install
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
pip install wagtail-sidebyside # without machine translation
|
|
77
|
+
pip install "wagtail-sidebyside[claude]" # with machine translation by Claude
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
```python
|
|
81
|
+
INSTALLED_APPS = [
|
|
82
|
+
"wagtail_sidebyside", # before wagtail.admin: it extends the page editor
|
|
83
|
+
# ...
|
|
84
|
+
"wagtail.contrib.settings",
|
|
85
|
+
"wagtail.locales",
|
|
86
|
+
"wagtail.admin",
|
|
87
|
+
"wagtail",
|
|
88
|
+
# ...
|
|
89
|
+
]
|
|
90
|
+
|
|
91
|
+
WAGTAIL_I18N_ENABLED = True
|
|
92
|
+
WAGTAIL_CONTENT_LANGUAGES = LANGUAGES = [("fr", "Francais"), ("en", "English")]
|
|
93
|
+
|
|
94
|
+
SIDEBYSIDE = {
|
|
95
|
+
"SOURCE_LOCALE": "fr", # the main language; default: Wagtail's default locale
|
|
96
|
+
}
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
python manage.py migrate
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
Add the locales under Settings > Locales. New source pages get their
|
|
104
|
+
translations right away; for existing pages the translation bar above the page
|
|
105
|
+
has a button to create them. Editors find all work under **Translations** in
|
|
106
|
+
the menu.
|
|
107
|
+
|
|
108
|
+
## Settings
|
|
109
|
+
|
|
110
|
+
All in the `SIDEBYSIDE` dict:
|
|
111
|
+
|
|
112
|
+
| Key | Default | |
|
|
113
|
+
| --- | --- | --- |
|
|
114
|
+
| `SOURCE_LOCALE` | Wagtail's default locale | Language code of the main language. |
|
|
115
|
+
| `TRANSLATOR` | `"wagtail_sidebyside.translators.claude.ClaudeTranslator"` | Machine translation backend, see below. |
|
|
116
|
+
| `AI_PROVIDER` | `""` (off) | Claude: `"anthropic"` or `"foundry"` (Microsoft Foundry / Azure). |
|
|
117
|
+
| `AI_MODEL` | `"claude-opus-5-5"` | Claude model. |
|
|
118
|
+
| `AI_PRICES` | built in | `{model: (input, output)}` in USD per million tokens, for the cost estimate. |
|
|
119
|
+
|
|
120
|
+
Fields that are the same in every language (an image, a colour) go in the page
|
|
121
|
+
model:
|
|
122
|
+
|
|
123
|
+
```python
|
|
124
|
+
class BlogPage(Page):
|
|
125
|
+
translation_exclude = ["header_image"]
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
Choice fields and blocks without text are copied from the source anyway.
|
|
129
|
+
|
|
130
|
+
## Machine translation
|
|
131
|
+
|
|
132
|
+
With Claude directly, create a key at [platform.claude.com](https://platform.claude.com)
|
|
133
|
+
(tip: in a workspace with a spend limit) and put it in the server's
|
|
134
|
+
environment, not in a settings file:
|
|
135
|
+
|
|
136
|
+
```bash
|
|
137
|
+
ANTHROPIC_API_KEY=sk-ant-api...
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
```python
|
|
141
|
+
SIDEBYSIDE = {"SOURCE_LOCALE": "fr", "AI_PROVIDER": "anthropic"}
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
Through Microsoft Foundry: `"AI_PROVIDER": "foundry"` with
|
|
145
|
+
`ANTHROPIC_FOUNDRY_API_KEY` and `ANTHROPIC_FOUNDRY_RESOURCE`.
|
|
146
|
+
|
|
147
|
+
Editors manage the rest in **Settings > Translations**: switch AI on or off,
|
|
148
|
+
a monthly budget (the AI buttons hide when it is reached), a glossary
|
|
149
|
+
(`fromage = cheese`) and instructions for tone and style. The page also shows
|
|
150
|
+
this month's usage and a "Test connection" button.
|
|
151
|
+
|
|
152
|
+
AI never saves by itself: a machine translation is marked *to review* until an
|
|
153
|
+
editor saves it.
|
|
154
|
+
|
|
155
|
+
## Extending
|
|
156
|
+
|
|
157
|
+
### Another translation service
|
|
158
|
+
|
|
159
|
+
Subclass `Translator` and point `SIDEBYSIDE["TRANSLATOR"]` at it:
|
|
160
|
+
|
|
161
|
+
```python
|
|
162
|
+
from wagtail_sidebyside.translators import TranslationError, Translator, Usage
|
|
163
|
+
|
|
164
|
+
|
|
165
|
+
class DeepLTranslator(Translator):
|
|
166
|
+
def available(self):
|
|
167
|
+
return bool(os.environ.get("DEEPL_KEY"))
|
|
168
|
+
|
|
169
|
+
def translate(self, items, source, target, glossary="", instructions=""):
|
|
170
|
+
# items: [(text, is_html), ...]; source/target: language names
|
|
171
|
+
texts = ... # call the service, raise TranslationError on failure
|
|
172
|
+
return texts, Usage(input_tokens=..., output_tokens=...)
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
Optional: `status()` and `status_template` for the settings screen, `check()`
|
|
176
|
+
for "Test connection", `cost(usage)` for the budget.
|
|
177
|
+
|
|
178
|
+
### Hooks
|
|
179
|
+
|
|
180
|
+
Standard [Wagtail hooks](https://docs.wagtail.org/en/stable/reference/hooks.html),
|
|
181
|
+
in your app's `wagtail_hooks.py`:
|
|
182
|
+
|
|
183
|
+
```python
|
|
184
|
+
from wagtail import hooks
|
|
185
|
+
|
|
186
|
+
|
|
187
|
+
@hooks.register("sidebyside_block_kind")
|
|
188
|
+
def block_kind(block):
|
|
189
|
+
"""How a leaf block is translated: "text", "textarea", "richtext",
|
|
190
|
+
"html", "image", "document", False (not translatable) or None (default)."""
|
|
191
|
+
if isinstance(block, MapBlock):
|
|
192
|
+
return False
|
|
193
|
+
|
|
194
|
+
|
|
195
|
+
@hooks.register("sidebyside_construct_rows")
|
|
196
|
+
def construct_rows(rows, source, target):
|
|
197
|
+
"""Change the rows of the translation screen in place."""
|
|
198
|
+
rows[:] = [row for row in rows if row.unit.path != "seo_title"]
|
|
199
|
+
|
|
200
|
+
|
|
201
|
+
@hooks.register("sidebyside_before_save_translation")
|
|
202
|
+
def before_save(request, source_page, target_page):
|
|
203
|
+
"""Return a response to stop the save."""
|
|
204
|
+
|
|
205
|
+
|
|
206
|
+
@hooks.register("sidebyside_after_save_translation")
|
|
207
|
+
def after_save(request, source_page, target_page, revision):
|
|
208
|
+
"""Return a response to replace the redirect."""
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
## Coming from wagtail-localize
|
|
212
|
+
|
|
213
|
+
Both use Wagtail core i18n, so pages and their translations stay as they are.
|
|
214
|
+
wagtail-sidebyside treats the translated text already on the pages as done.
|
|
215
|
+
One catch: wagtail-localize only writes a translation into the page when it is
|
|
216
|
+
published. Translations that were entered but never published live only in
|
|
217
|
+
wagtail-localize's own tables. Step 1 saves those as drafts before
|
|
218
|
+
wagtail-localize goes. On a live site, deploy step 1 and step 2 separately.
|
|
219
|
+
|
|
220
|
+
**Step 1: install next to wagtail-localize**
|
|
221
|
+
|
|
222
|
+
```python
|
|
223
|
+
INSTALLED_APPS = [
|
|
224
|
+
"wagtail_sidebyside", # before wagtail.admin
|
|
225
|
+
"wagtail_localize", # stays for now
|
|
226
|
+
"wagtail.locales", # instead of "wagtail_localize.locales"
|
|
227
|
+
"wagtail.contrib.settings",
|
|
228
|
+
# ...
|
|
229
|
+
]
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
```bash
|
|
233
|
+
pip install "wagtail-sidebyside[claude]"
|
|
234
|
+
python manage.py migrate
|
|
235
|
+
python manage.py import_localize_drafts --dry-run # lists the waiting translations
|
|
236
|
+
python manage.py import_localize_drafts # saves them as drafts
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
Live pages are not changed; the drafts show up in the side-by-side screen
|
|
240
|
+
as work to finish.
|
|
241
|
+
|
|
242
|
+
**Step 2: remove wagtail-localize**
|
|
243
|
+
|
|
244
|
+
```bash
|
|
245
|
+
python manage.py migrate wagtail_localize zero # drops its tables
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
Then:
|
|
249
|
+
|
|
250
|
+
- remove `"wagtail_localize"` (and `"wagtail_localize.modeladmin"` if used)
|
|
251
|
+
from `INSTALLED_APPS`;
|
|
252
|
+
- remove `wagtail-localize` from your requirements;
|
|
253
|
+
- remove `translatable_fields` and the `wagtail_localize` imports from your
|
|
254
|
+
models. Fields that were a `SynchronizedField` (the same in every language)
|
|
255
|
+
go in `translation_exclude`;
|
|
256
|
+
- remove any templates or code that use `wagtail_localize`.
|
|
257
|
+
|
|
258
|
+
## Development
|
|
259
|
+
|
|
260
|
+
```bash
|
|
261
|
+
uv sync
|
|
262
|
+
uv run pytest
|
|
263
|
+
uv run python -m tests.demo # demo site on http://localhost:8000/cms/ (admin/admin)
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
The demo uses a fake translator, so no API key is needed.
|
|
267
|
+
|
|
268
|
+
## License
|
|
269
|
+
|
|
270
|
+
MIT, see [LICENSE](LICENSE).
|
|
@@ -0,0 +1,243 @@
|
|
|
1
|
+
# wagtail-sidebyside
|
|
2
|
+
|
|
3
|
+
> **Why this exists:** we built it because the existing translation solutions
|
|
4
|
+
> for Wagtail were simply not good enough for us. Editors translated one string
|
|
5
|
+
> at a time without seeing the page, saving and publishing were separate from
|
|
6
|
+
> Wagtail's own flow, So we made the editor we wanted: the whole page,
|
|
7
|
+
> side by side, one save.
|
|
8
|
+
>
|
|
9
|
+
> **Made with Claude:** this package was designed and written together with
|
|
10
|
+
> [Claude Opus 5.5](https://www.anthropic.com/claude) (Anthropic), in Claude
|
|
11
|
+
> Code, by a developer at [PythonUnited](https://github.com/PythonUnited).
|
|
12
|
+
|
|
13
|
+
Translate Wagtail pages side by side. One main language, every other language
|
|
14
|
+
is a translation of it. The editor sees the source next to the translation,
|
|
15
|
+
field by field, and saves or publishes the whole page at once. Optional machine
|
|
16
|
+
translation with AI.
|
|
17
|
+
|
|
18
|
+

|
|
19
|
+
|
|
20
|
+
- **Side by side**: every text of the page in one screen, including StreamField
|
|
21
|
+
blocks, the slug and the SEO fields, in the order of the editor.
|
|
22
|
+
- **One save**: "Save draft" and "Publish" for the whole translation, with
|
|
23
|
+
Wagtail's own action menu, revisions, history and live preview.
|
|
24
|
+
- **Knows what changed**: every field is *to do*, *done*, *outdated* (with a
|
|
25
|
+
word diff of the source change) or *to review* (AI or reused text).
|
|
26
|
+
- **Tree in sync**: new source pages get their translations; moving,
|
|
27
|
+
unpublishing and deleting cascade. A translation is never published ahead of
|
|
28
|
+
its source.
|
|
29
|
+
- **AI** (optional): translate one field or all empty fields with Claude, with a
|
|
30
|
+
glossary, house style instructions and a monthly budget.
|
|
31
|
+
- **Built on Wagtail core i18n** (`Locale`, `TranslatableMixin`): no extra
|
|
32
|
+
translation tables, no monkey patching. Extend it with hooks.
|
|
33
|
+
|
|
34
|
+
| The source page | All translations |
|
|
35
|
+
| --- | --- |
|
|
36
|
+
|  |  |
|
|
37
|
+
|
|
38
|
+
Live preview while translating:
|
|
39
|
+
|
|
40
|
+

|
|
41
|
+
|
|
42
|
+
## Requirements
|
|
43
|
+
|
|
44
|
+
Python 3.12+, Wagtail 8.1+.
|
|
45
|
+
|
|
46
|
+
## Install
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
pip install wagtail-sidebyside # without machine translation
|
|
50
|
+
pip install "wagtail-sidebyside[claude]" # with machine translation by Claude
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
```python
|
|
54
|
+
INSTALLED_APPS = [
|
|
55
|
+
"wagtail_sidebyside", # before wagtail.admin: it extends the page editor
|
|
56
|
+
# ...
|
|
57
|
+
"wagtail.contrib.settings",
|
|
58
|
+
"wagtail.locales",
|
|
59
|
+
"wagtail.admin",
|
|
60
|
+
"wagtail",
|
|
61
|
+
# ...
|
|
62
|
+
]
|
|
63
|
+
|
|
64
|
+
WAGTAIL_I18N_ENABLED = True
|
|
65
|
+
WAGTAIL_CONTENT_LANGUAGES = LANGUAGES = [("fr", "Francais"), ("en", "English")]
|
|
66
|
+
|
|
67
|
+
SIDEBYSIDE = {
|
|
68
|
+
"SOURCE_LOCALE": "fr", # the main language; default: Wagtail's default locale
|
|
69
|
+
}
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
python manage.py migrate
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Add the locales under Settings > Locales. New source pages get their
|
|
77
|
+
translations right away; for existing pages the translation bar above the page
|
|
78
|
+
has a button to create them. Editors find all work under **Translations** in
|
|
79
|
+
the menu.
|
|
80
|
+
|
|
81
|
+
## Settings
|
|
82
|
+
|
|
83
|
+
All in the `SIDEBYSIDE` dict:
|
|
84
|
+
|
|
85
|
+
| Key | Default | |
|
|
86
|
+
| --- | --- | --- |
|
|
87
|
+
| `SOURCE_LOCALE` | Wagtail's default locale | Language code of the main language. |
|
|
88
|
+
| `TRANSLATOR` | `"wagtail_sidebyside.translators.claude.ClaudeTranslator"` | Machine translation backend, see below. |
|
|
89
|
+
| `AI_PROVIDER` | `""` (off) | Claude: `"anthropic"` or `"foundry"` (Microsoft Foundry / Azure). |
|
|
90
|
+
| `AI_MODEL` | `"claude-opus-5-5"` | Claude model. |
|
|
91
|
+
| `AI_PRICES` | built in | `{model: (input, output)}` in USD per million tokens, for the cost estimate. |
|
|
92
|
+
|
|
93
|
+
Fields that are the same in every language (an image, a colour) go in the page
|
|
94
|
+
model:
|
|
95
|
+
|
|
96
|
+
```python
|
|
97
|
+
class BlogPage(Page):
|
|
98
|
+
translation_exclude = ["header_image"]
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
Choice fields and blocks without text are copied from the source anyway.
|
|
102
|
+
|
|
103
|
+
## Machine translation
|
|
104
|
+
|
|
105
|
+
With Claude directly, create a key at [platform.claude.com](https://platform.claude.com)
|
|
106
|
+
(tip: in a workspace with a spend limit) and put it in the server's
|
|
107
|
+
environment, not in a settings file:
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
ANTHROPIC_API_KEY=sk-ant-api...
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
```python
|
|
114
|
+
SIDEBYSIDE = {"SOURCE_LOCALE": "fr", "AI_PROVIDER": "anthropic"}
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Through Microsoft Foundry: `"AI_PROVIDER": "foundry"` with
|
|
118
|
+
`ANTHROPIC_FOUNDRY_API_KEY` and `ANTHROPIC_FOUNDRY_RESOURCE`.
|
|
119
|
+
|
|
120
|
+
Editors manage the rest in **Settings > Translations**: switch AI on or off,
|
|
121
|
+
a monthly budget (the AI buttons hide when it is reached), a glossary
|
|
122
|
+
(`fromage = cheese`) and instructions for tone and style. The page also shows
|
|
123
|
+
this month's usage and a "Test connection" button.
|
|
124
|
+
|
|
125
|
+
AI never saves by itself: a machine translation is marked *to review* until an
|
|
126
|
+
editor saves it.
|
|
127
|
+
|
|
128
|
+
## Extending
|
|
129
|
+
|
|
130
|
+
### Another translation service
|
|
131
|
+
|
|
132
|
+
Subclass `Translator` and point `SIDEBYSIDE["TRANSLATOR"]` at it:
|
|
133
|
+
|
|
134
|
+
```python
|
|
135
|
+
from wagtail_sidebyside.translators import TranslationError, Translator, Usage
|
|
136
|
+
|
|
137
|
+
|
|
138
|
+
class DeepLTranslator(Translator):
|
|
139
|
+
def available(self):
|
|
140
|
+
return bool(os.environ.get("DEEPL_KEY"))
|
|
141
|
+
|
|
142
|
+
def translate(self, items, source, target, glossary="", instructions=""):
|
|
143
|
+
# items: [(text, is_html), ...]; source/target: language names
|
|
144
|
+
texts = ... # call the service, raise TranslationError on failure
|
|
145
|
+
return texts, Usage(input_tokens=..., output_tokens=...)
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
Optional: `status()` and `status_template` for the settings screen, `check()`
|
|
149
|
+
for "Test connection", `cost(usage)` for the budget.
|
|
150
|
+
|
|
151
|
+
### Hooks
|
|
152
|
+
|
|
153
|
+
Standard [Wagtail hooks](https://docs.wagtail.org/en/stable/reference/hooks.html),
|
|
154
|
+
in your app's `wagtail_hooks.py`:
|
|
155
|
+
|
|
156
|
+
```python
|
|
157
|
+
from wagtail import hooks
|
|
158
|
+
|
|
159
|
+
|
|
160
|
+
@hooks.register("sidebyside_block_kind")
|
|
161
|
+
def block_kind(block):
|
|
162
|
+
"""How a leaf block is translated: "text", "textarea", "richtext",
|
|
163
|
+
"html", "image", "document", False (not translatable) or None (default)."""
|
|
164
|
+
if isinstance(block, MapBlock):
|
|
165
|
+
return False
|
|
166
|
+
|
|
167
|
+
|
|
168
|
+
@hooks.register("sidebyside_construct_rows")
|
|
169
|
+
def construct_rows(rows, source, target):
|
|
170
|
+
"""Change the rows of the translation screen in place."""
|
|
171
|
+
rows[:] = [row for row in rows if row.unit.path != "seo_title"]
|
|
172
|
+
|
|
173
|
+
|
|
174
|
+
@hooks.register("sidebyside_before_save_translation")
|
|
175
|
+
def before_save(request, source_page, target_page):
|
|
176
|
+
"""Return a response to stop the save."""
|
|
177
|
+
|
|
178
|
+
|
|
179
|
+
@hooks.register("sidebyside_after_save_translation")
|
|
180
|
+
def after_save(request, source_page, target_page, revision):
|
|
181
|
+
"""Return a response to replace the redirect."""
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
## Coming from wagtail-localize
|
|
185
|
+
|
|
186
|
+
Both use Wagtail core i18n, so pages and their translations stay as they are.
|
|
187
|
+
wagtail-sidebyside treats the translated text already on the pages as done.
|
|
188
|
+
One catch: wagtail-localize only writes a translation into the page when it is
|
|
189
|
+
published. Translations that were entered but never published live only in
|
|
190
|
+
wagtail-localize's own tables. Step 1 saves those as drafts before
|
|
191
|
+
wagtail-localize goes. On a live site, deploy step 1 and step 2 separately.
|
|
192
|
+
|
|
193
|
+
**Step 1: install next to wagtail-localize**
|
|
194
|
+
|
|
195
|
+
```python
|
|
196
|
+
INSTALLED_APPS = [
|
|
197
|
+
"wagtail_sidebyside", # before wagtail.admin
|
|
198
|
+
"wagtail_localize", # stays for now
|
|
199
|
+
"wagtail.locales", # instead of "wagtail_localize.locales"
|
|
200
|
+
"wagtail.contrib.settings",
|
|
201
|
+
# ...
|
|
202
|
+
]
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
```bash
|
|
206
|
+
pip install "wagtail-sidebyside[claude]"
|
|
207
|
+
python manage.py migrate
|
|
208
|
+
python manage.py import_localize_drafts --dry-run # lists the waiting translations
|
|
209
|
+
python manage.py import_localize_drafts # saves them as drafts
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
Live pages are not changed; the drafts show up in the side-by-side screen
|
|
213
|
+
as work to finish.
|
|
214
|
+
|
|
215
|
+
**Step 2: remove wagtail-localize**
|
|
216
|
+
|
|
217
|
+
```bash
|
|
218
|
+
python manage.py migrate wagtail_localize zero # drops its tables
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
Then:
|
|
222
|
+
|
|
223
|
+
- remove `"wagtail_localize"` (and `"wagtail_localize.modeladmin"` if used)
|
|
224
|
+
from `INSTALLED_APPS`;
|
|
225
|
+
- remove `wagtail-localize` from your requirements;
|
|
226
|
+
- remove `translatable_fields` and the `wagtail_localize` imports from your
|
|
227
|
+
models. Fields that were a `SynchronizedField` (the same in every language)
|
|
228
|
+
go in `translation_exclude`;
|
|
229
|
+
- remove any templates or code that use `wagtail_localize`.
|
|
230
|
+
|
|
231
|
+
## Development
|
|
232
|
+
|
|
233
|
+
```bash
|
|
234
|
+
uv sync
|
|
235
|
+
uv run pytest
|
|
236
|
+
uv run python -m tests.demo # demo site on http://localhost:8000/cms/ (admin/admin)
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
The demo uses a fake translator, so no API key is needed.
|
|
240
|
+
|
|
241
|
+
## License
|
|
242
|
+
|
|
243
|
+
MIT, see [LICENSE](LICENSE).
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "wagtail-sidebyside"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Translate Wagtail pages side by side: one main language, translations next to the source, optional AI."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
license-files = ["LICENSE"]
|
|
12
|
+
authors = [{ name = "PythonUnited" }]
|
|
13
|
+
requires-python = ">=3.12"
|
|
14
|
+
dependencies = ["wagtail>=8.1,<9"]
|
|
15
|
+
classifiers = [
|
|
16
|
+
"Development Status :: 4 - Beta",
|
|
17
|
+
"Environment :: Web Environment",
|
|
18
|
+
"Framework :: Django",
|
|
19
|
+
"Framework :: Wagtail",
|
|
20
|
+
"Intended Audience :: Developers",
|
|
21
|
+
"Operating System :: OS Independent",
|
|
22
|
+
"Programming Language :: Python :: 3",
|
|
23
|
+
"Programming Language :: Python :: 3.12",
|
|
24
|
+
"Programming Language :: Python :: 3.13",
|
|
25
|
+
"Programming Language :: Python :: 3.14",
|
|
26
|
+
"Topic :: Internet :: WWW/HTTP :: Site Management",
|
|
27
|
+
]
|
|
28
|
+
|
|
29
|
+
[project.optional-dependencies]
|
|
30
|
+
claude = ["anthropic>=2.9"]
|
|
31
|
+
|
|
32
|
+
[project.urls]
|
|
33
|
+
Homepage = "https://github.com/PythonUnited/wagtail-sidebyside"
|
|
34
|
+
Issues = "https://github.com/PythonUnited/wagtail-sidebyside/issues"
|
|
35
|
+
Changelog = "https://github.com/PythonUnited/wagtail-sidebyside/blob/main/CHANGELOG.md"
|
|
36
|
+
|
|
37
|
+
[dependency-groups]
|
|
38
|
+
dev = [
|
|
39
|
+
"anthropic>=2.9",
|
|
40
|
+
"pytest>=9",
|
|
41
|
+
"pytest-django>=4.14",
|
|
42
|
+
"ruff>=0.17",
|
|
43
|
+
]
|
|
44
|
+
|
|
45
|
+
[tool.hatch.build.targets.wheel]
|
|
46
|
+
packages = ["src/wagtail_sidebyside"]
|
|
47
|
+
|
|
48
|
+
[tool.hatch.build.targets.sdist]
|
|
49
|
+
include = ["src", "tests", "README.md", "CHANGELOG.md", "LICENSE"]
|
|
50
|
+
|
|
51
|
+
[tool.pytest.ini_options]
|
|
52
|
+
DJANGO_SETTINGS_MODULE = "tests.settings"
|
|
53
|
+
pythonpath = ["."]
|
|
54
|
+
testpaths = ["tests"]
|
|
55
|
+
addopts = ["--strict-markers"]
|
|
56
|
+
|
|
57
|
+
[tool.ruff]
|
|
58
|
+
line-length = 88
|
|
59
|
+
src = ["src", "tests"]
|
|
60
|
+
|
|
61
|
+
[tool.ruff.lint]
|
|
62
|
+
select = ["E", "F", "I", "UP", "B"]
|
|
63
|
+
ignore = ["E501"]
|
|
File without changes
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
"""Footer actions of the translation screen, on top of Wagtail's own."""
|
|
2
|
+
|
|
3
|
+
from django.utils.translation import gettext_lazy as _
|
|
4
|
+
from wagtail.admin.action_menu import (
|
|
5
|
+
ActionMenuItem,
|
|
6
|
+
CancelWorkflowMenuItem,
|
|
7
|
+
PublishMenuItem,
|
|
8
|
+
RestartWorkflowMenuItem,
|
|
9
|
+
SubmitForModerationMenuItem,
|
|
10
|
+
WorkflowMenuItem,
|
|
11
|
+
)
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
class PublishTogetherMenuItem(ActionMenuItem):
|
|
15
|
+
"""Publish the source's draft and the translation at once."""
|
|
16
|
+
|
|
17
|
+
name = "action-publish-together"
|
|
18
|
+
label = _("Publish source and translation")
|
|
19
|
+
icon_name = "upload"
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
class PublishTranslationOnlyMenuItem(PublishMenuItem):
|
|
23
|
+
label = _("Publish translation only")
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def adapt(action_menu, source_page, user):
|
|
27
|
+
"""Workflow actions are left out: the translation screen does not handle
|
|
28
|
+
moderation, so they would only save a draft. When the source has
|
|
29
|
+
unpublished changes, "Publish" publishes the translation only (against
|
|
30
|
+
the published source), with "Publish source and translation" just above
|
|
31
|
+
it. A source that was never published can only be published together
|
|
32
|
+
with its translation."""
|
|
33
|
+
items = action_menu.menu_items
|
|
34
|
+
items[:] = [
|
|
35
|
+
item
|
|
36
|
+
for item in items
|
|
37
|
+
if not isinstance(
|
|
38
|
+
item,
|
|
39
|
+
(
|
|
40
|
+
SubmitForModerationMenuItem,
|
|
41
|
+
WorkflowMenuItem,
|
|
42
|
+
RestartWorkflowMenuItem,
|
|
43
|
+
CancelWorkflowMenuItem,
|
|
44
|
+
),
|
|
45
|
+
)
|
|
46
|
+
]
|
|
47
|
+
if not source_page.has_unpublished_changes:
|
|
48
|
+
return
|
|
49
|
+
for index, item in enumerate(items):
|
|
50
|
+
if isinstance(item, PublishMenuItem):
|
|
51
|
+
if source_page.live:
|
|
52
|
+
items[index] = PublishTranslationOnlyMenuItem(order=item.order)
|
|
53
|
+
else:
|
|
54
|
+
del items[index]
|
|
55
|
+
if source_page.permissions_for_user(user).can_publish():
|
|
56
|
+
items.insert(index, PublishTogetherMenuItem())
|
|
57
|
+
return
|