Website Localization with Sulu

Many businesses need to communicate with customers and other stakeholders in more than one language. We can deivid them into the following broad categories:

• Internationally active SMEs: Small and medium-sized enterprises that serve multiple countries with a different language for each market.
• Businesses serving multilingual countries: Serve a single country in several languages, e.g. in Belgium people speak French, Dutch, and Flemish.
• Multilingual corporations: Serve many different markets, some of which have multiple languages in the same country and some with different variants of the same language. For example, in the DACH region some companies need content in different variants of German for Germany, Switzerland and Austria.
• Multi-brand, international corporations: Serve different regions, languages, and markets, with a high level of autonomy on a local level. Sometimes they operate different brands in one or more countries.

All these businesses need uniform branding and localized content, with minimal additional effort. Multi-brand, international corporations need to strike the balance between reusing content to avoid duplication, and adapting content to suit their local markets.

The list illustrates the complexity and diversity of requirements that Sulu’s multilingual features have to cater for. For multi-brand, international corporations, it might be adivsable to set up a separate webspace — but that is beyond the scope of this guide.

To help you start planning, use the above categories as a guide. Start by listing the markets you serve, and for each one decide whether it needs highly customized content — even completely different branding — or content that is translated or lightly adapted from a central resource.

There are a few aspects of multilingual websites you’ll need to consider, whichever CMS you use.

Non-Latin character sets

Sulu can handle all character sets and special characters. In URLs, these are converted into ASCII characters automatically. On a related note, if you’re serving a language that flows from left to right, make sure your frontend can handle it.

URL strategy

Sulu can use whatever URL pattern you choose, including differentiating by subdomain (en.example.com), top-level domain (example-english.com), or folder structure (example.com/en). Although with Sulu you can easily change your strategy as often as you like, it’s bad for SEO and user experience if you change your approach once you’ve gone online, so make a plan before you launch. 

Required locales

In Sulu, a locale consists of a language and, optionally, a country code. Examples include Swiss German (de-ch), German German (de-de), US English (en-us), and British English (en-gb). Sulu places no limits on these so you can define your own if you need to. You can find a list of official locales on Wikipedia.

Search engine optimization

Seek advice on SEO from trusted experts. Apart from your URL strategy, Sulu supports tools you’ll need for optimizing your site. These include:

• Separate metadata per language (title, meta description, etc.)
• Speaking URLs (example.com/the-name-of-your-article)
• Automatic canonical links for avoiding duplicate content
• Automatically generated sitemap with links to all language variants

Permissions

You can grant permissions to editors by locale, as well as for a specific page. So an editor could have editing rights on every piece of content in every language; or they could be allowed to edit content just in Swiss German on a specific page.

Every Sulu website has at least one webspace. Each webspace has its own language settings as well as content tree, navigation structure, URL format, and so on. (See the docs on Webspaces for more information.)

Sulu uses the same tree for all content in a webspace, regardless of language. This ensures translations are always correctly associated with one another once they’ve been created.

Here’s a summary of what an editor can do with Sulu’s multilingual features:

• Add a translation for any piece of content such as a page, article, or media metadata.
• Designate shadow pages. If a page doesn’t exist in a website visitor’s language, you can set a fallback page to be shown for this content. The marketer responsible for Germany likes their Swiss colleague’s content, they can designate the Swiss-German version as the German-German version.
• Keep content structure and navigation in sync because they are the same for all languages. (The editor can specify per language whether a page is visible in the website navigation or not, but cannot change its position.)
• Set content and media (such as images and videos) as non-translatable so they can be reused across locales without any translation; alternatively these can be duplicated and adapted for each locale — if, say, the alt text is different.
• Optimize for search engines with comprehensive SEO-friendly features specific to multilingual needs.

XLIFF is an XML format that many translation agencies work with. Developers can export the entire content from your website for easy exchange with translation agencies, who can translate your content then send it back to you. With a simple command, a developer can re-import it into your website.

To export your content to XLIFF, execute this command:

To import an XLIFF file, execute this command:

In both cases, the order of parameters is [filename] [webspace] [localization].

You begin building a multilingual website the same way you’d build a single-language website. Adhere to the usual best practices surrounding Blocks and Templates, as outlined in the relevant guides. We recommend testing multilingual content on your website as you begin to build it out. At an early stage, make sure your country representatives are happy with the direction your project is taking. We highly recommend planning for internationalization from the beginning by including an indicator in your URL. If you start with one language and no indicator but add languages later, you’ll need a lot of redirects.

Sulu does all the heavy lifting

From a technical point of view, adding multilingual functionality to an existing website is a matter of changing a few lines of code in the XML definition. Themers don’t need to make any changes either: Sulu automatically supplies Twig with the appropriate content depending on what language is currently being served.

Configure your languages

The following code example gives an impression of how little configuration is required to add languages and determine which format the URLs should take:

Interface texts—such as “Read more” links or “Next”—are straightforward too. These can be handled using Symfony custom translator, which editors cannot change.

Create a language switcher

In many cases, Sulu will automatically detect the visitor’s language, but you should still add a language selector. Here’s an example of Twig code you can use to create a language switcher:

The content in some fields — in particular some media assets — doesn’t need translating and can be used in all languages. Developers can designate these as non-translatable to save editors the effort of adding them in every variant.

Now you’re ready to set up permissions, and add content, as usual.

The Allianz Cinema website is a great example of a Sulu multilingual project. It’s predestined for Sulu’s multilingual functionality all within one webspace because it serves customers in several languages but — crucially — all under the same brand and largely the same content.

Switzerland is a country with three official languages — French, German, and Italian — so this example fits into the category “business serving a multilingual home country” in the table above. Editors can adapt content in three ways:

• Copy content from another locale and translate or adapt it.
• Use a shadow page to designate a fallback if the content already exists in their language, so they don’t have to rewrite it.
• Use a shadow page to designate a fallback in a different language if they don’t have a translation for a specific language.

Developers can designate media assets, such as stills from a film, non-translatable. This can save editors having to upload the same media for each language.

Finally, because multilingual features are built into Sulu’s core, they are available nearly everywhere within Sulu. This is a powerful combination for Allianz Cinema, which relies on Sulu’s support for custom data objects and business logic to model their complex processes.

We’ve given you an overview of how multilinguality works in Sulu and how to start your project. If anything is missing from this guide or you have questions, don’t hesitate to get in touch with us on Slack. Alternatively, you can find practical examples in the Sulu demo project (the source code behind sulu.rocks), or browse the documentation.