Wagtail Localization

[KalobTaulien]

Epic for Wagtail Localization. The spike ticket can be found at #6671

All the below tasks are split into tickets in this epic, with the step number in the title so we don't get too far ahead of ourselves and need to spend time backtracking.

The localization branch we're using in this repo is the wagtail-localize-2021 branch. Note: Please keep the original wagtail-localize branch as it has code we may want to reference in there while we work on localization.

Helpful resources:

• https://docs.wagtail.io/en/stable/advanced_topics/i18n.html
• https://www.wagtail-localize.org/

Steps needed to [re]implement wagtail-localize

• Step 1. Upgrade Django ato Django 3, and Wagtail to 2.12 #6702 We really should, but don't have to, upgrade to Wagtail 2.13 and Django 3.2 before adding wagtail-localize. I think the last dry run I did up to Wagtail 2.13rc1 required me to do some model-translation work.
  • Upgrade Wagtail to 2.12.* and upgrade Django to 3.0.*
  • Upgrade Wagtail to 2.13 and upgrade Django to 3.2.*
• Step 2. Add localization "staging" site (DevOps) #6704 We need a dedicated pipeline for testing the work. @tomusher we'll need your help with this.
  • Needs CI setup to help us merge the main review branch into master later with no problems.
• Step 3. Completely remove wagtail-modeltranslation and django-modeltranslation. Upgrade Wagtail and Django after.  #6705 Remove model translation entirely before adding wagtail
  • Remove translation files
  • Remove requirement dependencies
  • Remove tests
  • Remove factory code that uses model translation
  • Look for thing_en= in the source code and remove the _en
  • Run tests to make sure everything passes
  • Merge into our review branch and let CI run for higher future-merge confidence
• Step 4. Add in wagtail-localize and enable it in our settings #6706 Add in wagtail-localize. Enable it in the settings, but don't do anything else with it yet. Let's take this in small steps.
  • Make sure tests pass.
  • Add in wagtail-localize into the requirement dependencies
  • Merge into review branch and let CI run for higher future-merge confidence
• Step 5. List out which models and fields need translating #6707 List out which fields should be TranslatableField and which fields should be SynchronizedField. @TheoChevalier we can really use your help here. A list of models/pages with which fields should be Translatable Vs Synchronized would be a life saver for implementation.
• Step 6. Snippet translations #6708 Create migrations for all snippets. This document will be very helpful. We need to bootstrap migrations for each model.
  • Make sure all snippet models are translated.
  • Make sure all snippet fields have translatable_fields = [ .. ] set on them
  • Make sure tests still pass. May need to do some adjusting for new language headers in the request object, particularly around redirects.
  • Whoever integrates this, please confirm with Theo all the fields are set properly.
• Step 6.5. Check that PNI localization works and adjust categories if needed. #6760 Check that PNI localization works and adjust categories if needed.
• Step 7. Passing tests #6709 Tests ticket:
  • We might end up at a point where we need to work on just tests for a while. I recall some of these being rather tricky. First up: Make sure cypress tests for redirects work.
  • Make sure redirect tests continue to redirect to the appropriate language
• Step 8. Make the footer language picker work. #6710 Change the language picker in the footer of the website to properly set the language of the site
• Step 9. Pontoon integration #6711 Add in pontoon integration. @Pomax you and Karl may need to work on this together.
• Step 10. Documentation #6712 Documentation:
  • Write documentation on how to implement and support pontoon with any gotchas documented as well. Might be useful to put this in the wagtail-localize.org docs.
  • We said we'd write docs for moving away from wagtail-modeltranslation and contribute it back to wagtail-localize. Lets write documentation on how we moved away from wagtail-modeltranslation to wagtail-localize, and commit the changes to the wagtail-localize docs

TRACKING DEPLOYMENT ISSUES

Use #7233 to report any issues you find while we're stage testing.

Merge requirements

• make sure wagtail-localize-2021 is up to date with current master
• run through https://www.wagtail-localize.org/how-to/integrations/pontoon for staging:
  • Generate an SSH keypair for Wagtail Localize (see vault)
  • Add the public key (wagtail-localize-key.pub) as a deploy key for the l10n repo
  • Add the SSH private key as BASE64-encoded heroku env var
  • Configure the wagtail-localize-git plugin vars (see docs)
• merge wagtail-localize-2021 into master
• verify staging works as expected
  • use Wagtail Localize - testing result aggratation issue #7233 for issues found during testing.
• create sync locale "cron job" using heroku scheduler

Pre-deploy steps

• run through https://www.wagtail-localize.org/how-to/integrations/pontoon for prod:
  • Generate an SSH keypair for Wagtail Production (see vault)
  • Add the public key (wagtail-localize-key.pub) as a deploy key for the l10n repo
  • Add the SSH private key as BASE64-encoded heroku env var
  • Configure the wagtail-localize-git plugin vars
• send out notification to staff
• create an explicit database snapshot for emergency rollsbacks
• promote staging to production

Post deploy steps (#6713)

• Create new locales in the settings
• Run sync_locale_trees
• create sync locale "cron job" using heroku scheduler
• Start translating content (Theo)!
• finalize this epic by tearing down the foundation-localize heroku app

Things we'll need to secure before getting started:

• Time from Pomax for code review.
• Possibly Karl for Pontoon integration support
• Tom Usher for Devops setup
• Theo for translation support
• Kalob for doing the work

Helpful code snippets for future reference:

from wagtail_localize.fields import TranslatableField, SynchronizedField
class Model(Page):
    translatable_fields = [
        TranslatableField('title'),
        SynchronisedField('slug'),
        ...
    ]

[Pomax]

this epic was closed out long ago, any outstanding work should be new issues.