## Documentation

Table of Contents
Class Inheritance Tree
Widget Screenshots
Package groups

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.     -----------------------------------------------------------------------

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>

145.     with GlibTo API docTo specTo body;

147.     package Gtkada.IntlTo API docTo spec is

148.        pragma Preelaborate;

150.        function Gettext (Msg : Glib.UTF8_StringTo API docTo spec) return Glib.UTF8_StringTo API docTo spec;

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).

155.        function Dgettext

156.          (Domain : String; Msg : Glib.UTF8_StringTo API docTo spec) return Glib.UTF8_StringTo API docTo spec;

157.        --  Look up Msg in the Domain message catalog for the current locale.

159.        function "-" (Msg : Glib.UTF8_StringTo API docTo spec) return Glib.UTF8_StringTo API docTo spec;

160.        --  Shortcut for Dgettext ("GtkAda", Msg)

162.        function Dcgettext

163.          (Domain : String; Msg : Glib.UTF8_StringTo API docTo spec; Category : Integer)

164.           return Glib.UTF8_StringTo API docTo spec;

165.        --  Look up Msg in the Domain message catalog for the Category locale.

167.        function Default_Text_Domain return String;

168.        --  Return the current default message catalog.

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".

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.

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.

184.     end Gtkada.IntlTo API docTo spec;