Setting the Background

Internationalizing or localizing a site is more than just adding content in a local language – we need not just support different languages but also regional variations in those languages. Our UI must also support other languages and display labels, dates, and more in the correct format for a chosen language. If truth be told, we could almost write a book in its own right on the subject!

With this in mind, and as there is so much we could cover, we’ll focus on the latter – providing international support.

Localizing and internationalizing are effectively two sides of the same coin, but as it is such a big topic, it’s essential to be clear which one we mean!

There is one crucial point to keep in mind: there is no single right or wrong answer when it comes to internationalization (or localization, for that matter). Sites frequently use a mixture of options – which we will touch on more later – the choice of which is dictated by the site owner’s requirements.

Okay – enough theory for the moment: let’s turn our attention to the various options available to help with adding internationalization support to our Eleventy site.

Some Housekeeping

Okay – now that we have laid down some assumptions, there are a couple of tasks to complete before localizing our site. Let’s take a look at what we need to do.

Great – we’ve done the boring part: now we can crack on with localizing the site! This may have been a mundane task, but an important one: localizing content can take time and require a lot of changes, so it’s best to have one we can work on while running our existing site in parallel.

I want to point out one thing, though – why did we remove the YouTube plugin? It’s a good question, and there is a good reason for doing so: npm looks for all published packages when installing and will complain if it can’t find any in its registry.

Strictly speaking, I could have included it as I have published my version; it would require changing the entry slightly to get it to work. However, excluding it for now is no bad thing – it’s one thing we would want to localize anyway, which we could do at a later date.

Okay – let’s move on: we have a site set up ready to use. Before we make any changes to our new site, we need to have a good strategy in place; let’s take a moment to explore how we will localize our content in more detail.

Creating a Strategy

We started this chapter by exploring some of the reasons why, and the benefits gained from, localizing is an essential part of any website. However, there is a crucial part we need to consider in all of this – it’s the strategy: How are we going to localize our content? Localizing our website will require quite a few changes, so it’s essential we get it right!

Each option has its own merits and constraints – for this project, we will use the middle one, which tends to be the most reliable in determining where customers are located (IP addresses don’t always match the physical location, for one!). We will revisit the reasons for taking this approach, but for now, let’s start with setting the locales for our project.

Setting the Locale

The first step in updating our site to support different languages is to add support for locales. There are three ways we might do this: recognizing the locale from an IP address, using the value set in the accept-language header in the browser, or using an identifier in the URL. Each option has its own merits, but (for reasons we will cover later) the defined value in the URL is usually the most reliable method.

This is the method we will use in our project – I’ve chosen to use English and French as my example languages, but feel free to adapt to other languages as the principles will be the same. Let’s dive in and look at the steps required to add locale support in more detail, beginning with the now-familiar step of stopping our Eleventy server.

The changes we make in this exercise will get the site ready to support both English and French localization. We will then add English translations in this chapter and finish with the French equivalents in Chapter 9.

Setting The Locale

To add support for locales, follow these steps:

1. 1.

   First, go ahead and make sure the Eleventy development server is stopped before continuing with the next step.

    
2. 2.

   Go ahead and create two folders at the root of our new project folder – one called en and the other fr.

    
3. 3.

   Next, create a new file at the root of the en folder, then add this code:

    

{

    "locale": "en"

}

1. 4.

   Save this file as en.json, and close it. Now move the posts folder from the root of our project folder into the en folder.

   Don’t be tempted to copy this folder: it will produce a duplicate permalink error.

    

1. 5.

   Go ahead and create a new pages folder inside the en folder, then move the about.njk, archive.njk, and contact.njk pages into this folder.

    
2. 6.

   Next, create a new file called books.njk, and add this code:

    

---

layout: layouts/page.njk

permalink: /books/

eleventyNavigation:

  key: Books

  order: 2

---

<h1>Books</h1>

<div class="booklist">

  {% for item in cms.allBooks %}

    <div class="book">

      <div><img src={{ item.image.url }} alt="{{ item.bookName }}"></div>

      <div>

        <span>{{ item.bookName }}</span>

        <span>Price: ${{ item.price }}</strong>

      </div>

    </div>

  {% endfor %}

</div>

You may remember back in Chapter 3, we used the code to source data from DatoCMS, but on the index.njk page; it’s better served from its own page.

1. 7.

   Save and close books.njk. Next, move the index.njk from the root of our project folder into the root of the en folder.

    
