How to add localization to your Wagtail CMS website

Hello and welcome to another lesson on Learn Wagtail. In this video, we are going to set up localization using a newish package called Wagtail Localize. So first before we get started, really all I'm going to do in this video is I'm going to go through the tutorial that is available on Wagtaillocalize. org. Now one thing to note before we get started is Wagtail Localize is still in its early days and it is likely to change a little bit. So what you see in Wagtail once we get up and running might change a little bit between the time of this recording and the time that you are watching. It really, really depends on the development. cycle of this particular package and where it's at

and how it may eventually end up in Wagtail Core. So first things first we're going to need to set up a new project. We can see here we have different installation instructions here. I'm on a Mac. You can simply go to Windows, just click this little Windows tab, and it'll tell you exactly what to do. I'm going to be using the Mac. or the Linux instructions to get up and running. So first things first what I need to do is I need to open up Visual Studio Code. Now at no point in time do you need to be using VS Code. You can use any text editor you like. This is just the one that I prefer. And what I'm going to do is I'm just going to open up a new folder here called Learn Wagtail Tutorials. So I open that up, and it gives me a little sidebar on the left there, and I'm going to open up my terminal here. If I go to view, where is my terminal?

Here we go. And I'm going to create a new virtual environment. So I'm going to be using pipenv. You can use irregular Python environment, you can use Docker, you can use Vagrant, you can use anything you like. Just make sure you use that one layer of abstraction. So I'm going to do pip env shell. And this is just going to go ahead and create a brand new pipenv for me. And when I type python-v, you can see that I'm using Python 3. 9. So let's go ahead and install. Wagtail in here. So let's do pip installwagtail. And this is just gonna go off and install the latest version of Wagtail. We can check the version of it in just a second as well. So that's installed. Let's go ahead and type Pip show Wagtail and I'll show you which version I'm using right now. 2. 12.

2. And you can see that right in there. So let's go ahead and start a new site, Wagtail. Start. I'm gonna call it my site and I'm gonna put a dot in there and that dot at the very end just means put it put all the files it's going to create in this particular folder. So Let's go ahead and run that and you'll see all these files show up on the left hand side. Let's just make that a touch bigger here. And now what we can do is we can run python manage. py runserver on localhost port 8000. And if that works for you, you're going to see that there's 119 unapplied migrations. Again, that number might change. Might be 120, might be 130. It might be a little bit less depending on your version of Wagtail, but let's go ahead and uh run these migrations. So I'm just gonna type python manage.

py migrate. And that's going to go ahead and provision my database. And then we're going to create a super user. I'm going to show you that this just creates a generic Wagtail website So if I do, and this is just a shortcut that I like to run, these comma, comma, and then like a couple of letters that just it's because I write python manage. py so many times in a day. So you want to type python manage. py create superuser. And I'm going to call myself admin, admin at admin. io, password is just a password. And let's go ahead and run that server once more. Now it doesn't complain about migrations. So what we can do is in your favorite browser, and I'm just using Chrome here, you can go to localhost port 8000

and it's gonna see it's gonna show you a regular admin uh not an admin I was reading the word admin interface it's gonna show you the regular WedKill setup so if you click admin interface and log in with those credentials that you just created you're going to see a regular page here and Uh in here we have our homepage. And that's it. We only have one page, just one homepage. There's no localization, there's no internationalization. So what we're going to do is we're going to follow the internationalization steps or the localization steps found on Wagtellocalize. org. So we have our website up and running. Let's head on over to step two where we configure Wagtail Localize. And if we just follow these steps, these steps are well documented. So if we just follow these steps, it's going to tell us exactly what we need to do.

So first things first, we need to add Wagtel localize and WagtelLocalize. locales into our installed apps. So let's head on over to our editor here. Let's just fix this up so it's not taking up as much real estate. And let's go ahead and open up base. py. And in here, these are just our base settings, but we can we can see that there's installed apps in here. And we just want to add Wag to localize and Weg to localize. locales. Now there's a caveat here. And it tells us right in the documentation. And it says, uh note that Wagtail Localize. locales module is a temporary replacement for Wagtail's built-in Wagtail. locales module. So if you have Wagtail. dot locales installed in here somewhere go ahead and remove that in favor of Wagto

