OCAML-GETTEXT(1)

✨ ocaml-gettext ✨

okay so bestie, you just opened the OCAML-GETTEXT(1) manual page and I am SO glad you're here 💖 this is the whole thing, top to bottom, nothing skipped, fr fr. grab a strawberry 🍓 and let's go.

🌸 NAME 🌸

ocaml-gettext — the program that manages PO and MO files for your OCaml source files. that's it, that's the vibe. 💅

🦋 SYNOPSIS 🦋

ocaml-gettext --action verb options* [file...]

💜 DESCRIPTION 💜

this page is the quick rundown of the ocaml-gettext command — the little overview, the appetiser, the teaser 🎀

now the actions, because this is where the main character energy lives:

• --action extract — the files you hand over get treated like OCaml source files, and ocaml-gettext tries to pull the translatable strings out of them. what you get back is a POT file. ✨ special-case alert ✨: if a file named POTFILES is in the list of files you provided, then every single line of it counts as a file to be searched. iconic behaviour honestly.
• --action compile — the files you give it are treated as PO files, and they get compiled into binary MO files.
• --action install — the files you give it are treated as MO files, and they get installed into their respective directories, taking language, textdomain and category into account.
• --action uninstall — the symmetric twin of install 🫶 it uninstalls the files you provided for the language, textdomain and category in question.
• --action merge — merges a POT file with the PO file you provided.

and now the options, one by one, no skipping, we stay thorough:

• --extract-command cmd — the command used to extract translatable strings from an OCaml source file. this command has to output the same marshalled structure as ocaml-xgettext. best practice? use the same build version of ocaml-gettext. no cap.
• --extract-default-option options — the default options used when extracting translatable strings. these are camlp4 options and they get passed to ocaml-xgettext when it's processing files that don't already have their own specific camlp4 options.
• --extract-filename-option filename options — specific per-filename camlp4 options. used when extracting strings from the specified filename. it overrides the default camlp4 options. 👑
• --extract-pot filename — the POT file to write when extracting translatable strings.
• --compile-output filename — the MO file to write when compiling a PO file. if you don't provide it, the output is just the name of the PO file with a .mo extension.
• --install-language language — the language to use when installing a MO file.
• --install-category category — the category to use when installing a MO file.
• --install-textdomain textdomain — the textdomain to use when installing a MO file.
• --install-destdir dirname — the base directory to use when installing a MO file.
• --uninstall-language language — the language to use when uninstalling a MO file.
• --uninstall-category category — the category to use when uninstalling a MO file.
• --uninstall-textdomain textdomain — the textdomain to use when uninstalling a MO file.
• --uninstall-orgdir dirname — the base directory used when uninstalling a MO file.
• --merge-pot filename — the POT file to use as a master for merging a PO file.
• --merge-backup-extension extension — the backup extension to use when moving PO files that have been merged.
• --version — returns version info about ocaml-gettext.
• --short-version — returns only the version of ocaml-gettext. the return is made to be easily parseable by a configure script. the output of this command will always be the shortest version string, made up of numeric characters (0-9) and ".". you should compare version strings knowing that a version A is greater than a version B if there is a number between two "." of A that is greater than the corresponding number of B, starting at the right of the string. for example: 0.14 is greater than 0.13.1. 🧠
• -help, --help — displays the help about the ocaml-gettext command.

🌈 OCAML-GETTEXT OPTIONS 🌈

this section briefly describes the common options provided by programs that use the ocaml-gettext library. okay bestie, here we go:

• --gettext-failsafe ignore — defines the behaviour of ocaml-gettext for any error that could be encountered while processing string translation. ignore is the default behaviour. the string returned is the original string, untranslated. this behaviour is consistent and lets you have usable output even if it isn't perfect. 💅
• --gettext-failsafe inform-stderr — same behaviour as ignore, except that a message is printed on stderr.
• --gettext-failsafe raise-exception — stops the program by raising an exception when an error is encountered. 🚨 dramatic, on purpose.
• --gettext-disable — disables any translation made by ocaml-gettext. all translations return the original string, untranslated.
• --gettext-domain-dir textdomain dir — defines a dir to search for a specific domain. this could be useful if MO files are stored in a non standard directory.
• --gettext-dir dir — adds a directory to search for MO files.
• --gettext-language language — sets the language to use in the ocaml-gettext library. the language should be POSIX compliant. it should follow this convention: lang[_territory][.charset][@modifier]. the lang and territory should be two letters ISO code. the charset should be a valid ISO character set (at least recognised by the underlying charset recoding routine). for example, valid languages are: fr_FR.ISO-8859-1@euro, de_DE.UTF-8.
• --gettext-codeset codeset — sets the codeset for output.

heads up bestie 🙈 you should be aware that these command line options apply only for strings after the initialisation of the library. this means that if the options initially guessed by ocaml-gettext don't match the command line you provided, there will probably be some untranslated string, because those strings are translated before options get parsed. this is particularly true for the usage message itself (--help): even if the strings are translated, they are translated before setting the correct option. yeah. it's giving chicken-and-egg.

some options (--gettext-codeset for example) are overridden internally for particular use. you should always translate strings to UTF-8 in a graphical user interface (because GTK2 requires it). 😭

🎀 NOTES 🎀

the options --uninstall-language, --uninstall-textdomain, --install-language and --install-textdomain could be guessed from the filename you provide. but listen — you must be aware that these options can conflict with the fact that you provide several files to install.

for example, if you provide a textdomain, you should either install several MO files whose filenames only reflect the language, or only one MO file if you also provide a language.

so like, you can totally run:

ocaml-gettext --install-textdomain mytextdomain fr.po de.po

without a problem ✨ but you cannot run:

ocaml-gettext --install-textdomain mytextdomain --install-language fr fr.po de.po

this restriction exists because you should not over-specify file installation. periodt.

the rules for guessing the language/textdomain are: language[.textdomain].mo. so for a fully automated install, without giving any hints through command line options, you should name your file fr.mytextdomain.mo or de.mytextdomain.mo. slay. 💅

👑 SEE ALSO 👑

ocaml-xgettext(1), ocaml-gettext(5).

💖 AUTHORS 💖

Sylvain Le Gall.

and that's a wrap, bestie 🦋 this was the OCAML-GETTEXT(1) page, dated 2008-04-29, and you ate the whole thing. go forth and translate. 💜🌸✨