Skip to content

Introduction

Kirby comes with built-in support for multi-language sites. Languages can be defined, added and switched right in the Panel.

Features

  • Define any number of languages for your site.
  • Add new languages from the Panel.
  • Set a different default language from the Panel.
  • Use custom language variables to define string translations, for example for buttons, forms, options.
  • Define custom language URLs.
  • RTL languages are supported too.

Enabling the multi-lang feature in the Panel

To allow your users to define and switch languages from the Panel, you first have to enable it in /site/config/config.php:

/site/config/config.php
<?php

return [
    'languages' => true,
];

Adding languages

Manually

New language definitions are created in the /site/languages folder. To add a new language, create a new PHP file with a filename consisting of the language code of the new language and the extension .php.

For example, to add English as a new language:

/site/languages/en.php
<?php

return [
  'code' => 'en',
  'default' => true,
  'direction' => 'ltr',
  'locale' => 'en_US',
  'name' => 'English',
];

Repeat for every new language you want to use.

Via the Panel

After enabling languages in your config as described above, you can find the language setup on the Panel in the "Settings" page.

To add the first/a new language, click on "Add a new language" and add the language name, code, direction and PHP locale string.

Once the default language is defined, you can add more languages as secondary languages. The Panel automatically renames all existing content and file meta data files and includes the language extension.

By default, the URL of your site changes and the language code is added to the URL. If you want to keep the root URL for the default language, you can set the URL manually.

Manage languages

The Panel offers options to delete and edit a language, or to make it the default language. You can access them by clicking on the menu icon (three dots):

Edit: Change the name, locale or reading direction of the language.
Make default: Make the language the new default language.
Delete: Delete the language.

Using different domains for each language

Kirby supports cross-domain multi-language sites. You can define the domain for each language like this:

/site/languages/en.php
<?php

return [
  'code' => 'en',
  'default' => true,
  'direction' => 'ltr',
  'locale' => 'en_US',
  'name' => 'English',
  'url' => 'https://example.com'
];
/site/languages/de.php
<?php

return [
  'code' => 'de',
  'default' => false,
  'direction' => 'ltr',
  'locale' => 'de_DE',
  'name' => 'Deutsch',
  'url' => 'https://example.de'
];

Make sure that both domains point to your Kirby site.

Detailed locale settings

If you need more control over your locale settings for each language, you can pass an array of locales:

/site/languages/en.php
<?php

return [
  'code' => 'en',
  'default' => true,
  'direction' => 'ltr',
  'name' => 'English',
  'url' => '/',
  'locale'  => [
    LC_COLLATE  => 'en_US.utf8',
    LC_MONETARY => 'en_US.utf8',
    LC_NUMERIC  => 'en_US.utf8',
    LC_TIME     => 'en_US.utf8',
    LC_MESSAGES => 'en_US.utf8',
    LC_CTYPE    => 'en_US.utf8'
  ]
];
/site/languages/de.php
<?php

return [
  'code' => 'de',
  'default' => false,
  'direction' => 'ltr',
  'name' => 'Deutsch',
  'url' => 'de',
  'locale'  => [
    LC_COLLATE  => 'de_DE.utf8',
    LC_MONETARY => 'de_DE.utf8',
    LC_NUMERIC  => 'de_DE.utf8',
    LC_TIME     => 'de_DE.utf8',
    LC_MESSAGES => 'de_DE.utf8',
    LC_CTYPE    => 'de_DE.utf8'
  ]
];

Language specific date handlers

By default, Kirby uses PHP's date function to format dates for pages and files. date() does not respect locale settings and always creates English month and day names. You can switch to strftime() as your primary date handler, which uses a different format for dates, but also supports translated month and day names. To switch the handler, add the following to your config:

/site/config/config.php
<?php

return [
  'date.handler'  => 'strftime',
];

Automatic language detection

Kirby can detect the preferred language of the visitor. This has to be enabled in your config:

/site/config/config.php
return [
  'languages.detect' => true
]