gettext: gettextize Invocation
1
1 13.3 Invoking the ‘gettextize’ Program
1 ======================================
1
1 The ‘gettextize’ program is an interactive tool that helps the
1 maintainer of a package internationalized through GNU ‘gettext’. It is
1 used for two purposes:
1
1 • As a wizard, when a package is modified to use GNU ‘gettext’ for
1 the first time.
1
1 • As a migration tool, for upgrading the GNU ‘gettext’ support in a
1 package from a previous to a newer version of GNU ‘gettext’.
1
1 This program performs the following tasks:
1
1 • It copies into the package some files that are consistently and
1 identically needed in every package internationalized through GNU
1 ‘gettext’.
1
1 • It performs as many of the tasks mentioned in the next section
1 ⇒Adjusting Files as can be performed automatically.
1
1 • It removes obsolete files and idioms used for previous GNU
1 ‘gettext’ versions to the form recommended for the current GNU
1 ‘gettext’ version.
1
1 • It prints a summary of the tasks that ought to be done manually and
1 could not be done automatically by ‘gettextize’.
1
1 It can be invoked as follows:
1
1 gettextize [ OPTION… ] [ DIRECTORY ]
1
1 and accepts the following options:
1
1 ‘-f’
1 ‘--force’
1 Force replacement of files which already exist.
1
1 ‘--intl’
1 Install the libintl sources in a subdirectory named ‘intl/’. This
1 libintl will be used to provide internationalization on systems
1 that don’t have GNU libintl installed. If this option is omitted,
1 the call to ‘AM_GNU_GETTEXT’ in ‘configure.ac’ should read:
1 ‘AM_GNU_GETTEXT([external])’, and internationalization will not be
1 enabled on systems lacking GNU gettext.
1
1 ‘--po-dir=DIR’
1 Specify a directory containing PO files. Such a directory contains
1 the translations into various languages of a particular POT file.
1 This option can be specified multiple times, once for each
1 translation domain. If it is not specified, the directory named
1 ‘po/’ is updated.
1
1 ‘--no-changelog’
1 Don’t update or create ChangeLog files. By default, ‘gettextize’
1 logs all changes (file additions, modifications and removals) in a
1 file called ‘ChangeLog’ in each affected directory.
1
1 ‘--symlink’
1 Make symbolic links instead of copying the needed files. This can
1 be useful to save a few kilobytes of disk space, but it requires
1 extra effort to create self-contained tarballs, it may disturb some
1 mechanism the maintainer applies to the sources, and it is likely
1 to introduce bugs when a newer version of ‘gettext’ is installed on
1 the system.
1
1 ‘-n’
1 ‘--dry-run’
1 Print modifications but don’t perform them. All actions that
1 ‘gettextize’ would normally execute are inhibited and instead only
1 listed on standard output.
1
1 ‘--help’
1 Display this help and exit.
1
1 ‘--version’
1 Output version information and exit.
1
1 If DIRECTORY is given, this is the top level directory of a package
1 to prepare for using GNU ‘gettext’. If not given, it is assumed that
1 the current directory is the top level directory of such a package.
1
1 The program ‘gettextize’ provides the following files. However, no
1 existing file will be replaced unless the option ‘--force’ (‘-f’) is
1 specified.
1
1 1. The ‘ABOUT-NLS’ file is copied in the main directory of your
1 package, the one being at the top level. This file gives the main
1 indications about how to install and use the Native Language
1 Support features of your program. You might elect to use a more
1 recent copy of this ‘ABOUT-NLS’ file than the one provided through
1 ‘gettextize’, if you have one handy. You may also fetch a more
1 recent copy of file ‘ABOUT-NLS’ from Translation Project sites, and
1 from most GNU archive sites.
1
1 2. A ‘po/’ directory is created for eventually holding all translation
1 files, but initially only containing the file ‘po/Makefile.in.in’
1 from the GNU ‘gettext’ distribution (beware the double ‘.in’ in the
1 file name) and a few auxiliary files. If the ‘po/’ directory
1 already exists, it will be preserved along with the files it
1 contains, and only ‘Makefile.in.in’ and the auxiliary files will be
1 overwritten.
1
1 If ‘--po-dir’ has been specified, this holds for every directory
1 specified through ‘--po-dir’, instead of ‘po/’.
1
1 3. Only if ‘--intl’ has been specified: A ‘intl/’ directory is created
1 and filled with most of the files originally in the ‘intl/’
1 directory of the GNU ‘gettext’ distribution. Also, if option
1 ‘--force’ (‘-f’) is given, the ‘intl/’ directory is emptied first.
1
1 4. The file ‘config.rpath’ is copied into the directory containing
1 configuration support files. It is needed by the ‘AM_GNU_GETTEXT’
1 autoconf macro.
1
1 5. Only if the project is using GNU ‘automake’: A set of ‘autoconf’
1 macro files is copied into the package’s ‘autoconf’ macro
1 repository, usually in a directory called ‘m4/’.
1
1 If your site support symbolic links, ‘gettextize’ will not actually
1 copy the files into your package, but establish symbolic links instead.
1 This avoids duplicating the disk space needed in all packages. Merely
1 using the ‘-h’ option while creating the ‘tar’ archive of your
1 distribution will resolve each link by an actual copy in the
1 distribution archive. So, to insist, you really should use ‘-h’ option
1 with ‘tar’ within your ‘dist’ goal of your main ‘Makefile.in’.
1
1 Furthermore, ‘gettextize’ will update all ‘Makefile.am’ files in each
1 affected directory, as well as the top level ‘configure.ac’ or
1 ‘configure.in’ file.
1
1 It is interesting to understand that most new files for supporting
1 GNU ‘gettext’ facilities in one package go in ‘intl/’, ‘po/’ and ‘m4/’
1 subdirectories. One distinction between ‘intl/’ and the two other
1 directories is that ‘intl/’ is meant to be completely identical in all
1 packages using GNU ‘gettext’, while the other directories will mostly
1 contain package dependent files.
1
1 The ‘gettextize’ program makes backup files for all files it replaces
1 or changes, and also write ChangeLog entries about these changes. This
1 way, the careful maintainer can check after running ‘gettextize’ whether
1 its changes are acceptable to him, and possibly adjust them. An
1 exception to this rule is the ‘intl/’ directory, which is added or
1 replaced or removed as a whole.
1
1 It is important to understand that ‘gettextize’ can not do the entire
1 job of adapting a package for using GNU ‘gettext’. The amount of
1 remaining work depends on whether the package uses GNU ‘automake’ or
1 not. But in any case, the maintainer should still read the section
1 ⇒Adjusting Files after invoking ‘gettextize’.
1
1 In particular, if after using ‘gettexize’, you get an error
1 ‘AC_COMPILE_IFELSE was called before AC_GNU_SOURCE’ or ‘AC_RUN_IFELSE
1 was called before AC_GNU_SOURCE’, you can fix it by modifying
1 ‘configure.ac’, as described in ⇒configure.ac.
1
1 It is also important to understand that ‘gettextize’ is not part of
1 the GNU build system, in the sense that it should not be invoked
1 automatically, and not be invoked by someone who doesn’t assume the
1 responsibilities of a package maintainer. For the latter purpose, a
1 separate tool is provided, see ⇒autopoint Invocation.
1