2. 8.

   We need to amend the permalink in post2.md, as this has a different structure. Go ahead and open this file in your editor, then change the permalink value as shown:

    

permalink: /{{ locale }}/posts/my-second-post/index.html

1. 9.

   We also need to update the permalink values in the front matter for the Archives pages – go ahead and open archive.njk in the en folder, then make sure the permalink value shows this:

    

permalink: /{{ locale }}/posts/

1. 10.

   We should also do this for the French version too - copy the archive.njk file into the fr folder, then make sure it shows the same permalink value as in step 9.

    
2. 11.

   Save and close any file open. Switch to a Node.js command prompt, then set the working folder to our project folder.

    
3. 12.

   At the prompt, enter npm run watch:eleventy and press Enter.

    
4. 13.

   Once the server is running, browse to http://localhost:8080/en and then try clicking on any link from the site’s homepage. You will notice that the page URL now shows /en in the link, which means our content is now localized.

   Note The header and footer are not displayed: don’t worry! We will fix this later in this chapter.

    

1. 14.

   If all is well, we should see our site content displayed similar to Figure 8-1.

    

Yikes – our site has lost its styling, so it looks a little raw! Don’t worry, though: as I alluded to earlier, internationalization will require making quite a few changes, and things will get worse before they get better. This last exercise is probably the most critical change we need to make in terms of structure, so let’s take a moment to review what we achieved in changing code.

Localizing Dates

With our basic site structure now in place, we can update the format of dates shown on our site. Not every site will use dates in the same way – we might use them to indicate when a post was added or the availability of new stock for an e-commerce outlet.

It doesn’t matter what we use the data for; the principles for adding dates for a localized site remain the same, so let’s dive in and take a look.

For this exercise, I will focus on the mechanics of adding a formatted date; we will come back later and tweak the format to suit our locales better.

Setting Up The Date Format

To set up a localized date, follow these steps:

1. 1.

   The first task is to stop the Eleventy server – this will make sure any changes we make are applied correctly when we restart the server.

    
2. 2.

   Next, crack open a Node.js command prompt and change the working folder to our new project area.

    
3. 3.

   At the prompt, enter npm install moment --save and press Enter – this will install the moment date library.

    
4. 4.

   Once installed, open .eleventy.js, then add this line below the last of statement at the top of the file:

    

const moment = require('moment');

1. 5.

   Next, scroll down to the date addFilters, then leave a line blank after the htmlDateString filter, and add this:

    

// date filter (localized)

eleventyConfig.addFilter("date", function (date, format, locale) {

  locale = locale ? locale : "en";

  moment.locale(locale);

  return moment(date).format(format);

});

1. 6.

   Save and close the file. Go ahead and open _includes/posts/post.njk, then comment out this line, as shown:

    

