1. ----------------------------------------------------------------------- 
  2. --               GtkAda - Ada95 binding for Gtk+/Gnome               -- 
  3. --                                                                   -- 
  4. --      Copyright (C) 2000 E. Briot, J. Brobecker and A. Charlet     -- 
  5. --                Copyright (C) 2000-2003 ACT-Europe                 -- 
  6. --                                                                   -- 
  7. -- This library is free software; you can redistribute it and/or     -- 
  8. -- modify it under the terms of the GNU General Public               -- 
  9. -- License as published by the Free Software Foundation; either      -- 
  10. -- version 2 of the License, or (at your option) any later version.  -- 
  11. --                                                                   -- 
  12. -- This library is distributed in the hope that it will be useful,   -- 
  13. -- but WITHOUT ANY WARRANTY; without even the implied warranty of    -- 
  14. -- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU -- 
  15. -- General Public License for more details.                          -- 
  16. --                                                                   -- 
  17. -- You should have received a copy of the GNU General Public         -- 
  18. -- License along with this library; if not, write to the             -- 
  19. -- Free Software Foundation, Inc., 59 Temple Place - Suite 330,      -- 
  20. -- Boston, MA 02111-1307, USA.                                       -- 
  21. --                                                                   -- 
  22. -- As a special exception, if other files instantiate generics from  -- 
  23. -- this unit, or you link this unit with other files to produce an   -- 
  24. -- executable, this  unit  does not  by itself cause  the resulting  -- 
  25. -- executable to be covered by the GNU General Public License. This  -- 
  26. -- exception does not however invalidate any other reasons why the   -- 
  27. -- executable file  might be covered by the  GNU Public License.     -- 
  28. ----------------------------------------------------------------------- 
  29.  
  30. --  <description> 
  31. -- 
  32. --  This package provides support for string internationalization using the 
  33. --  libintl library. 
  34. -- 
  35. --  Developer setup 
  36. --  =============== 
  37. -- 
  38. --  To provide internationalization in your application, you must install a 
  39. --  number of files along with your application, and modify your code to 
  40. --  highlight the strings to translate. This translation is based on the 
  41. --  gettext() library. Reading its documentation is recommanded since it 
  42. --  explains best practices for handling translations. 
  43. -- 
  44. --  Preparing your code 
  45. --  =================== 
  46. -- 
  47. --  Gettext needs to information to locate the translation files: a language, 
  48. --  as setup by the user (see User Setup below), and a domain, hard-coded in 
  49. --  the application. The domain is the name of your application. Given these 
  50. --  two informations, the translation file will be found in: 
  51. --     $prefix/<lang>/LC_MESSAGES/<domain>.mo 
  52. -- 
  53. --  Where $prefix is either one of the standard search paths, or specified 
  54. --  through a call to Bind_Text_Domain. 
  55. -- 
  56. --  Although the user can simply specify which language to use by setting one 
  57. --  environment variable, they are in fact several other setup to be done, so 
  58. --  that the C library properly handles date format for instance. This is done 
  59. --  through a call to Setlocale. 
  60. -- 
  61. --  An application can be associated with several domains, although it is 
  62. --  generally recommanded to have one default domain, specify through a call to 
  63. --  Text_Domain. Each string can then be translated through a call to Gettext, 
  64. --  without specifying the domain every time. 
  65. --  A convenient shortcut is provided in the form of the "-" operator. 
  66. -- 
  67. --  As a result, typical code would look like: 
  68. --    begin 
  69. --       Setlocale; 
  70. --       Text_Domain ("application"); 
  71. --       Bind_Text_Domain ("application", "/usr/local/share/locale"); 
  72. --       ... 
  73. --       Put_Line (-"Internalized string"); 
  74. --    end; 
  75. -- 
  76. --  Preparing and installing the translation files 
  77. --  =============================================== 
  78. -- 
  79. --  The Gtkada distribution comes with a convenient script named 
  80. --  build_skeleton.pl, which you can run on your application to extract all the 
  81. --  strings that should be translated. See the "po/" directory in GtkAda, as 
  82. --  well as the Makefile in this directory. 
  83. -- 
  84. --  Running "make refresh" will reparse all the source files in your 
  85. --  application, and create (or update if they already exist) one file .po for 
  86. --  each language registered in the Makefile. 
  87. -- 
  88. --  You would then translate each of the string indicated my "msgid", by 
  89. --  modifying the lines starting with "msgstr". 
  90. -- 
  91. --  Once this is done, running the msgfmt tool through "make install" will 
  92. --  generate a <lang>.mo binary file, which should be copied in the directory 
  93. --     $prefix/<lang>/LC_MESSAGES/<domain>.mo 
  94. -- 
  95. --  The translation files can also be created fully by hand. 
  96. --  Here is a sample translation file that can be used as an input for msgfmt: 
  97. -- 
  98. --  # gtkada-fr.po 
  99. --  msgid  "Help" 
  100. --  msgstr "Aide" 
  101. -- 
  102. --  msgid  "Yes" 
  103. --  msgstr "Oui" 
  104. -- 
  105. --  $ msgfmt gtkada-fr.po -o gtkada-fr.gmo 
  106. --  $ cp gtkada-fr.gmo /usr/share/locale/fr/LC_MESSAGES/gtkada.mo 
  107. -- 
  108. --  If your program uses GtkAda, there are also a number of strings that need 
  109. --  to be translated in that library. The recommanded approach is to merge the 
  110. --  .po files found in the GtkAda distribution in the "po/" directory, and use 
  111. --  the tool msgmerge to merge these into your applications' translation file. 
  112. -- 
  113. --  User setup 
  114. --  ========== 
  115. -- 
  116. --  To change the current locale setting, use the environment variables 
  117. --  "LANG". For example, to switch to the french locale using 
  118. --  bash: 
  119. -- 
  120. --  $ export LANG=fr_FR 
  121. -- 
  122. --  Depending on the specific implementation of gettext, the following 
  123. --  environment variables may be set to change the default settings of locale 
  124. --  parameters: 
  125. -- 
  126. --    - LANG Specifies locale name. 
  127. -- 
  128. --    - LC_MESSAGES 
  129. --          Specifies messaging locale, and if present overrides 
  130. --          LANG for messages. 
  131. -- 
  132. --    - TEXTDOMAIN 
  133. --          Specifies the text domain name, which is identical to 
  134. --          the message object filename without .mo suffix. 
  135. -- 
  136. --    - TEXTDOMAINDIR 
  137. --          Specifies the pathname to the message database, and if 
  138. --          present replaces the default (e.g /usr/lib/locale on Solaris, 
  139. --          /usr/share/locale on Linux). 
  140. -- 
  141. --  See the gettext documentation of your specific OS for more details. 
  142. -- 
  143. --  </description> 
  144.  
  145. with Glib; 
  146.  
  147. package Gtkada.Intl is 
  148.    pragma Preelaborate; 
  149.  
  150.    function Gettext (Msg : Glib.UTF8_String) return Glib.UTF8_String; 
  151.    --  Look up Msg in the current default message catalog. 
  152.    --  Use the current locale as specified by LC_MESSAGES. If not found, return 
  153.    --  Msg itself (the default text). 
  154.  
  155.    function Dgettext 
  156.      (Domain : String; Msg : Glib.UTF8_String) return Glib.UTF8_String; 
  157.    --  Look up Msg in the Domain message catalog for the current locale. 
  158.  
  159.    function "-" (Msg : Glib.UTF8_String) return Glib.UTF8_String; 
  160.    --  Shortcut for Dgettext ("GtkAda", Msg) 
  161.  
  162.    function Dcgettext 
  163.      (Domain : String; Msg : Glib.UTF8_String; Category : Integer) 
  164.       return Glib.UTF8_String; 
  165.    --  Look up Msg in the Domain message catalog for the Category locale. 
  166.  
  167.    function Default_Text_Domain return String; 
  168.    --  Return the current default message catalog. 
  169.  
  170.    procedure Text_Domain (Domain : String := ""); 
  171.    --  Set the current default message catalog to Domain. 
  172.    --  If Domain is "", reset to the default of "messages". 
  173.  
  174.    procedure Bind_Text_Domain (Domain : String; Dirname : String); 
  175.    --  Specify that the Domain message catalog will be found in Dirname. 
  176.    --  This overrides the default system locale data base. 
  177.    --  Dirname will generally be the installation prefix for your application. 
  178.  
  179.    procedure Setlocale; 
  180.    --  This procedure must be called before any other subprogram in this 
  181.    --  package. It will initialize internal variables based on the environment 
  182.    --  variables. 
  183.  
  184. end Gtkada.Intl;