README

= Translator Extension

Created By: Phil Burrows, January 2008
peburrows@gmail.com
http://philburrows.com
http://dev.philburrows.com/svn/radiant-extensions/translator/trunk

-------------------------

== Description

This extension allows for different page parts to be rendered
depending on the user's Accept-Language header.

== Disclaimer

This extension works well for me, but YMMV.

== Dependencies

* None, really

== Usage

In the pages you wish to have different languages available,
simply create a page part with a two letter language abbreviation
suffix for every part you wish to have available in multiple languages.
Defaults to English if a page part is not defined that matches the
user's requested language.

NOTE: the default language is english, so page parts without the
two-letter language suffix will be considered english.

Examples:
---------
Page Parts:
  'body' (English)
  'body_de' (German translation)
  'body_fr' (French translation)
  
  'sidebar' (English)
  'sidebar_de' (German translation)
  'sidebar_fr' (French translation)

Then, in your layout, simply use the translator tags the same way you would use the standard Radiant content tag

<r:translator:content name="body" />
<r:translator:content name="sidebar" inherit="true" />

each of these will render the appropriate page part, determined by the browser's Accept-Language

You can also take advantage of the <r:translator:title /> tag which will render the normal page title by default,
but will first check for a config page part that specifies other titles for the different languages.
Sample config page part -->

translator:
  es:
    title: éste es el título
  de:
    title: dieses ist der titel

Also, if you wish to allow the user to explicitly set their language
(instead of relying on the browser sending the proper Accept-Language header),
this extension utilizes session variables (and an included controller to
set those variables) which override the Accept-Language header.
Just hit '/language/set/:lang' and replace :lang with the two-letter language
abbreviation. Also, hitting '/language/set/reset' will clear the session
variable and fall-back to relying on the Accept-Language header.

TODO:
* allow setting of the default language to something other than English
* support the four letter language abbreviations in the form of lang-REGION (en-US, fr-CA, fr-FR, etc.)