XGETTEXT(1)

📦
version 1.00 · 6 versions
, in fedora 43

💖 xgettext.pl — bestie, it's the man page 💖

okay so this is xgettext.pl, and it lives in the User Contributed Perl Documentation section of your man pages. we're gonna go through the whole thing together, no skips, no skimming, we eat every option. 🍓

✨ NAME ✨

xgettext.pl — extract translatable strings from source. that's it, that's the whole job, and it does it beautifully. 💅

🌸 VERSION 🌸

version 1.00 ✨

🦋 SYNOPSIS 🦋

xgettext.pl [OPTION] [INPUTFILE]...

that's the vibe. options, then files. periodt. 💜

🎀 DESCRIPTION 🎀

so this program extracts translatable strings from the input files you give it. and if you give it none? it just reads from STDIN instead. no big deal, it's flexible like that. 😌

also bestie, if you wanna know which input file formats are even supported, go read Locale::Maketext::Extract — that's where the list lives. 🫶

✨ OPTIONS ✨

heads up before we dive in: mandatory arguments to long options are mandatory for short options too. and same energy for optional arguments — optional stays optional on both. iykyk. 💅

🗂️ Input file location

  • INPUTFILE... — the files you want messages extracted from. if you don't name any, STDIN gets the job. 💖
  • -f, --files-from=FILE — get your list of input files from FILE instead of typing them all out like a peasant. 👑
  • -D, --directory=DIRECTORY — add DIRECTORY to the list of places it searches for input files. 🔍

📄 Input file format

  • -u, --use-gettext-style — tells it that your source code uses the Gettext style (like %1) in its localization calls instead of the Maketext style (like "[_1]"). pick your fighter, bestie. 🌈

📁 Output file location

  • -d, --default-domain=NAME — use NAME.po as the output file instead of "messages.po". cute name, cute file. 🎀
  • -o, --output=FILE — the PO file name to be written or incrementally updated. and if you pass "-"? it writes to STDOUT instead. iconic behavior honestly. 💅
  • -p, --output-dir=DIR — output files get placed in directory DIR. put them away, put them away. 🧺

🎁 Output details

  • -g, --gnu-gettext — enables GNU gettext interoperability by printing #, perl-maketext-format before each entry that has "%" variables. look at it being a good neighbor. 🤝
  • -W, --wrap — when wrap is enabled, entries with multiple file locations list each location on its own separate line. default behavior is to cram them all onto a single line. other comments are not affected by this, fyi. 🙈

🔌 Plugins

okay so by default, all builtin parser plugins are enabled for all file types, and warnings are turned off. comfy.

but the second you specify any plugin on the command line, warnings flip to on by default — and you can turn them back off with "-now". the way it just switches up on you 😭

  • -P|--plugin pluginname — use the specified plugin for the default file types that plugin recognises.
  • -P|--plugin 'pluginname=*' — use the specified plugin for all file types.
  • -P|--plugin pluginname=ext,ext2 — use the specified plugin for any files ending in C<.ext> or C<.ext2>
  • -P|--plugin My::Module::Name='*' — use your custom plugin module for all file types. main character energy, we love a custom module. 👑

multiple plugins can be specified on the command line, so stack them, bestie. 🥞

💫 Available plugins:

  • "perl" : Locale::Maketext::Extract::Plugin::Perl

for a slightly more accurate but much slower Perl parser, you can use the PPI plugin. it does not have a short name, so you have to specify it in full, eg:

xgettext.pl -P Locale::Maketext::Extract::Plugin::PPI
  • "tt2" : Locale::Maketext::Extract::Plugin::TT2
  • "yaml" : Locale::Maketext::Extract::Plugin::YAML
  • "formfu" : Locale::Maketext::Extract::Plugin::FormFu
  • "mason" : Locale::Maketext::Extract::Plugin::Mason
  • "text" : Locale::Maketext::Extract::Plugin::TextTemplate
  • "generic" : Locale::Maketext::Extract::Plugin::Generic

⚠️ Warnings

if a parser plugin hits a syntax error while parsing, it will abort parsing and hand over to the next parser plugin. and if warnings are turned on, that error gets echoed to STDERR. 😭

off by default — unless any plugin has been specified on the command line. sneaky but fair.

  • -w|--warnings
  • -now|--nowarnings

🗣️ Verbose

if you'd like to see which files have been processed, which plugins were used, and which strings were extracted, then enable "verbose". and note: if no acceptable plugin was found, or no strings were extracted, then that file is not listed. rude but honest. 💀

  • -v|--verbose — lists processed files.
  • -v -v|--verbose --verbose : — lists processed files and which plugins managed to extract strings.
  • -v -v|--verbose --verbose : — lists processed files, which plugins managed to extract strings, and the extracted strings, the line where they were found, and any variables. maximum tea, we're getting everything ☕✨

👀 SEE ALSO 👀

  • Locale::Maketext::Extract
  • Locale::Maketext::Lexicon::Gettext
  • Locale::Maketext
  • Locale::Maketext::Extract::Plugin::Perl
  • Locale::Maketext::Extract::Plugin::PPI
  • Locale::Maketext::Extract::Plugin::TT2
  • Locale::Maketext::Extract::Plugin::YAML
  • Locale::Maketext::Extract::Plugin::FormFu
  • Locale::Maketext::Extract::Plugin::Mason
  • Locale::Maketext::Extract::Plugin::TextTemplate
  • Locale::Maketext::Extract::Plugin::Generic

go read them, bestie, they're all in the family 🫶

💜 AUTHORS 💜

Audrey Tang <cpan@audreyt.org> 🎀

Copyright 2002-2008 by Audrey Tang <cpan@audreyt.org>.

This software is released under the MIT license cited below.

🧾 The "MIT" License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

💖 AUTHORS 💖

  • Clinton Gormley <drtech@cpan.org>
  • Audrey Tang <cpan@audreyt.org>

This software is Copyright (c) 2014 by Audrey Tang.

This is free software, licensed under:

The MIT (X11) License

and that's the whole page, bestie!! 🎉 written for perl v5.42.0 and dated 2025-07-25 — yeah, that's the version and the date, and this page is literally called XGETTEXT(1), we've been through all of it together. slay. 💅✨🦋

📦 where this page comes from