This guide will walk you through setting up a language, choosing a language context methodology, and language toggle options.

Add Your Language(s)

First, you will need to add a new language (if you have not already done so). You can do this by navigating to Settings > Languages and click on the “New” button. If you receive an error message, your license may not support an additional language. If this is the case, please contact support@agilitycms.com.

Choose Your Language Context

Next, you’ll need to decide how to keep track of the language context. There are generally three options – Language Code in URL, Separate Domain per Language, or Cookie Language.

Language Code in URL

Having the Language Code in the URL means that the current language will always be the first path in the URL such as http://mysite.com/en-us/about-us or http://mysite.com/fr-ca/about-us.

This must be enabled in Settings > Development Framework.

Separate Domain per Language

Having a separate domain per language means that each language will be mapped to a specific domain. In this case, you may have URLs that appear like http://en.mysite.com/about or http://fr.mysite.com/about.

Adding your domains:

1. Go to Settings > Domain Configuration > click on your Website Channel and then click the “New” (+) button to define your domains.
2. On the Channel Domain Details flyout, enter a Name, Domain URL, and Default Path.
3. Ensure you set your Default Language and the Force Default Language checkbox. This will ensure that when a user arrives on that domain that the appropriate language is automatically used.

Cookie Language

When you are not using the Language Code in the URL or a Separate Domain per Language, then you are by default using the Cookie Language method. This means that a user will arrive on your site in your default language and then will require a request to change the language code via querystring (i.e. ?lang=fr-ca). Changing the language will NOT change anything in the URL path and instead the language code will only be stored in a cookie. This option is not recommended for sites that must be SEO friendly and should only be considered for testing or internal applications where SEO is not required.

Toggling the Language

Once you have your languages setup and have determined a context strategy, its now time to setup your language toggle. This allows users on the website to switch between languages. There are a couple ways to do this with Agility providing an option out-of-the-box or creating your own.

Default Language Toggle

The simplest implementation of a language toggle utilizes a query string parameter to change the language. The parameter looks like “?lang={lang-code}”. Adding this to your website is easy and can be added as simple anchor tag.

Default Behaviour

When you switch to a different language, Agility.Web will automatically find the connected page in that target language and will handle changing the language and loading that page. If there is not connected page in the target language, the routing engine will simply return the original page again (in the original language).

Optional Behaviour

By default, if the corresponding page does not exist in the target language are redirect will occur back to the origin language. However, you can instead change the behaviour to 404 in the target language instead.

To do this, you must set an override in the Agility.Web settings in the web.config. The property that controls this is redirect404ToDefaultLanguage. By default, if this property is not set then it is set to True. You can override this by setting it to False.

<settings applicationName="Agility Sample MVC4" developmentMode="true" contentCacheFilePath="c:\AgilityContent\" redirect404ToDefaultLanguage="false" >

Custom Language Toggle

Often, there are specific requirements that must be met for the language toggle that fall outside the default behaviour. In this case, it is recommended to create your own language toggle logic.

The recommended approach for this would be to have your own custom route that is executed when a user clicks the language switch anchor tag, or selects a language from a dropdown list.

Within the Controller ActionResult for that custom route, you are able to utilize properties from AgilityContext and methods in Agility.Web.Data (http://developer.agilitycms.com/Documentation/Web-Content-Management/apis-and-sdks/web-forms-sdk/Web-Forms-Related-API-Calls/Agility-Web-Data.aspx) where you can get the current page in the current language, find the target page in the target language and even do more complex things like searching the target language sitemap.

The end result should be a 301 or 302 redirect to a page in the target language.

Programatically Setting a Language Context

In cases where you want to set the current language context in code, you can do this using the following code in C#:

AgilityContext.LanguageCode = "{lang-code}" //i.e. "en-us"

This will set response cookies behind the scenes and set the current language context for the site. You can call this method as many times as you want in the life-cycle of a page render, the last time this is called, will ultimately determine the language context cookie sent in the response.

It can be useful to switch language contexts programtically in code to search for a page/content in other languages.