How to integrate with Pontoon
Pontoon is an open source translation management system built and maintained by Mozilla. This guide explains how to configure Wagtail Localize to use an instance of pontoon for Translation.
Git repository set up
Pontoon can only work with PO files in a Git repository, so we will need to create a git repo to use as an intermediary between the two systems.
Generate an SSH keypair for Wagtail Localize
In order for Wagtail Localize to access the git repository, it must authenticate itself with your git repository host.
The only authentication method it supports at the moment is using an SSH key.
To generate a new keypair, use the ssh-keygen
command (built in to Mac/Linux. optional feature on Windows):
ssh-keygen -f wagtail-localize-key -C wagtail-localize
It will prompt for a password, leave that blank.
Create a git repository
Now you need to create a git repo for the PO files to live in. You can use any host for this you like as long as it:
- Is accessible over the network from both Pontoon and Wagtail
- Supports deploy keys that can write to the repository (Both GitHub and Gitlab support this)
Note that you do not need to make your repo public as both Pontoon and Wagtail Localize can authenticate using a deploy key.
Once you've created your repository, add the public key (wagtail-localize-key.pub
) that you created as a deploy key.
Make sure it has write permissions.
Configuring Wagtail Localize
In this section, we will configure Wagtail Localize to push source PO files into the repository and pull translations.
Install the wagtail-localize-git
plugin
Install wagtail-localize-git
using pip, and also add it your requirements.txt
/pyproject.toml
file:
pip install wagtail-localize-git
Then, add it to your INSTALLED_APPS
django setting:
INSTALLED_APPS = [
# ...
"wagtail_localize",
# Insert this
"wagtail_localize_git",
# ...
]
Note that this app won't do anything unless it's configured, so it's safe to add it into your base settings as well.
Configure your server
Install the SSH private key
On your server, you need to add the private SSH key to the SSH keyring so that the git
command will automatically
use it. There are instructions on how to do this on Heroku at the end of this guide.
Configure the wagtail-localize-git
plugin
On your Wagtail server, you'll need to set two Django settings:
-
WAGTAILLOCALIZE_GIT_URL
should be set to the SSH git clone URL of your repository -
WAGTAILLOCALIZE_GIT_CLONE_DIR
needs to be set to a directory that Wagtail Localize can clone the git repository into.
If you're running on an ephermeral file system (such as on Heroku), this can be pointed to a temporary directory.
Wagtail Localize will re-clone the repository if it's ever deleted. It keeps track of what the previous HEAD
commit was in the database so it will not lose track of anything if a deletion occurs.
For example:
WAGTAILLOCALIZE_GIT_URL = "git@github.com:mozilla-l10n/mozilla-donate-content.git"
WAGTAILLOCALIZE_GIT_CLONE_DIR = "/tmp/wagtail-content-for-pontoon.git"
Finally, you need to set up a cron job to run the sync_git
management command periodically. I suggest that you
set it to run at least hourly, but ideally, every 10 minutes to allow translations to move between Pontoon and Wagtail
quickly.
Appendix: Installing an SSH private key on a Heroku app
Setting up an SSH private key on a Heroku can be done by putting the private key into an environment variable, and creating a setup script that copies that key into a place where git/SSH can see it.
Encoding the key
Firstly, encode the SSH private key with base64
and add it to the app with an environment variable called SSH_PRIVATE_KEY
:
base64 -w0 wagtail-localize-key
Copy the string that this outputs, and paste it into the following command (or use the web UI):
heroku config:set -a application-name-here SSH_PRIVATE_KEY=<paste base64 string here>
For regular (non container) apps
For regular Heroku apps, add a .profile
file in the root folder of your project and insert the following:
#!/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
mkdir -p $SSH_DIR
chmod 700 $SSH_DIR
echo $SSH_PRIVATE_KEY | base64 --decode > $SSH_DIR/id_rsa
chmod 400 $SSH_DIR/id_rsa
cat << EOF > $SSH_DIR/config
StrictHostKeyChecking no
EOF
chmod 600 $SSH_DIR/config
echo "Done!"
fi
For container apps
For container-based apps, you can use a Docker entrypoint to set up the SSH key.
Copy the following file into your repo, or combine it with your existing Docker entrypoint if you already have one:
#!/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
mkdir -p $SSH_DIR
chmod 700 $SSH_DIR
echo $SSH_PRIVATE_KEY | base64 --decode > $SSH_DIR/id_rsa
chmod 400 $SSH_DIR/id_rsa
cat << EOF > $SSH_DIR/config
StrictHostKeyChecking no
EOF
chmod 600 $SSH_DIR/config
echo "Done!"
fi
exec "$@"
Run chmod +x docker_entrypoint.sh
to make it executable.
Then add ENTRYPOINT ["/app/docker-entrypoint.sh"]
to your Dockerfile
(update the filename if it's different on your project).