Sulu CMS Internationalization: Quick Guide to Page Translations

What you need to know right away

In Sulu, every page can have multiple language versions. The system stores each locale in the sulu_content table and links them to the sulu_page entity via a translations association. URLs are built with a locale prefix (e.g. /en/about) and fall back to the default locale if a translation is missing.

How Sulu stores translations

When you create a page and add a translation, Sulu writes a row to sulu_content:

id | page_id | locale | title | content | …

The page_id references sulu_page.id. Doctrine loads the translations lazily, so a page entity only pulls its translations when you access the translations collection.

Configuring locale prefixes

By default Sulu prefixes every URL with the locale. The setting lives in config/packages/sulu.yaml:

# config/packages/sulu.yaml
sulu:
    routing:
        locale_prefix: true
        default_locale: en

Changing default_locale after content exists can hide pages that lack a translation for the new default.

Adding a translation in the Admin UI

1. Open the page you want to translate.
2. Click Add language in the top‑right corner.
3. Choose the target locale (e.g. fr) and fill in the translated fields.
4. Save. Sulu creates a new row in sulu_content with locale = 'fr'.

After saving, the page appears under /fr/about (if the page slug is about) and the language selector shows English and French.

Practical example: Adding a French translation for page ID 1

Assume a page with ID 1 exists in English. You can verify the new translation via SQL and via the browser.

# Run as a database user with SELECT rights
SELECT * FROM sulu_content WHERE page_id = 1 AND locale = 'fr';

In the browser, request https://your-site.com/fr/about. The page title should be the French translation you entered.

Common pitfalls and limits

• Missing translation tables: A fresh install does not create sulu_content automatically. Run bin/console sulu:install or bin/console sulu:database:update to create them.
• Locale prefix override: Custom routing rules that remove the prefix will break language detection. Keep locale_prefix enabled unless you handle detection manually.
• Lazy loading surprises: Accessing $page->getTranslations() triggers a database hit. In performance‑critical code, consider eager loading via JOIN FETCH if you need many pages.
• Default locale change: If you switch the default locale after content creation, pages without a translation in the new default become inaccessible until you add one.

How to verify the setup works

1. Check the sulu_content table for rows with the expected locale values.
2. Open a page in the admin UI and confirm the language selector lists all added locales.
3. Browse /en/about and /fr/about and verify that the page title and body match the translations.

When all three checks succeed, your internationalization configuration is correct.