POTOOL(1)

📦 version 0.19, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 POTOOL(1) 💖

okay bestie, sit down, we're learning potool — that's the program for manipulating gettext po files, and it lives in section 1 of the General Commands Manual. She's been around a while, she's iconic, and she's about to make your .po files behave. 🎀

✨ NAME ✨

potool — the program for manipulating gettext po files. that's it, that's the whole job description, and she does it beautifully. 💅

🌸 SYNOPSIS 🌸

potool FILENAME1 [ FILENAME2 ] [-f f|nf|t|nt|nth|o|no] [-n
ctxt|id|str|cmt|ucmt|pcmt|scmt|dcmt|tr|linf]...  [-s] [-p] [-c]

potool -h

one file = filter mode, two files = swap mode, and -h when you're lost. 🦋

💫 DESCRIPTION 💫

so potool works in two (so far) modes and honestly? she serves in both.

Mode one needs just one file name and she works as a filter. lowkey the simplest thing ever, she just reads and outputs.

Mode two is the glow-up: the program replaces the translations in FILENAME1 with the translations from FILENAME2. so like — FILENAME1 is the base po file, while FILENAME2 is our working copy. base gets updated, working copy does the talking. periodt. 👑

🎀 OPTIONS 🎀

  • -f filter — decides which po file entries get retained. in mode two, filters are applied only to FILENAME2 (the working copy, remember her). existing filters are:
    • t — translated entries ✨
    • nt — untranslated entries 🙈
    • nth — untranslated entries and the header
    • f — fuzzy entries 🫠
    • nf — entries that are not fuzzy
    • o — obsolete entries 💀
    • no — non-obsolete entries

and yes bestie, you can stack filters by specifying multiple -f options. go off. 🔥

  • -n filter — decides which po file entry parts should not be retained. any number of -n options is allowed (she's flexible like that 💅). valid parameters are:
    • ctxt — don't write ctxt parts
    • id — don't write id parts
    • str — don't write str parts
    • tr — don't write translations
    • ucmt — don't write user's comments
    • pcmt — don't write the comments regarding position in source files
    • scmt — don't write special comments ('#, fuzzy, c-format, ...')
    • dcmt — don't write reserved comments (usually starting with a dot)
    • cmt — don't write any comments
    • linf — change source line numbers to '1'.
the last parameter is so useful when you need to compare two po or pot files using diff(1), because otherwise it usually returns lots of unimportant line number changes and you're just sitting there like 😭
  • -s — don't display the entries themselves, only their count. she's just giving you the numbers, no yapping. 🔢
  • -p — causes potool to keep the formatting of the file intact. without this option, all strings will be re-wrapped in the output at newlines or word boundaries to fit in 80 columns. no cap.
  • -c — overwrite all msgstrs with their msgids. wild but okay 💅
  • -h — display short usage help. the "bestie I'm lost" button 🫶

🌈 EXAMPLES 🌈

count the translated entries:

potool x.po -s -ft

displays the number of translated entries. see also postats(1). 💖

delete everything and start fresh:

potool x.po -nstr

deletes all translations — so you can start from scratch! :-) iconic honestly.

translated first, then untranslated:

potool x.po -ft && potool x.po -fnt

displays firstly the translated and then the non-translated entries from file x.po (reverse order is not recommended because of the first "header" entry). the output contains all information from x.po, with the difference that untranslated entries are located together in a single place. organized queen. 🎀

edit only the untranslated ones:

potool x.po -fnt > tmp.po && editor tmp.po && potool x.po tmp.po

lets you easily add new translations, without looking at the already translated entries. chef's kiss. 😌

the last two examples are implemented as the potooledit(1) program. ✨

🦋 CAVEATS 🦋

by default, the program re-wraps lines in all strings in the output. see the -p option. not a drill, bestie, she will reformat your strings and she will not apologize. 😭

👑 SEE ALSO 👑

potooledit(1), postats(1), msgmerge(1), msgfmt(1). go read them, they're all part of the family. 💜

💜 AUTHOR 💜

Potool was written by Zbigniew Chyla and is now being maintained by Marcin Owsiany <porridge@debian.org>. legends, both of them. 🫶

and that's the whole page, bestie!! this was the POTOOL(1) man page, dated September 15, 2012, and if you made it this far you're genuinely so valid. go filter some po files. slay. 💅✨🌸

📦 where this page comes from