localize dot locales. Now this is one of those things that might change in the future. So just You know, while you're watching this video, head on over to wagtellocalize. org and make sure you follow along with the written instructions because those are going to be more up to date than this video. Next, we need to add Wagtail's internationalization. So this is the only line we really need to add here. We have internationalization, localization, and time zones all set to true. Let's go ahead and find that in our base. py settings Do do do do do. It's usually near the bottom somewhere. There it is. Use internationalization, use localization, use time zones. Let's go ahead and paste Wagtail internationalization enabled is equal to true. I'm just gonna paste that in there. Now, at this point in time, I just saved my file

and it's gonna give me this complaint. No module named Wagtail Localize. So let's let's cancel our server and let's do pip install and what I'm gonna do is actually clear this so I can write it near The center up here. Uh pip install wagtail dash localize And that's just going to go and install Wagtail Localize. And you can see that it's actually uninstalling Wagtail212. 2. Uh let's see what it installed here. Pip show Wagtail. And this installed the uh the latest version before 2. 12. So that's likely to change as well down the road as 2. 12, 2. 13, 2. 14 support comes out, that's going to change for you. So let's clear that and let's run our server one more time and we're gonna see that there's some migrations we need to apply.

There's 12 migrations. Migrations might change down the road. They might Say 12, they might say 15. It really depends on the development of this particular package. So let's go ahead and run those migrations with python manage. py migrate And it's just gonna go off and provision my uh Wagtail localize table for me in my database. And if I run this one more time, we're gonna see that everything works perfectly. Now there's a couple more things we need to do in here. We need to configure our content languages. So let's just go ahead and copy this. We can copy that as well by clicking that link and In my settings, and it doesn't really matter where you put these things in your settings. Uh so what I'm gonna do is I'm just gonna paste that in there. And what this is going to do is say, hey, there's an English version of your site.

And so when you go to your website. com slash en it's going to show the English version. Or your website. com slash fr, it's going to show the French version. And what I'm going to do is just because the docs show two uh different languages in here, they show English and French. I'm going to add Spanish. Just to demonstrate that we can add that in there. And all this is is a uh a two-pair tuple. And so it just has your prefix in there, so English for English or EN for English, E S for Spanish, F R for French, etc. etc. Then we need to go into our middleware and we need to add one line in here, just this one here. We need to add our Django Middleware Locale Locale Middleware. Now you might already have this on an existing project, you might not.

But if you don't, let's go ahead and make sure we have that in there. So where are we? We're looking for middleware. Here it is. And let's just go ahead and throw that in there, just before our Wagtail stuff. We want to make sure that it's a Django it's a Django middleware, so we want to make sure that the Django middleware is loaded before Wagtail. Let's go ahead and save that. We're gonna see no complaints in our terminal in here. And then we need to move into our URLs. And so there's a good explanation about what to do in here. So let's first of all let's open up our URLs. py And I'm just gonna make this a touch smaller so we can see a little bit more in the viewport here. And what this is going to reference is there are two URL patterns when you create a new Wagtail site. So you have URL patterns here, and you also have URL patterns down here. And the idea is that your base website comes with URL patterns up here

and then you can have Some extra Wagtail URL patterns down here. And so this really just says, hey, when you go to your website. com slash blog It's going to look for everything. If it doesn't match Django Admin, Admin, Documents, or Search, it's going to look for everything else in your page structure, in your Wagtail site. So it's going to look for, for example. slash blog page and that's just a catch-all URL. So what we want to do here is we want to grab this search And we want to just paste that right in there, just like that Then it's going to tell us that we need to add I18N patterns. So let's go ahead and copy this one line here

and throw that into R Django imports near the top there. I just put that in alphabetical order. Uh I18N patterns and if we scroll down down here, what we're gonna do is we're gonna replace this list with a function and we're gonna put I18N patterns as a function in here. So I'm removing that list. And I'm saying, hey, everything, every parameter in this particular function is going to be internationalization. So we're using I18N patterns, internationalization patterns. Let's go ahead and save that, see if there's any complaints. There shouldn't be. Everything looks good there. And we already migrated our database and we are basically good to go at this point.

