Grav - Multi Language


Multi-Language is defined as the use of different languages in your website. We will learn different procedures that will help you use multi–languages in your Grav site.

Multi – Languages Basics

Basically Grav needs a .md file for the representation of any page. When you enable the multi-language support, it will look for a file like or

Language Configuration

You must first set up some basic language configuration in your user/config/system.yaml file. file.

      - en
      - Fr

By doing this, you have enabled multi–language support in Grav. In the above code, en means English language and fr means French. This means your site will support these two languages. Here the default language is en (English). If you write Fr (French) first, then that becomes your default language.

Multiple Language Pages

If your default language is set as English, then Grav will look for file. If that file is not found, then Grav looks for another language you have set. If both the languages are not found, then it looks for the file.

Example file

title: Home

# Grav is Running!
## You have installed **Grav** successfully

The above code will generate the following output −

Grav Multi Language

For French as default language, the file will be −

titre: Accueil

# Grav est en marche!
## Vous avez installé ** ** Grav succès

The above code will generate the following output −

Grav Multi Language

Active Language via URL

If you want to update a URL to your website with a language code, then follow these steps −


If you want your site to be in English, then type the below line in your browser −

If you want your site to be in French, then type the below line in your browser − 

Active Language via Browser

Grav has the ability to get the http_accept_language value and compare them to present supported language. If you want this to function, then enable your user/system.yaml file in the language section as −

language :
   http_accept_language : true

Language-Based Homepage

To have a language based home page, you must enable the following code in your site.yaml file −

      en: /homepage
      fr: /page-d-accueil

In this way, Grav will find out which language to use from the active languages.

The following code will force Grav to redirect you to your default language route. And the include_route option forces to add the language code in your url like

      include_lang: true
      include_route: false

Language-Based Twig Templates

If your file is, then Grav will look for a twig file as default.html.twig. When you need a language–specific twig file, then you must upload it at the root level of the language folder. If your present theme is in templates/default.html.twig you must create a templates/en/ folder and place your English-specific folder in it as: templates/en/default.html.twig

Language Switcher

Language switcher plugin is available at Grav Package Manager (GPM).

Translations via Twig

Use twig filter and t() function. Both function similarly. If you have another twig file, then it lets you to translate from an array.

Plugin and Theme Language Translations

Provide your translations in plugins and themes by creating a languages.yaml file in the root of your theme or plugin (/user/plugins/error/languages.yaml) and must contain all the supported languages.

Translation Overrides

If you want to override translation, then you must put the value pair in the language file in your the user/languages/ folder.


Environment – Based Language Handling

It is possible to route users to the correct version of your site according to URL. If your site url is, an alias for your standard, then you can create a configuration as /user/

      - fr
      - en

It uses inverted language order. In the above code, fr is the default language. If you change the order by keeping en at the top and fr at the bottom, then en becomes the default language.

Language Alias Routes

It is very difficult to switch between different language versions of the same page, you can use the Page.rawRoute() method on your page object. It gets the same raw route for different language translations of a single page. Put the language code in the front to get a proper route.

If you are on page in French with a custom route of −


English page has the custom route of −


You get the raw page of the French page and that might be −


Then just add the language you want which will be your new URL.


Translations Support

Grav provides simple mechanism for providing translations in Twig via PHP to be used in themes and plugins. It is enabled by default and uses en language if no specific language is defined. To enable or disable, go to system.yaml file and make the changes.

   translations: true

You can provide translations in many ways and different places. The first place is system/languages folder. Files must be created in en.yaml, fr.yaml, etc. format. Each yaml file must consist an array or nested arrays of key pairs.

SITE_NAME: My Blog Site
   MAIN_TEXT: Welcome to my new blog site
   SUB_TEXT: Check back daily for the latest news

Session Based Active Language

You can activate session-based storage of the active language. To enable you must have session : enables : true in system.yaml and enable language setting.

   session_store_active: true

Language Switcher

Install a language switching plugin from GPM.

Setup with language specific domains

Have Environment based language handling configuration to assign default languages. Add this option to your system.yaml; it must be set to true.

pages.redirect_default_route: true

Add the following to your .htaccess file and pick the language slugs and domain names according to your requirements.


# handle top level e.g.
RewriteRule ^en/?$ "" [R = 301, L]
RewriteRule ^de/?$ "" [R = 301, L]

# handle sub pages, exclude admin path
RewriteCond %{REQUEST_URI} !(admin) [NC]
RewriteRule ^en/(.*)$ "$1" [R = 301, L]
RewriteCond %{REQUEST_URI} !(admin) [NC]
RewriteRule ^de/(.*)$ "$1" [R = 301, L]