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.ac} should read: 58@samp{AM_GNU_GETTEXT([external])}, and internationalization will not 59be enabled on systems lacking GNU gettext. 60 61@item --po-dir=@var{dir} 62@opindex --po-dir@r{, @code{gettextize} option} 63Specify a directory containing PO files. Such a directory contains the 64translations into various languages of a particular POT file. This 65option can be specified multiple times, once for each translation domain. 66If it is not specified, the directory named @file{po/} is updated. 67 68@item --no-changelog 69@opindex --no-changelog@r{, @code{gettextize} option} 70Don't update or create ChangeLog files. By default, @code{gettextize} 71logs all changes (file additions, modifications and removals) in a 72file called @samp{ChangeLog} in each affected directory. 73 74@item --symlink 75@opindex --symlink@r{, @code{gettextize} option} 76Make symbolic links instead of copying the needed files. This can be 77useful to save a few kilobytes of disk space, but it requires extra 78effort to create self-contained tarballs, it may disturb some mechanism 79the maintainer applies to the sources, and it is likely to introduce 80bugs when a newer version of @code{gettext} is installed on the system. 81 82@item -n 83@itemx --dry-run 84@opindex -d@r{, @code{gettextize} option} 85@opindex --dry-run@r{, @code{gettextize} option} 86Print modifications but don't perform them. All actions that 87@code{gettextize} would normally execute are inhibited and instead only 88listed on standard output. 89 90@item --help 91@opindex --help@r{, @code{gettextize} option} 92Display this help and exit. 93 94@item --version 95@opindex --version@r{, @code{gettextize} option} 96Output version information and exit. 97 98@end table 99 100If @var{directory} is given, this is the top level directory of a 101package to prepare for using GNU @code{gettext}. If not given, it 102is assumed that the current directory is the top level directory of 103such a package. 104 105The program @code{gettextize} provides the following files. However, 106no existing file will be replaced unless the option @code{--force} 107(@code{-f}) is specified. 108 109@enumerate 110@item 111The @file{ABOUT-NLS} file is copied in the main directory of your package, 112the one being at the top level. This file gives the main indications 113about how to install and use the Native Language Support features 114of your program. You might elect to use a more recent copy of this 115@file{ABOUT-NLS} file than the one provided through @code{gettextize}, 116if you have one handy. You may also fetch a more recent copy of file 117@file{ABOUT-NLS} from Translation Project sites, and from most GNU 118archive sites. 119 120@item 121A @file{po/} directory is created for eventually holding 122all translation files, but initially only containing the file 123@file{po/Makefile.in.in} from the GNU @code{gettext} distribution 124(beware the double @samp{.in} in the file name) and a few auxiliary 125files. If the @file{po/} directory already exists, it will be preserved 126along with the files it contains, and only @file{Makefile.in.in} and 127the auxiliary files will be overwritten. 128 129If @samp{--po-dir} has been specified, this holds for every directory 130specified through @samp{--po-dir}, instead of @file{po/}. 131 132@item 133Only if @samp{--intl} has been specified: 134A @file{intl/} directory is created and filled with most of the files 135originally in the @file{intl/} directory of the GNU @code{gettext} 136distribution. Also, if option @code{--force} (@code{-f}) is given, 137the @file{intl/} directory is emptied first. 138 139@item 140The file @file{config.rpath} is copied into the directory containing 141configuration support files. It is needed by the @code{AM_GNU_GETTEXT} 142autoconf macro. 143 144@item 145Only if the project is using GNU @code{automake}: 146A set of @code{autoconf} macro files is copied into the package's 147@code{autoconf} macro repository, usually in a directory called @file{m4/}. 148@end enumerate 149 150If your site support symbolic links, @code{gettextize} will not 151actually copy the files into your package, but establish symbolic 152links instead. This avoids duplicating the disk space needed in 153all packages. Merely using the @samp{-h} option while creating the 154@code{tar} archive of your distribution will resolve each link by an 155actual copy in the distribution archive. So, to insist, you really 156should use @samp{-h} option with @code{tar} within your @code{dist} 157goal of your main @file{Makefile.in}. 158 159Furthermore, @code{gettextize} will update all @file{Makefile.am} files 160in each affected directory, as well as the top level @file{configure.ac} 161or @file{configure.in} file. 162 163It is interesting to understand that most new files for supporting 164GNU @code{gettext} facilities in one package go in @file{intl/}, 165@file{po/} and @file{m4/} subdirectories. One distinction between 166@file{intl/} and the two other directories is that @file{intl/} is 167meant to be completely identical in all packages using GNU @code{gettext}, 168while the other directories will mostly contain package dependent 169files. 170 171The @code{gettextize} program makes backup files for all files it 172replaces or changes, and also write ChangeLog entries about these 173changes. This way, the careful maintainer can check after running 174@code{gettextize} whether its changes are acceptable to him, and 175possibly adjust them. An exception to this rule is the @file{intl/} 176directory, which is added or replaced or removed as a whole. 177 178It is important to understand that @code{gettextize} can not do the 179entire job of adapting a package for using GNU @code{gettext}. The 180amount of remaining work depends on whether the package uses GNU 181@code{automake} or not. But in any case, the maintainer should still 182read the section @ref{Adjusting Files} after invoking @code{gettextize}. 183 184In particular, if after using @samp{gettexize}, you get an error 185@samp{AC_COMPILE_IFELSE was called before AC_GNU_SOURCE} or 186@samp{AC_RUN_IFELSE was called before AC_GNU_SOURCE}, you can fix it 187by modifying @file{configure.ac}, as described in @ref{configure.ac}. 188 189It is also important to understand that @code{gettextize} is not part 190of the GNU build system, in the sense that it should not be invoked 191automatically, and not be invoked by someone who doesn't assume the 192responsibilities of a package maintainer. For the latter purpose, a 193separate tool is provided, see @ref{autopoint Invocation}. 194