{# <time datetime="Posted {{ page.date | htmlDateString }}">{{ page.date | readableDate }} by {{ sitedata.author.name }} | A {{ 'text' | timeToRead }} read</time> #}

1. 7.

   Immediately below that line, add this replacement:

    

<p><time datetime="{{ post.date | date('YYYY-MM-DD') }}">{{ post.item|date("DD MMMM YYYY", locale) }} {{ site[locale].by }} {{ sitedata.author.name }} | {{ 'text' | timeToRead }}</time></p>

1. 8.

   Save and close the file. Before we can compile our code, we need to remove one YouTube plugin entry in our pages – go to page2.md, then remove the line starting {%youtube…%}. This is to prevent our build from breaking when we recompile the code.

    
2. 9.

   With that out of the way, we can now compile – switch to a Node.js command prompt, then make sure the working folder is our new project area.

    
3. 10.

   At the prompt, enter this command:

    

npm run watch:eleventy

and press Enter – if all is well, we should see something akin to Figure 8-2 when the site starts, and we click through to the second post.

Excellent – we’re a step closer to localizing our site! Okay, I know it’s not a significant visual change, but it’s essential to get the correct format of date for our chosen locales, as this will prevent confusion for those readers or customers who are used to dates being in a different form. This change highlights some key points, particularly around internationalization, so let’s take a moment to review the code changes in detail before moving on to the next task in this chapter.

Localizing Layouts

At first glance, it might seem a complex task to fix some of the issues created by relocating the content – indeed, I wouldn’t be surprised if you were thinking, “yikes… where do I start?”

That’s more than enough for us to get going on! To give you a flavor of how it will look, Figure 8-3 will show you what the result will look like on the index page.

Let’s make a start – we’ll begin with reinstating the style sheet and image links, so our site starts to look whole again.

Wow – that was certainly a lengthy exercise! It couldn’t be helped, though – there are points where we just have to make those changes. Completing this exercise means we have made significant progress: we still have a few areas to cover, which we will attend to shortly. For now, though, let’s pause for a moment to explore the changes we made in the last demo, so we can see how they all hang together.

Localizing the Header

At face value, the header for our site looks very simple – we have the logo, name of the site, and three menu options: indeed, is it a case of adding in more labels, such as site[locale].about? Unfortunately, it’s not as straightforward as one might think: we already have the titles from within the front matter sections on each page.

The difficulty here is that we need to create collections for each locale (EN and FR) to keep the content separate throughout the site. The nature of our site means that we can’t use a single “wildcard” style component (more on this later), so we have to use a little trickery – let’s dive in and take a look at what is involved in more detail.

Localizing The Header

To localize the header, follow these steps:

1. 1.

   First, stop the Eleventy server, as we have done in previous exercises. This will ensure we apply the latest changes when restarting the server at the end of the exercise.

    
2. 2.

   Next, go ahead and create two folders within the _includescomponents folder – one called en and the other called fr.

    
3. 3.

   Go ahead and open header.njk from the en folder, then amend the for... line as shown:

    

{%- for entry in collections.pages_en | eleventyNavigation %}

1. 4.

   Repeat the same exercise for the header.njk file in components/fr, as shown:

    

{%- for entry in collections.pages_fr | eleventyNavigation %}

1. 5.

   The header is called in from the base.njk layout, so open this file and replace the existing {% include…%} line after the opening <body> tag with these two lines, like this:

    

  <body>

    {% set localeHeader = site[locale].header %}

    {% include localeHeader %}

1. 6.

   We need to add in two more files to tie the localized headers into the site – go ahead and open a new file, then add this code:

    

module.exports = {

  locale: "en",

  layout: "layouts/base.njk",

};

1. 7.

   Save this file as en.11tydata.js within the root of the en folder.

    
2. 8.

   Save a copy of the file into the root of the fr folder and change the locale value within it to "fr".

    
3. 9.

   Save and close all files – once done, switch to a Node.js command prompt, then change the working folder to our new project area.

    
4. 10.

   At the prompt, enter this command, press Enter, and wait for Eleventy to compile our code and fire up the site.

    

npm run watch:eleventy

1. 11.

   If all is well, we should see something akin to the screenshot shown in Figure 8-4, when browsing to the English site at http://localhost:8080/en.

    

1. 12.

   To give you a flavor of what our site will look like, once we add the French localizations (which we will do in the next chapter), I’ve gone on ahead and converted the site to show the French equivalents. You can see what it will look like in Figure 8-5.

    

Excellent – we now have a localized header for each site, so things are shaping up nicely! Although the code changes required to get us to this point were relatively straightforward, the demo does bring up an interesting point about the site structure – let’s take a closer look at the code in more detail.

Summary

Localizing a site isn’t a five-minute job – there is more to just providing localized copy text; we have to consider labels, date formats, displaying the right language content for the site, and more. We’ve made good progress, though, on updating the website in this respect: let’s take a moment to review what we have learned in this chapter.

We kicked off by setting the background to this part of the project – this explored some of the points we have to think about, defining the difference between internationalization and localization and creating a strategy for adding different languages. At the same time, we took a look at some of the plugin options to help with adding international support – we will focus on setting this up manually for this project but can explore using these plugins once the basics are in place.

Next up, we set up locale support so that our site is configured to display content from different languages. I’ve chosen French and English for now, but the actual language choices aren’t crucial here: it’s more about the changes we have to make to support different languages, not the language itself.

We then moved on to localizing dates – we added support using the Moment library, but note that while it illustrates how we can format dates, we should equally consider using a different library as Moment has been deprecated.

We then worked on updating the layout; we started with fixing the styling and missing images before setting up and adding placeholder labels to our site. This we complimented with a new data dictionary to act as the source for our labels. At the same time, we also worked on localizing the header – the header configuration is different from the rest of the site, so we had to use another method to display headers in the correct language.

Localizing a site requires making substantial changes. We’re only halfway through this part of the project – we still need to work on updating tags, making sure content is filtered for the correct locale (so we don’t display both languages simultaneously), and more! There’s plenty to keep us busy, so let’s crack on with the next chapter, where we will add the second batch of changes to our internationalized site.