harbour-core/harbour/doc/en/lang.txt

/*
 * $Id$
 */

/*
 * The following parts are Copyright of the individual authors.
 * www - http://harbour-project.org
 *
 * Copyright 2000 Luiz Rafael Culik <culik@sl.conex.net>
 *    Documentation for: HB_LANGNAME(), HB_LANGSELECT()
 *
 * Copyright 2004 Chen Kedem <niki@actcom.co.il>
 *    Documentation for: HB_LANGERRMSG(),HB_LANGMESSAGE(),HB_SETCODEPAGE(),
 *                       HB_TRANSLATE()
 *
 * See COPYING for licensing terms.
 *
 */


/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      HB_LANGERRMSG()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Language and Nation
 *  $ONELINER$
 *      Description of an error code using current language
 *  $SYNTAX$
 *      HB_LANGERRMSG( <nErrorCode> ) --> cErrorMessage
 *  $ARGUMENTS$
 *      <nErrorCode> is one of the generic error codes (EG_...) defined
 *      in include/error.ch
 *  $RETURNS$
 *      HB_LANGERRMSG() return the error message string represented by
 *      the code <nErrorCode>.
 *  $DESCRIPTION$
 *      This function return the error message associated with an error
 *      code using the current language selected.
 *  $EXAMPLES$
 *      #include "error.ch"
 *      REQUEST HB_LANG_ES
 *      FUNCTION Main()
 *      // English: Argument error
 *      ? "English:", HB_LANGERRMSG( EG_ARG )
 *      HB_LANGSELECT( "ES" )
 *      // Spanish: Error de argumento
 *      ? "Spanish:", HB_LANGERRMSG( EG_ARG )
 *      RETURN NIL
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      H
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library are rtl, lang
 *      Header is error.ch
 *  $SEEALSO$
 *      HB_LANGSELECT(),NATIONMSG()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      HB_LANGMESSAGE()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Language and Nation
 *  $ONELINER$
 *      Returns international strings messages and errors
 *  $SYNTAX$
 *      HB_LANGMESSAGE( <nMsg> ) --> cMessage
 *  $ARGUMENTS$
 *      <nMsg> is the message number to get.
 *  $RETURNS$
 *      HB_LANGMESSAGE() return the text associated with the code <nMsg>.
 *  $DESCRIPTION$
 *      HB_LANGMESSAGE() is similar to NATIONMSG() but give access to the
 *      whole list of language messages: Day and month names, generic error
 *      messages, internal errors, and others...
 *
 *      Use the header file hblang.ch for a list of base values for <nMsg>.
 *  $EXAMPLES$
 *      #include "hblang.ch"
 *      REQUEST HB_LANG_ES
 *      FUNCTION Main()
 *      // English: Monday
 *      ? "English:", HB_LANGMESSAGE( HB_LANG_ITEM_BASE_DAY + 1 )
 *      HB_LANGSELECT( "ES" )
 *      // Spanish: Lunes
 *      ? "Spanish:", HB_LANGMESSAGE( HB_LANG_ITEM_BASE_DAY + 1 )
 *      RETURN NIL
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      H
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library are rtl, lang
 *      Header is hblang.ch
 *  $SEEALSO$
 *      HB_LANGSELECT(),NATIONMSG(),REQUEST
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      HB_LANGNAME()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Language and Nation
 *  $ONELINER$
 *      Return the name of the current language module in use
 *  $SYNTAX$
 *      HB_LANGNAME() --> cLangName
 *  $ARGUMENTS$
 *      None.
 *  $RETURNS$
 *      <cLangName>  Name of the current language in use
 *  $DESCRIPTION$
 *      This function return the current name of the language module in use.
 *  $EXAMPLES$
 *      REQUEST HB_LANG_PT
 *      REQUEST HB_LANG_RO
 *      REQUEST HB_LANG_ES
 *      FUNCTION Main()
 *      HB_LANGSELECT( 'PT' )       // Default language is now Portuguese
 *      ? CDOW( DATE() )            //Segunda-feira
 *      ? 'Current language is ", HB_LANGNAME()             // Portuguese
 *      ? 'Old language id selected is ", HB_LANGSELECT()   // PT
 *      HB_LANGSELECT( 'RO' )       // Default language is now Romanian
 *      ? CMONTH( DATE() )          // Mai
 *      ? 'Old language id selected is ",HB_LANGSELECT()    // RO
 *      HB_LANGSELECT( 'ES' )       // Default language is now Spanish
 *      ? 'Current language is ",HB_LANGNAME()              // Spanish
 *      ? CMONTH( DATE() )          // Mayo
 *      ? CDOW( DATE() )            // Lunes
 *      RETURN NIL
 *  $TESTS$
 *      See tests/langapi.prg, tests/langmsg.prg
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      H
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library are rtl, lang
 *  $SEEALSO$
 *      HB_LANGSELECT(),NATIONMSG()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      HB_LANGSELECT()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Language and Nation
 *  $ONELINER$
 *      Select a specific nation message module
 *  $SYNTAX$
 *      HB_LANGSELECT( [<cNewLang>] ) --> cOldLang
 *  $ARGUMENTS$
 *      <cNewLang>  The optional ID of the country language module.
 *      Possible values for <cNewLang> are below as defined in the
 *      Lang library, sorted by language.
 *
 *      <table>
 *      Language              Codepage       <cNewLang>
 *
 *      Bulgarian             866            BG866
 *      Bulgarian             ISO-8859-5     BGISO
 *      Bulgarian             Windows-1251   BGWIN
 *      Basque                850            EU
 *      Catalan               850            CA
 *      Chinese Simplified    936            ZHGB
 *      Chinese Traditional   950            ZHB5
 *      Croatian              852            HR852
 *      Croatian              ISO-8859-2     HRISO
 *      Czech                 852            CS852
 *      Czech                 ISO-8859-2     CSISO
 *      Czech                 Kamenickych    CSKAM
 *      Czech                 Windows-1250   CSWIN
 *      Dutch                 437            NL
 *      English               437            EN
 *      Esperanto             850            EO
 *      French                850            FR
 *      Galician              850            GL
 *      German                850            DE
 *      German ANSI           ANSI           DEWIN
 *      Greek                 737            EL
 *      Greek ANSI            Windows-1253   ELWIN
 *      Hebrew                862            HE862
 *      Hebrew                Windows-1255   HEWIN
 *      Hungarian             852            HU852
 *      Hungarian             CWI-2          HUCWI
 *      Hungarian             ISO-8859-2     HUISO
 *      Hungarian             Windows-1250   HUWIN
 *      Icelandic             850            IS850
 *      Indonesian            437            ID
 *      Italian               437            IT
 *      Korean                949            KO
 *      Lithuanian            Windows-1257   LT
 *      Polish                852            PL852
 *      Polish                ISO-8859-2     PLISO
 *      Polish                Mazowia        PLMAZ
 *      Polish                Windows-1250   PLWIN
 *      Portuguese            850            PT
 *      Romanian              852            RO
 *      Russian               866            RU866
 *      Russian               KOI-8          RUKOI8
 *      Russian               Windows-1251   RUWIN
 *      Serbian               852            SR852
 *      Serbian               ISO-8859-2     SRISO
 *      Serbian               Windows-1251   SRWIN
 *      Slovenian             437            SL437
 *      Slovenian             852            SL852
 *      Slovenian             ISO-8859-2     SLISO
 *      Slovenian             Windows-1250   SLWIN
 *      Spanish               850            ES
 *      Spanish ANSI          ANSI           ESWIN
 *      Turkish               857            TR857
 *      Turkish               Windows-1254   TRWIN
 *      </table>
 *  $RETURNS$
 *      <cOldLang>   The old language indentifier
 *  $DESCRIPTION$
 *      This function set a default language module for date/month names,
 *      internal warnigs, NatMsg messages and internal errors. When a
 *      Lang ID is selected all messages will be output with the current
 *      language selected until another one is selected or the program ends.
 *      The default language is English (cLang == "EN").
 *
 *      NOTE: You must REQUEST every language module you intend to use.
 *      For example: to use the Russian RU866 language you must add the
 *      following to your program: REQUEST HB_LANG_RU866
 *  $EXAMPLES$
 *      REQUEST HB_LANG_PT
 *      REQUEST HB_LANG_RO
 *      REQUEST HB_LANG_ES
 *      FUNCTION Main()
 *      HB_LANGSELECT( 'PT' )       // Default language is now Portuguese
 *      ? CDOW( DATE() )            // Segunda-feira
 *      ? 'Old language id selected is ", HB_LANGSELECT()   // PT
 *      HB_LANGSELECT( 'RO' )       // Default language is now Romanian
 *      ? CMONTH( DATE() )          // Mai
 *      ? 'Old language id selected is ",HB_LANGSELECT()   // RO
 *      HB_LANGSELECT( 'ES' )       // Default language is now Spanish
 *      ? CMONTH( DATE() )          // Mayo
 *      ? CDOW( DATE() )            // Lunes
 *      RETURN NIL
 *  $TESTS$
 *      See tests/langapi.prg, tests/langmsg.prg
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      H
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Libraty are rtl, lang
 *  $SEEALSO$
 *      HB_LANGNAME(),HB_SETCODEPAGE(),NATIONMSG(),REQUEST
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      HB_SETCODEPAGE()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Language and Nation
 *  $ONELINER$
 *      Select the active code page by language ID
 *  $SYNTAX$
 *      HB_SETCODEPAGE( [<cNewLang>] ) --> cOldLang
 *  $ARGUMENTS$
 *      <cNewLang>  The optional ID of the country language module.
 *      Possible values for <cNewLang> are below as defined in the
 *      Codepage library, sorted by language.
 *
 *      <table>
 *      Language              Codepage       <cNewLang>
 *
 *      Bulgarian             866            BG866
 *      Bulgarian             ISO-8859-5     BGISO
 *      Bulgarian             MIK            BGMIK
 *      Bulgarian             Windows-1251   BGWIN
 *      Croatian              437            HR437
 *      Croatian              852            HR852
 *      Croatian              Windows-1250   HR1250
 *      Czech                 852            CS852
 *      Czech                 ISO-8859-2     CSISO
 *      Czech                 KAM            CSKAM
 *      Czech                 Windoes-1250   CSWIN
 *      English               437            EN
 *      French                850            FR
 *      German                850            DE
 *      German                ISO-8859-1     DEWIN
 *      Greek                 737            EL
 *      Greek                 Windows-1253   ELWIN
 *      Hungarian (ntxhu852)  852            HU852
 *      Hungarian (sixhu852)  852            HU852S
 *      Hungarian (ntxhu852)  ISO-8859-2     HUISO
 *      Hungarian (sixhu852)  ISO-8859-2     HUISOS
 *      Hungarian (ntxhu852)  Windows-1250   HUWIN
 *      Hungarian (sixhu852)  Windows-1250   HUWINS
 *      Italian               437            IT437
 *      Italian               850            IT850
 *      Italian               ISO-8859-1b    ITISB
 *      Italian               ISO-8859-1     ITISO
 *      Lithuanian            Windows-1257   LT
 *      Polish                852            PL852
 *      Polish                ISO-8859-2     PLISO
 *      Polish                Mazowia        PLMAZ
 *      Polish                Windows-1250   PLWIN
 *      Portuguese            850            PT850
 *      Portuguese            ISO-8859-1     PTISO
 *      Russian               866            RU866
 *      Russian               KOI-8          RUKOI8
 *      Russian               Windows-1251   RU1251
 *      Serbian               Windows-1251   SRWIN
 *      Slovak                852            SK852
 *      Slovak                ISO-8859-2     SKISO
 *      Slovak                Kamenicky      SKKAM
 *      Slovak                Windows-1250   SKWIN
 *      Slovenian             437            SL437
 *      Slovenian             852            SL852
 *      Slovenian             ISO-8859-2     SLISO
 *      Slovenian             Windows-1250   SLWIN
 *      Spanish               850            ES
 *      Spanish               ISO-8859-1     ESWIN
 *      Spanish Modern        ISO-8859-1     ESMWIN
 *      Swedish               850            SV850
 *      Swedish (Clipper)     437            SVCLIP
 *      Swedish               ISO-8859-1     SVWIN
 *      Turkish               857            TR857
 *      Turkish               Windows-1254   TRWIN
 *      Ukrainian             866            UA866
 *      Ukrainian             KOI-8U         UAKOI8
 *      Ukrainian             Windows-1251   UA1251
 *      </table>
 *  $RETURNS$
 *      <cOldLang>   The old language indentifier
 *  $DESCRIPTION$
 *      HB_SETCODEPAGE() set the active code page use by Harbour for
 *      sorting and comparing strings. The default code page use ASCII
 *      order (cLang == "EN").
 *
 *      NOTE: You must REQUEST every code page module you intend to use.
 *      For example: to use the Russian RU866 code page you must add the
 *      following to your program: REQUEST HB_CODEPAGE_RU866
 *  $EXAMPLES$
 *      REQUEST HB_CODEPAGE_HU852
 *      FUNCTION Main()
 *      LOCAL cTxt := CHR( 71 ) + " > " + CHR( 144 ) + " is"
 *      ? HB_SETCODEPAGE()               // EN
 *      ? cTxt, CHR( 71 ) > CHR( 144 )   // G > <20> is .F.
 *      ? HB_SETCODEPAGE( "HU852" )      // EN
 *      ? cTxt, CHR( 71 ) > CHR( 144 )   // G > <20> is .T.
 *      ? HB_SETCODEPAGE( "EN" )         // HU852
 *      ? cTxt, CHR( 71 ) > CHR( 144 )   // G > <20> is .F.
 *      RETURN NIL
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      This function is a Harbour Extension.
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Libraty are rtl, codepage
 *  $SEEALSO$
 *      HB_LANGNAME(),HB_LANGSELECT(),HB_TRANSLATE(),NATIONMSG(),REQUEST
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      HB_TRANSLATE()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Language and Nation
 *  $ONELINER$
 *      Translate a string from one code page to the other
 *  $SYNTAX$
 *      HB_TRANSLATE( <cSrcText>, [<cPageFrom>], [<cPageTo>] ) --> cDstText
 *  $ARGUMENTS$
 *      <cSrcText> Is the source string to translate.
 *
 *      <cPageFrom> Is the optional character code page ID of the source
 *      string. If not specified, the default code page is used.
 *
 *      <cPageTo> Is the optional character code page ID of the destination
 *      string. If not specified, the default code page is used.
 *  $RETURNS$
 *      HB_TRANSLATE() return destination string converted from the source
 *      string.
 *  $DESCRIPTION$
 *      HB_TRANSLATE() try to convert a source string from one code page
 *      into the other. If a code page ID is not recognized, or not linked
 *      in, the default code page is used. HB_TRANSLATE() is used usually
 *      to convert between the Dos and the Windows code pages of the same
 *      language.
 *
 *      NOTE: If the source code page and target code page does not have
 *      the same number of characters, a translation can not be done and
 *      the destination string is a copy of the source string.
 *
 *      NOTE: You must REQUEST every code page module you intend to use.
 *      For example: to use the Russian RU866 code page you must add the
 *      following to your program: REQUEST HB_CODEPAGE_RU866
 *  $EXAMPLES$
 *      REQUEST HB_CODEPAGE_DE
 *      REQUEST HB_CODEPAGE_DEWIN
 *      FUNCTION Main()
 *      LOCAL cTxt := "A" + CHR( 142 ) + "BC"
 *      ? "German 850  text:", cTxt
 *      ? "German ANSI text:", HB_TRANSLATE( cTxt, "DE", "DEWIN" )
 *      RETURN NIL
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      This function is a Harbour Extension.
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Libraty are rtl, codepage
 *  $SEEALSO$
 *      HB_LANGSELECT(),HB_SETCODEPAGE(),NATIONMSG(),REQUEST
 *  $END$
 */