So what we can do is if we just open up another tab and go to localhost port 8000 or 127. 0. 0. 1 port 8000. You're gonna see that it automatically goes to slash EN. That is exactly what you want. This is the English version of the page So now we have localization actually up and running at this point in time, but we don't have any content. So if I went to slash ES because I added Spanish, we're gonna see that it just shows basically the homepage. There 's nothing unique about this whatsoever. So let's go back into our admin and in our settings what we want to do is uh I need to refresh this because we added localization. In our settings we'll see locales in here, and we can add a locale at the top right.

And which locale do we want to add? We're going to add Spanish and we're going to sync from English. Let's go ahead and save that And it created one page for me. Now if I open up this Explorer, we're going to see that we have two home pages now. And again, this is something that's likely to change in the future. There's probably going to be some sort of drop-down that says. Select your language so it doesn't say home English and Home Spanish, but for the time being this is what we have to work with. So this home Spanish is what's called an alias page And if we try to edit this, we actually can't edit it. Whereas if we edit the homepage, we can edit this homepage. Now my homepage is pretty bare bones. It only has a title and the default promote and settings and all that stuff in there. But it doesn't have any extra content in there.

So what I want to do is uh just as an example, I'm gonna keep this nice and simple. So I'm not gonna add any extra fields to this. But what I want to do is I want to click this English and go to Spanish. This is gonna show me the Spanish page, which is the equivalent of clicking the home Spanish. Edit link here and I'm gonna translate this page and it's gonna say what do you want to translate this page into? I'm gonna translate this page into Spanish And it's gonna bring me to this nice little page here where it's going to break down everything on your page, not just your title. But it's going to break down your stream fields, it's going to break down other char fields or text fields, uh links, images, things like that. So again, this is just a very basic example. But what we want to do here is click this translate button at the bottom right there

And instead of home, I want this to be in Spanish. So I'm going to call this Mikasa. And then I'm going to click Save. And it says it was translated manually on February 27th, 2021. Let's go ahead and publish this in Spanish. And you're gonna see that it says publish mi casa in Spanish with missing translations. See below. We actually don't really see anything at this point in time. But we do have content tabs in here. So we've got a content tab and we have a promote tab. In this promote tab, it's saying that the slug wasn't translated. Now this is the homepage. It doesn't really matter if what the slug is, but let's go ahead and change this to CASA. And publish in Spanish. And actually what I did there was I typed it, but I didn't save it. So let's go ahead and save that.

You can see it turns from uh orangey red to a green on that left side there. Publish that in Spanish. There we go. The page is published in Spanish. Now, because Wagtail comes with this default page here, we're not actually going to see anything. It just looks the exact same no matter what locale we use. We're using the Spanish locale, it doesn't look any different. So what we're going to do is we're going to open up. our home page template and I'm just gonna go ahead and delete a bunch of stuff in here and this is going to be a really ugly example but it's going to be a functional example So let's get rid of the extra CSS, let's get rid of the homepage, and in here, let's say there's going to be an H1 And it's going to be the page title. Because that's all we changed. That's all we translated was that page title. So in English, this is going to say home.

In Spanish, this is going to say casa So let's save that and refresh our page. And we're on the Spanish version. So we're on localhost port 8000 slash ES. It says Mikasa. If I go to the English version, it says home. So now we have localization actually up and running, working perfectly with Wagtail. Now what's really really nice about this is it's going to automatically detect your locale. So for me, on Chrome, that's in English. But if I open up Firefox, and what I'm going to do here is I'm going to go into my preferences and I'm going to change my language. Languages set alternatives and I'm gonna change this to Spanish. Okay , I'm gonna apply and restart

And now you can see everything is in Spanish for me. So if I go over to localhost port 8000, originally it sent me to the English page because it detected that my browser was in English. I changed my settings to be in Spanish, so when I click enter here or hit enter, it's going to go to slash ES automatically and show mi casa instead of home. Just like that. So now we have localization, internationalization up and running with a fresh install of Wagtail. And If you ever wanted to, uh just for search engine optimization, uh, you know, maybe you write most of your articles in English, but sometimes they have a Spanish translation. Sometimes they're not going to. You can always go to the English version as well just by changing it in your URL.

