README

   1 intltool README
   2 ===============
   3
   4 If you have problems understanding this README file, then please report
   5 these at http://bugs.launchpad.net/intltool on Launchpad. Patches are
   6 also very welcome. See HACKING for more information on submitting patches.
   7
   8 The intltool collection can be used to do these things:
   9
  10  o Extract translatable strings from various source files (.xml.in,
  11    .glade, .desktop.in, .server.in, .oaf.in).
  12
  13  o Collect the extracted strings together with messages from traditional
  14    source files (.c, .h) in po/$(PACKAGE).pot.
  15
  16  o Merge back the translations from .po files into .xml, .desktop and
  17    .oaf files.  This merge step will happen at build resp. installation
  18    time.
  19
  20 The intltool package has a script, intltoolize, which copies the various
  21 scripts and does the other magic to your module. So users building
  22 from tarballs don't need intltool, only folks building from cvs.
  23 (This is modelled on gettextize.)
  24
  25
  26 How to Use with autoconf/automake
  27 ---------------------------------
  28 (There is a section for non-auto* configurations below)
  29
  30 To use intltool in your module, do the following:
  31
  32  o Install intltool, and make sure that the macro it installs is
  33    in aclocal's path, or do:
  34
  35         export ACLOCAL_FLAGS='-I /usr/local/share/aclocal'
  36
  37  o Add these lines to autogen.sh, after the call to gettextize:
  38
  39         echo "Running intltoolize"
  40         intltoolize --copy --force --automake
  41
  42  o Add this line to configure.in near the top
  43
  44         IT_PROG_INTLTOOL([minimum required version], [no-xml])
  45
  46  o Add intltool-extract, intltool-merge, and intltool-update to
  47    DISTCLEANFILES in your top-level Makefile.am.
  48
  49  o Remove po/desk.pl and po/update.* scripts.  intltool-update will take
  50    over their functionality.
  51
  52 At this point, translatable strings will be automatically extracted to
  53 the .po files, if you make use of the following recommendations.
  54
  55 The intltool-prepare script will help you to prepare the package. It will
  56 try to extract translations from existing .desktop files which will
  57 become obsolete after intltoolization has taken place.
  58
  59 Examples of packages that use intltool are many of the GNOME components:
  60 find them at http://git.gnome.org/.
  61
  62 Details of the IT_PROG_INTLTOOL macro
  63 -------------------------------------------
  64
  65 The first parameter indicates the minimum required version. The
  66 configure script will halt if the version is older than the first
  67 parameter.
  68
  69 The second parameter is to tell intltool that we don't need the
  70 extended xml parsing abilities provided by the XML::Parser perl
  71 module. If it is not provided, or is any value other than "no-xml",
  72 then XML::Parser will be checked for by the configure script. This
  73 feature is only available in intltool 0.31 or newer.
  74
  75 Extra Steps for DESKTOP Files
  76 ..............................
  77
  78 This step also applies for similar files (.directory, .soundlist).
  79
  80  o Try to run intltool-prepare.
  81
  82  o Make sure intltool-prepare did find existing translations in the old
  83    .desktop files and did correctly merge them into the various po/*.po
  84    files.  Don't forget to commit the changed .po files; otherwise
  85    exiting translations will get lost!
  86
  87  o Remove old .desktop files and add new .desktop.in files.
  88
  89  o Adjust .cvsignore, .gitignore, .bzrignore or similar.
  90
  91  o Adjust Makefile.am, e.g.:
  92
  93         --- start ----
  94
  95         utilsdir = $(datadir)/gnome/apps/Utilities
  96         utils_in_files = bug-buddy.desktop.in
  97         utils_DATA = $(utils_in_files:.desktop.in=.desktop)
  98         @INTLTOOL_DESKTOP_RULE@
  99
 100         --- end ----
 101
 102  o Add .desktop.in files to po/POTFILES.in
 103
 104 Here's a .desktop.in example:
 105
 106         --- start ----
 107
 108         [Desktop Entry]
 109         _Name=Bug Report Tool
 110         _Comment=Report a bug in GNOME
 111         Exec=bug-buddy
 112         Icon=bug-buddy
 113         Terminal=false
 114         Type=Application
 115
 116         --- end ----
 117
 118
 119 Extra Steps for GLADE Files
 120 ...........................
 121
 122  o Add the .glade files you want translated to POTFILES.in
 123
 124  o Remove the intermediate *-glade.h or strings-glade.c files and drop
 125    them from POTFILES.in
 126
 127
 128 Extra Steps for SERVER Files (formerly .server)
 129 .............................
 130
 131 To get server translation extraction and merging requires a few more steps:
 132
 133  o Rename your .server files to .server.in and put an
 134    underscore before every value property for string attributes that should
 135    be localized.
 136
 137  o Add the new .server.in or .server.in files to POTFILES.in.
 138
 139  o Put lines like these in every Makefile.am that installs oaf files:
 140
 141         --- start ----
 142
 143         serverdir = $(libdir)/bonobo/servers
 144
 145         server_in_files = My_Server_file.server.in
 146         server_DATA = $(server_in_files:.server.in=.server)
 147
 148         @INTLTOOL_SERVER_RULE@
 149
 150         EXTRA_DIST=$(server_in_files) $(server_DATA)
 151
 152         --- end ----
 153
 154 At this point, your server translations will be extracted and merged.
 155
 156 Extra Steps for XML Files (Files with .xml Extension)
 157 .....................................................
 158
 159 To get xml (files with .xml extension) translation extraction
 160 and merging requires these steps:
 161
 162  o Rename your .xml files to .xml.in and put an underscore before
 163    every element that should be localized.
 164
 165  o Add the .xml.in files to POTFILES.in.
 166
 167  o Put lines like these in every Makefile.am that installs xml files:
 168
 169         --- start ----
 170
 171         xmldir = $(datadir)/xml
 172
 173         xml_in_files = My_xml_file.xml.in
 174         xml_DATA = $(xml_in_files:.xml.in=.xml)
 175
 176         @INTLTOOL_XML_RULE@
 177
 178         EXTRA_DIST=$(xml_in_files) $(xml_DATA)
 179
 180         --- end ----
 181
 182 At this point, your xml translations will be extracted and
 183 merged. All .po files will be converted on the fly to UTF-8, and the
 184 resulting XML file will have a UTF-8 effective encoding (you should
 185 make sure that the encoding="..." declaration in the .xml.in file is
 186 either absent or actually specifies UTF-8).
 187
 188 Previous versions of intltool generated XML files whose contents
 189 were made of the contents of the .po files, without paying attention
 190 to the encodings used. A single "XML" file could thus have strings in
 191 different encodings. This broken behavior can be requested only by
 192 using the old xml-i18n-tools API instead of the intltool one. See old
 193 versions of xml-i18n-tools for documentation on how the old API worked.
 194
 195 ---
 196
 197 XXX: add section for KEYS files. Works almost like XML files .
 198
 199 How to use without autoconf/automake
 200 ------------------------------------
 201
 202 intltool can also be used without the auto* tools. For instance in order
 203 to translate a somename.desktop.in file, you can do the following.
 204
 205  o Create a po/ dir.
 206  o Add a po/POTFILES.in file, including the path to the
 207    somename.desktop.in  file
 208
 209 Then to create the somename.desktop file all you do is:
 210
 211 $ intltool-merge po/ -d -u -c po/.intltool-merge-cache somename.desktop.in
 212 somename.desktop
 213
 214 You can also type intltool-merge --help for a bit more info.
 215
 216 To specify parameters for intltool-update (such as keywords or gettext
 217 domain), you can use Makevars syntax as used in recent GNU gettext, by
 218 putting something like the following in po/Makevars file:
 219
 220   DOMAIN = mydomain
 221   XGETTEXT_OPTIONS = --keyword --keyword=blah
 222
 223 This will make "intltool-update -p" produce mydomain.pot, passing
 224 parameters "--keyword --keyword=blah" to xgettext when extracting
 225 strings.
 226
 227 Passing special parameters to xgettext via environment
 228 ......................................................
 229
 230 If you need to add parameters passed to xgettext on a case-by-case
 231 basis, you can do so using environment variable XGETTEXT_ARGS.
 232
 233 If you would run it as follows:
 234
 235         XGETTEXT_ARGS=--no-location intltool-update -p
 236
 237 You would create a PO Template file without lines which indicate
 238 location of messages in the source code.
 239
 240
 241 Changing keywords used in xgettext invocation
 242 .............................................
 243
 244 If you need to change default keywords used to extract messages from
 245 source code, you need to add variable XGETTEXT_KEYWORDS to
 246 Makefile.in.in file inside directory where intltool-update is run
 247 from, eg.
 248
 249         --- start ----
 250
 251         XGETTEXT_KEYWORDS = --keyword --keyword=P_
 252
 253         --- end ----
 254
 255 Default keywords xgettext looks for if no XGETTEXT_KEYWORDS is defined
 256 are _, N_ and U_.
 257
 258
 259 Translators' comments in XML and .schemas files
 260 ...............................................
 261
 262 To provide comments to translators in free-form XML or .schema files,
 263 you need to precede the string to be translated with the plain XML
 264 comment.
 265
 266 In .schemas files, comments need to be inside <default>, <short> or
 267 <long> elements (i.e. they cannot be before the opening tag).