-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/

-- | A type-based approach to internationalization.
--   
--   This package uses a compile-time, type-safe approach to create
--   translated content. It has a simple syntax for translators, while
--   allowing the full power of Haskell for applying complex grammar rules.
--   
--   This package was spun off from yesod-core, and therefore the Yesod
--   documentation is a good place to start in understanding this package.
--   Please see http://www.yesodweb.com/book/shakespearean-templates
--   for more information.
@package shakespeare-i18n
@version 1.0.0.2

-- | 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.
module Text.Shakespeare.I18N

-- | generate translations from translation files
--   
--   This function will:
--   
--   
--   
- look in the supplied subdirectory for files ending in
--   .msg
--   
- generate a type based on the constructors found
--   
- create a RenderMessage instance
--   
mkMessage :: String -> FilePath -> Lang -> Q [Dec]

-- | create RenderMessage instance for an existing data-type
mkMessageFor :: String -> String -> FilePath -> Lang -> Q [Dec]

-- | create an additional set of translations for a type created by
--   mkMessage
mkMessageVariant :: String -> String -> FilePath -> Lang -> Q [Dec]

-- | 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.
class RenderMessage master message
renderMessage :: RenderMessage master message => master -> [Lang] -> message -> Text

-- | 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.
class ToMessage a
toMessage :: ToMessage a => a -> Text
data SomeMessage master
SomeMessage :: msg -> SomeMessage master

-- | an RFC1766 / ISO 639-1 language code (eg, fr, en-GB,
--   etc).
type Lang = Text
instance RenderMessage master (SomeMessage master)
instance IsString (SomeMessage master)
instance RenderMessage master Text
instance ToMessage String
instance ToMessage Text
