shakespeare-2.1.0: A toolkit for making compile-time interpolated templates
Copyright2012 Michael Snoyman <michael@snoyman.com> Jeremy Shaw
LicenseBSD-style (see the LICENSE file in the distribution)
MaintainerMichael Snoyman <michael@snoyman.com>
Stabilityexperimental
Portabilityportable
Safe HaskellSafe-Inferred
LanguageHaskell2010

Text.Shakespeare.I18N

Description

This module provides a type-based system for providing translations for text strings.

It is similar in purpose to gettext or Java message bundles.

The core idea is to create simple data type where each constructor represents a phrase, sentence, paragraph, etc. For example:

data AppMessages = Hello | Goodbye

The RenderMessage class is used to retrieve the appropriate translation for a message value:

class RenderMessage master message where
  renderMessage :: master  -- ^ type that specifies which set of translations to use
                -> [Lang]  -- ^ acceptable languages in descending order of preference
                -> message -- ^ message to translate
                -> Text

Defining the translation type and providing the RenderMessage instance in Haskell is not very translator friendly. Instead, translations are generally provided in external translations files. Then the mkMessage Template Haskell function is used to read the external translation files and automatically create the translation type and the RenderMessage instance.

A full description of using this module to create translations for Hamlet can be found here:

http://www.yesodweb.com/book/internationalization

A full description of using the module to create translations for HSP can be found here:

http://happstack.com/docs/crashcourse/Templates.html#hsp-i18n

You can also adapt those instructions for use with other systems.

Synopsis

Documentation

mkMessage Source #

Arguments

:: String

base name to use for translation type

-> FilePath

subdirectory which contains the translation files

-> Lang

default translation language

-> Q [Dec] 

generate translations from translation files

This function will:

  1. look in the supplied subdirectory for files ending in .msg
  2. generate a type based on the constructors found
  3. create a RenderMessage instance

mkMessageFor Source #

Arguments

:: String

master translation data type

-> String

existing type to add translations for

-> FilePath

path to translation folder

-> Lang

default language

-> Q [Dec] 

create RenderMessage instance for an existing data-type

mkMessageVariant Source #

Arguments

:: String

master translation data type

-> String

existing type to add translations for

-> FilePath

path to translation folder

-> Lang

default language

-> Q [Dec] 

create an additional set of translations for a type created by mkMessage

class RenderMessage master message where Source #

the RenderMessage is used to provide translations for a message types

The master argument exists so that it is possible to provide more than one set of translations for a message type. This is useful if a library provides a default set of translations, but the user of the library wants to provide a different set of translations.

Methods

renderMessage Source #

Arguments

:: master

type that specifies which set of translations to use

-> [Lang]

acceptable languages in descending order of preference

-> message

message to translate

-> Text 

Instances

Instances details
RenderMessage master Text Source # 
Instance details

Defined in Text.Shakespeare.I18N

Methods

renderMessage :: master -> [Lang] -> Text -> Text Source #

master ~ master' => RenderMessage master (SomeMessage master') Source # 
Instance details

Defined in Text.Shakespeare.I18N

Methods

renderMessage :: master -> [Lang] -> SomeMessage master' -> Text Source #

class ToMessage a where Source #

ToMessage is used to convert the value inside #{ } to Text

The primary purpose of this class is to allow the value in #{ } to be a String or Text rather than forcing it to always be Text.

Methods

toMessage :: a -> Text Source #

Instances

Instances details
ToMessage Text Source # 
Instance details

Defined in Text.Shakespeare.I18N

Methods

toMessage :: Text -> Text Source #

ToMessage String Source # 
Instance details

Defined in Text.Shakespeare.I18N

data SomeMessage master Source #

Constructors

forall msg.RenderMessage master msg => SomeMessage msg 

Instances

Instances details
master ~ master' => RenderMessage master (SomeMessage master') Source # 
Instance details

Defined in Text.Shakespeare.I18N

Methods

renderMessage :: master -> [Lang] -> SomeMessage master' -> Text Source #

IsString (SomeMessage master) Source # 
Instance details

Defined in Text.Shakespeare.I18N

Methods

fromString :: String -> SomeMessage master #

type Lang = Text Source #

an RFC1766 / ISO 639-1 language code (eg, fr, en-GB, etc).