Grav - Multi Language

Multi–Language is defined as the use of different languages into your site. By using the following procedure you can learn how to use multi–languages in your Grav site.

Multi – Languages Basics

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

Language Configuration

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

Language:
  Supported:
     - 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 it will look for default.en.md file.If that file is not found then looks for another language you have set. If both the languages are not found then it looks for default.md file.
Example: default.en.md file:

---
title: Home
---

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

This gives you the following output:
For french as default language, default.fr.md file will be:

---
titre: Accueil
---

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

This gives you the following output:

Active language via URL

If you want to update a url to your website with a language code then follow the below steps:
Example :
If you want your site to be in english, then type the below line in your browser:

http://www.mysite.com/en

If you want your site to be in french, then type the below line in your browser:

http://www.mysite.com/fr 

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:

home:
  aliases:
    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 http://www.mysite.com/en/home

languages:
   home_redirect:
     include_lang: true
     include_route: false

Language-Based Twig Templates

If your file is default.en.md, 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 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 language file in your user/languages/ folder.

Advanced

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 http://english.yoursite.com, an alias for your standard http://www.yoursite.com, then you can create a configuration as /user/english.yoursite.com/config/system.yaml.

languages:
  supported:
    - 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

As it is very difficult to switch between different language versions of the same page, you can use Page.rawRoute() method on your page object. It gets the same raw route for different language translations of 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:

/ma-page-francaise-personnalisee

English page has the custom route of:

/my-custom-french-page

You get the raw page of the french page and that might be:

/blog/custom/my-page

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

/en/blog/custom/my-page

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.

languages:
  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
HEADER:
    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.

languages:
  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 needs.

# http://www.cheat-sheets.org/saved-copy/mod_rewrite_cheat_sheet.pdf
# http://www.workingwith.me.uk/articles/scripting/mod_rewrite

# handle top level e.g. http://Grav-site.com/de
RewriteRule ^en/?$ "http://Grav-site.com" [R=301,L]
RewriteRule ^de/?$ "http://Grav-site.de" [R=301,L]

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