1The @code{gettextize} program is an interactive tool that helps the 2maintainer of a package internationalized through GNU @code{gettext}. 3It is used for two purposes: 4 5@itemize @bullet 6@item 7As a wizard, when a package is modified to use GNU @code{gettext} for 8the first time. 9 10@item 11As a migration tool, for upgrading the GNU @code{gettext} support in 12a package from a previous to a newer version of GNU @code{gettext}. 13@end itemize 14 15This program performs the following tasks: 16 17@itemize @bullet 18@item 19It copies into the package some files that are consistently and 20identically needed in every package internationalized through 21GNU @code{gettext}. 22 23@item It performs as many of the tasks mentioned in the next section 24@ref{Adjusting Files} as can be performed automatically. 25 26@item It removes obsolete files and idioms used for previous GNU 27@code{gettext} versions to the form recommended for the current GNU 28@code{gettext} version. 29 30@item It prints a summary of the tasks that ought to be done manually 31and could not be done automatically by @code{gettextize}. 32@end itemize 33 34It can be invoked as follows: 35 36@pindex gettextize 37@cindex @code{gettextize} program, usage 38@example 39gettextize [ @var{option}@dots{} ] [ @var{directory} ] 40@end example 41 42@noindent 43and accepts the following options: 44 45@table @samp 46@item -f 47@itemx --force 48@opindex -f@r{, @code{gettextize} option} 49@opindex --force@r{, @code{gettextize} option} 50Force replacement of files which already exist. 51 52@item --intl 53@opindex --intl@r{, @code{gettextize} option} 54Install the libintl sources in a subdirectory named @file{intl/}. 55This libintl will be used to provide internationalization on systems 56that don't have GNU libintl installed. If this option is omitted, 57the call to @code{AM_GNU_GETTEXT} in @file{configure.in} should read: 58@samp{AM_GNU_GETTEXT([external])}, and internationalization will not 59be enabled on systems lacking GNU gettext. 60 61@item --no-changelog 62@opindex --no-changelog@r{, @code{gettextize} option} 63Don't update or create ChangeLog files. By default, @code{gettextize} 64logs all changes (file additions, modifications and removals) in a 65file called @samp{ChangeLog} in each affected directory. 66 67@item --symlink 68@opindex --symlink@r{, @code{gettextize} option} 69Make symbolic links instead of copying the needed files. This can be 70useful to save a few kilobytes of disk space, but it requires extra 71effort to create self-contained tarballs, it may disturb some mechanism 72the maintainer applies to the sources, and it is likely to introduce 73bugs when a newer version of @code{gettext} is installed on the system. 74 75@item -n 76@itemx --dry-run 77@opindex -d@r{, @code{gettextize} option} 78@opindex --dry-run@r{, @code{gettextize} option} 79Print modifications but don't perform them. All actions that 80@code{gettextize} would normally execute are inhibited and instead only 81listed on standard output. 82 83@item --help 84@opindex --help@r{, @code{gettextize} option} 85Display this help and exit. 86 87@item --version 88@opindex --version@r{, @code{gettextize} option} 89Output version information and exit. 90 91@end table 92 93If @var{directory} is given, this is the top level directory of a 94package to prepare for using GNU @code{gettext}. If not given, it 95is assumed that the current directory is the top level directory of 96such a package. 97 98The program @code{gettextize} provides the following files. However, 99no existing file will be replaced unless the option @code{--force} 100(@code{-f}) is specified. 101 102@enumerate 103@item 104The @file{ABOUT-NLS} file is copied in the main directory of your package, 105the one being at the top level. This file gives the main indications 106about how to install and use the Native Language Support features 107of your program. You might elect to use a more recent copy of this 108@file{ABOUT-NLS} file than the one provided through @code{gettextize}, 109if you have one handy. You may also fetch a more recent copy of file 110@file{ABOUT-NLS} from Translation Project sites, and from most GNU 111archive sites. 112 113@item 114A @file{po/} directory is created for eventually holding 115all translation files, but initially only containing the file 116@file{po/Makefile.in.in} from the GNU @code{gettext} distribution 117(beware the double @samp{.in} in the file name) and a few auxiliary 118files. If the @file{po/} directory already exists, it will be preserved 119along with the files it contains, and only @file{Makefile.in.in} and 120the auxiliary files will be overwritten. 121 122@item 123Only if @samp{--intl} has been specified: 124A @file{intl/} directory is created and filled with most of the files 125originally in the @file{intl/} directory of the GNU @code{gettext} 126distribution. Also, if option @code{--force} (@code{-f}) is given, 127the @file{intl/} directory is emptied first. 128 129@item 130The file @file{config.rpath} is copied into the directory containing 131configuration support files. It is needed by the @code{AM_GNU_GETTEXT} 132autoconf macro. 133 134@item 135Only if the project is using GNU @code{automake}: 136A set of @code{autoconf} macro files is copied into the package's 137@code{autoconf} macro repository, usually in a directory called @file{m4/}. 138@end enumerate 139 140If your site support symbolic links, @code{gettextize} will not 141actually copy the files into your package, but establish symbolic 142links instead. This avoids duplicating the disk space needed in 143all packages. Merely using the @samp{-h} option while creating the 144@code{tar} archive of your distribution will resolve each link by an 145actual copy in the distribution archive. So, to insist, you really 146should use @samp{-h} option with @code{tar} within your @code{dist} 147goal of your main @file{Makefile.in}. 148 149Furthermore, @code{gettextize} will update all @file{Makefile.am} files 150in each affected directory, as well as the top level @file{configure.in} 151or @file{configure.ac} file. 152 153It is interesting to understand that most new files for supporting 154GNU @code{gettext} facilities in one package go in @file{intl/}, 155@file{po/} and @file{m4/} subdirectories. One distinction between 156@file{intl/} and the two other directories is that @file{intl/} is 157meant to be completely identical in all packages using GNU @code{gettext}, 158while the other directories will mostly contain package dependent 159files. 160 161The @code{gettextize} program makes backup files for all files it 162replaces or changes, and also write ChangeLog entries about these 163changes. This way, the careful maintainer can check after running 164@code{gettextize} whether its changes are acceptable to him, and 165possibly adjust them. An exception to this rule is the @file{intl/} 166directory, which is added or replaced or removed as a whole. 167 168It is important to understand that @code{gettextize} can not do the 169entire job of adapting a package for using GNU @code{gettext}. The 170amount of remaining work depends on whether the package uses GNU 171@code{automake} or not. But in any case, the maintainer should still 172read the section @ref{Adjusting Files} after invoking @code{gettextize}. 173 174In particular, if after using @samp{gettexize}, you get an error 175@samp{AC_COMPILE_IFELSE was called before AC_GNU_SOURCE} or 176@samp{AC_RUN_IFELSE was called before AC_GNU_SOURCE}, you can fix it 177by modifying @file{configure.ac}, as described in @ref{configure.in}. 178 179It is also important to understand that @code{gettextize} is not part 180of the GNU build system, in the sense that it should not be invoked 181automatically, and not be invoked by someone who doesn't assume the 182responsibilities of a package maintainer. For the latter purpose, a 183separate tool is provided, see @ref{autopoint Invocation}. 184