So I just changed that from ES, which is what it defaulted to because my browser was set in Spanish. So ES. And if I wanted to, I could go to the English version of any page. Now let's go ahead and create one more example in here. Let's go ahead and create a new page. So let's go into home. I'm going to add a child page. It's going to be a home page just because I'm using the default Wagtail setup. I didn't go ahead and create a new page. You can always add new page types. It doesn't have to be the same thing as your homepage. It could be any page type So let's just call this blog. Just for funsies, let's put parentheses English. So let's go ahead, publish this page. And when I view this, and again I'm on Chrome right now, it's in English, so we see En. Now if I go to ES, what are we gonna see?

We're gonna see the exact same thing. It's looking for blog in English, just in Spanish, but it doesn't exist yet. So what we need to do is we need to go to our blog page and we need to translate this page. We're gonna say, yep, translate it to Spanish, because that's the locale that we created in our settings And it says blog English was successfully submitted for translation into Spanish. Now in our Explorer, we're gonna see this. Homepage, blog English, and then we've got the homepage in Spanish called Mikasa. blog in English. And if we click edit, this actually changes a little bit. So it's going to mimic your English page, but it allows you to translate it into Spanish or any other language that you want. So let's go ahead and call this blog and in parentheses

Spanish. Promote. Let's change that to blog Spanish. And let's publish this in Spanish. And I didn't hit save again, uh, because that's just where my brain is at today. So hit save Caleb. There we go. Publish in Spanish. There we go. Okay, okay, okay. Now we're making some progress here. So, one thing you're going to notice here is that I changed that slug. And if I go back here, we're gonna see that that slug in English is blog-English, in Spanish it's blog-spanish. So if I go to ES slash ES slash blog dash Spanish this shows up in Spanish. Now if I want those to be in sync

Uh there is a way to completely sync those, that's totally fine. We can do that in our settings. That's that might be something that we tackle in another video, but let's go ahead and set this back to English. And let's go ahead and actually save this. Let's go ahead and publish this. There we go. English and English. We're gonna see that this page doesn't exist anymore because we changed that slug of that alias page. And if we go to blog English, we're gonna see that this is now in Spanish Now this gets a little bit confusing, but you always have to look at your URL up here. So if we go into slash en it's in English. It just happens to be that this blog slug is called blog English. We could have just as easily said slash blog, which is likely what you would have done anyways. I just made this a little more complicated than it needed to be.

So if we go over to ES We're gonna see that it's in Spanish, blog Spanish, and E N blog English. And so that's how we translate our pages. Now you can download your PO file, you can upload a PO file if you already have a PO file, but if you're just getting up and running with Wagtail and you want to add internationalization to your pages, chances are you don't have PO files. And so you don't have to worry about inputting a PO file or uploading a PO file. You can just do it one field at a time just by translating the page. Now one last thing is if we go into our Explorer here, we have home, Mikasa. And the page has now been converted to say blog Spanish. If at any point in time we wanted to change this to uh instead of be just in Spanish, because we're just looking at Spanish pages at this point, we can always just go.

Click this little fella up here, this little feature that says Spanish, and go to English. And it's going to change those those pages for me. So it just swaps them out for me. Which is really nice feature when you have a lot of content to deal with. Now, again, please note that things are likely to change. We are at some point likely to see that This little feature up here, this little drop-down, is likely to be up here at some point, I'm assuming. And so that you're not going to see home in English, home in Spanish, home in French, home in German. etc etc etc you're eventually just going to see your homepage and then a little drop down picker where you can select the language and it just swaps your pages out for you. But all in all, that is how we add internationalization and translations to our Wagtail site.

Now if any of this was ever confusing to you at any point in time, please, please, please Head on over to Wagtaillocalize. org and click on tutorial. There's two other steps that we didn't get into, such as translating content. Actually, we did kind of get into translating content. Uh but there is a better, more uh full demonstration in here. And so I didn't cover a lot of this. We did cover translating some content, but this is a much better example And then there's translating your templates, which gets into a whole nother thing, but you can come back to that a little bit later. I just wanted to show you how you can get Wagtail localized up and running on a fresh install of Wagtail. right away in just a few minutes and it instantly adds internationalization and localization to your Wagtail website

and magically just works So remember if you get stuck, head on over to Wagtil Localize. Thanks for tuning in to this video where we installed Wagtil Localize in a fresh Wagtail installation. My name is Caleb Tallinn. I have been your host today. Thank you so much for tuning in, and I hope to see you in another one of these videos