shakespeare-2.1.0.1: A toolkit for making compile-time interpolated templates

Copyright | 2012 Michael Snoyman <michael@snoyman.com> Jeremy Shaw
License | BSD-style (see the LICENSE file in the distribution)
Maintainer | Michael Snoyman <michael@snoyman.com>
Stability | experimental
Portability | portable
Safe Haskell | Safe-Inferred
Language | Haskell2010

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

- mkMessage :: String -> FilePath -> Lang -> Q [Dec]
- mkMessageFor :: String -> String -> FilePath -> Lang -> Q [Dec]
- mkMessageVariant :: String -> String -> FilePath -> Lang -> Q [Dec]
- class RenderMessage master message where
  - renderMessage :: master -> [Lang] -> message -> Text
- class ToMessage a where
  - toMessage :: a -> Text
- data SomeMessage master = forall msg.RenderMessage master msg => SomeMessage msg
- type Lang = Text

# Documentation

mkMessage #

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 #

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 #

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 #

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 #

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 # |
Instance details Defined in Text.Shakespeare.I18N Methods renderMessage :: master -> [Lang] -> Text -> Text #
master ~ master' => RenderMessage master (SomeMessage master') # |
Instance details Defined in Text.Shakespeare.I18N Methods renderMessage :: master -> [Lang] -> SomeMessage master' -> Text #

class ToMessage a where #

`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 #

#### Instances

Instances details

ToMessage Text # |
Instance details Defined in Text.Shakespeare.I18N Methods toMessage :: Text -> Text #
ToMessage String # |
Instance details Defined in Text.Shakespeare.I18N Methods toMessage :: String -> Text #

data SomeMessage master #

Constructors

forall msg.RenderMessage master msg => SomeMessage msg |

#### Instances

Instances details

master ~ master' => RenderMessage master (SomeMessage master') # |
Instance details Defined in Text.Shakespeare.I18N Methods renderMessage :: master -> [Lang] -> SomeMessage master' -> Text #
IsString (SomeMessage master) # |
Instance details Defined in Text.Shakespeare.I18N Methods fromString :: String -> SomeMessage master

type Lang = Text #

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