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