Steps required to add localisation to a Craft website

Step 1 — carefully select your languages

It is tempting to want to add multiple languages to your Craft installation, as this will allow you to target more territories, but it is worth considering the time it will take to create the content to replicate the existing content and then you will need to factor in the ongoing overhead of translating new content. It can become quite a burden — both in time and money.

Sometimes it is better to trial a single language so you can gauge the amount of work involved (in regard to content) even if you plan to roll out multiple languages over time. However, if you are certain there is a need to release the website in multiple languages, then it will save the developer time if they are made aware of this as they can configure Craft for these languages even if they are not released at the same time.

Step 2 — decide on your domains

Now you know the language variations you wish to publish on your website, you will need to decide on the domains these websites will use. Craft can handle:

• gTLD/ccTLD with a subdirectory — yourdomain.com/fr

• Subdomains — fr.yourdomain.com

• ccTLD domains — yourdomain.fr

Location is a big indicator of relevance and Google (and other search engines) will use the domain to identify a website’s locale — making the ccTLD option the best. Of course, the only drawback is you will need to register the domains for the different territories in which you wish to operate in.

Using a TLD with a subdirectory is the next best option. Subdomains are not favoured as it harms Domain Authority, so the SEO community tends to avoid this approach.

Step 3 — identify the content that will need translating

Managing and translating content is the trickiest part of the process.

Craft stores text in both a database (dynamic text) and in templates (static text).

Static text

For templates, the developer will need to have used the correct markup in order for the static text to be translated. For example, many developer may use the following markup to add a button:

<button type=“submit”>Submit</button>

However, this cannot be translated by Craft. Instead, the markup needs to be crated using a Craft variable with the translate filter:

<button type=“submit”>{{ ‘Submit’|t }}</button>

Adding static text as a Twig variable with the translate filter makes this text translatable.

If the template markup has not been added in this way, then every template will need to be reviewed and updated so static text can be converted.

Dynamic text

Most content should be stored in the database and editable within Craft. The most obvious candidate for translation are all the Entries, however, you will also need to consider other content types:

• Globals

• Categories

• Assets meta (i.e. an image’s ALT description and/or caption)

• SEO data (e.g title, description, keywords etc.)

• Plugins that render content to the front-end website (typically form labels, form error messages)

All this data will need translating.

Finally, you may also need to consider translating the URLs. There is little point having the content fully translated and the URL still written in the primary language. All entry slugs and section URIs will need to be translated.

Step 4 — setting up Craft

Read the Craft docs on setting up a localised site. They’ve outlined the basic steps already, but here’s a quick outline:

Define your sites and languages

In Settings > Sites adding a site for each required language. Craft will need to recreate content for each language you add, which can take some time depending on the size of the primary site.

• [tip] Ensure the Base URL is defined and added as an environment variable
• [tip 2] Craft provides a multitude of language options so it can be confusing to decide which version to select. Unless you have a specific reason to select a country localised language option (i,e, fr-BE for Belgium because the website’s audience in only from that region), then we would recommend selecting the generic language locale (i.e fr)

Update sections

At this point, the new site is not active and will need to be added to every section in Settings > Sections

This is where it is best to add the appropriate translation for the URI.

Update user permissions

It is easy to forget this step, but anything newly added to Craft (including sites) will not be automatically assigned to the user. Therefore, you will need to assign the new sites to the user group or individual user account.

Update field settings

The next step is to update the fields so they are configured to be translatable.

Most fields will need to be defined as translatable, with some exceptions. Asset fields tend to not be translatable as an image is typically the same across all websites.

Defining the Translation method for each field is an important step. There are multiple options, but you will most likely select the Translate for each language option

Matrix fields are a little tricky. Often you do not want to make the actual Matrix field translatable, only the fields within the blocks. How the blocks are saved across each website is controlled via the Propagation method.

Add templates

Every site will need its own directory defined within the template folder and its own index file.

In addition, the static translation files will need to be created. Essentially, each site has its own file containing JSON data with an original language and translated language pair.

This usually has to be manually curated and maintained but there are some new plugins that can help with this process.

Step 5 — extracting content for translation

This is perhaps the most difficult step as data is spread across a Craft website.

It is far easier to create a new User group/account for a translation company to access Craft directly (with limited permissions) and for them to edit content directly in Craft. This ensures all content is translated in a methodical manner.

Of course, clients can be reluctant to grant third-party access to their website, therefore, the only other option is to export the data and supply it to a translation agency.

The big issue is how to best export the data. Craft can natively export category and entry data from the control panel as CSV, JSON and XML.

Data in Global sets will need to be manually created in a CSV file. Often the data in Global sets is limited so this shouldn’t be too much of a problem.

Form fields and error messages will need to be audited and supplied in a manually curated JSON file.

Step 6 — importing translated content

Importing content can be managed using Craft’s native Feedme plugin, however, Feedme can only import data into specific fields types. If your website uses an unsupported field type (typically a third-party plugin) then this content may need to be manually added.

As of writing, Feedme can import data for the following element types:

• Asset

• Category

• Entry

• Tag

• User

• Global set

It also can support importing data for popular plugins including: SEOmatic and Navigation.

Step 7 — check everything

Obviously, this step is crucial. Although your data has been imported, it will still need human review and approval. Someone within your or your client’s business will need to check all content.

Step 8 — adding new functionality

Your web developer will need to modify the templates to include some or all of the following typical features:

• Site switcher

• Add lang attribute to identify language

• GEO detection to redirect users to the appropriate site

• HREF lang tags should be added to the templates

Adding a site switcher to a site retrospectively can be difficult if the website has not been designed to accommodate this in its design. This may require remodelling the site header, which may require additional work.

Step 9 — deploy the updates

With everything checked and approved all that is left to do is release the updates.

Step 10 — update Google Search Console

Finally, your SEO specialist may recommend adding your domains to Google Search Console and submitting a XML sitemap.

Helpful plugins

The Enupal Translate plugin will aid the initial development of your website and ongoing maintenance as It allows for the easy management of static text translations. It scans all templates and lists the translatable text which can be edited in the Craft’s control panel or exported as CSV file which can be imported.

If you want to automatically redirect users to a site that matches their locale then you could consider the Language Redirector plugin. It does not rely on any IP database, but uses logic grabbed from the user’s browser settings.

GeoMate provides similar functionality, but it uses GEO detection. It requires a lot more set-up and a MaxMind account. There is a free GeoLite2 database, which can be used but it is less accurate than the commercial version and is limited to 1000 IP requests per service per day. This should be enough capacity for most websites but you will only know through usage. The commercial GeoIP2 database is $288 per year.

The GeoMate plugin provides much more control and can be used to add a site switcher as well as display a prompt to allow a user to decide if they want to be redirected to a site in their language. Or, it can be configured to automatically predict them.

Final thoughts

There is a lot to think about whether you are building a new website or retrospectively adding multi-language versions our your website.

Most websites are fairly dynamic and have content added to it on a regular basis. Therefore, there needs to be some control/monitoring of new content added post sending the data to the translation agency. If multiple languages are being added then the translation agency will need to provide a timeframe for completion for each language. This scenario is where providing access to the CMS can be beneficial as there is less administration involved in managing content.

Budgeting

As you can see, there is so much to consider. Be careful when you are budgeting for this work as it typically takes longer than you imagine. For example, if the German language is to be added to your website, then word lengths can be around 35% longer than English. This can have big implications on the design of your website as the translated words may not fit in the allocated space — think button labels and navigation.