-- 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 <a>http://www.yesodweb.com/book/shakespearean-templates</a>
--   for more information.
@package shakespeare-i18n
@version 1.0.0.3


-- | 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:
--   
--   <pre>
--   data AppMessages = Hello | Goodbye
--   </pre>
--   
--   The <a>RenderMessage</a> class is used to retrieve the appropriate
--   translation for a message value:
--   
--   <pre>
--   class RenderMessage master message where
--     renderMessage :: master  -- ^ type that specifies which set of translations to use
--                   -&gt; [Lang]  -- ^ acceptable languages in descending order of preference
--                   -&gt; message -- ^ message to translate
--                   -&gt; Text
--   </pre>
--   
--   Defining the translation type and providing the <a>RenderMessage</a>
--   instance in Haskell is not very translator friendly. Instead,
--   translations are generally provided in external translations files.
--   Then the <a>mkMessage</a> Template Haskell function is used to read
--   the external translation files and automatically create the
--   translation type and the <tt>RenderMessage</tt> instance.
--   
--   A full description of using this module to create translations for
--   <tt>Hamlet</tt> can be found here:
--   
--   <a>http://www.yesodweb.com/book/internationalization</a>
--   
--   A full description of using the module to create translations for
--   <tt>HSP</tt> can be found here:
--   
--   <a>http://happstack.com/docs/crashcourse/Templates.html#hsp-i18n</a>
--   
--   You can also adapt those instructions for use with other systems.
module Text.Shakespeare.I18N

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

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

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

-- | the <a>RenderMessage</a> is used to provide translations for a message
--   types
--   
--   The <tt>master</tt> argument exists so that it is possible to provide
--   more than one set of translations for a <tt>message</tt> 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

-- | <a>ToMessage</a> is used to convert the value inside #{ } to
--   <a>Text</a>
--   
--   The primary purpose of this class is to allow the value in #{ } to be
--   a <a>String</a> or <a>Text</a> rather than forcing it to always be
--   <a>Text</a>.
class ToMessage a
toMessage :: ToMessage a => a -> Text
data SomeMessage master
SomeMessage :: msg -> SomeMessage master

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