From 1afdac1bc4cbf9816e7109bbedef2825c4fe1155 Mon Sep 17 00:00:00 2001 From: Charles Brunet Date: Thu, 7 Nov 2024 10:58:14 -0500 Subject: New xgettext method for i18n module This method call xgettext to extract translatable string from source files into a .pot translation template. It differs from a plain CustomTarget in three ways: - It accepts build targets as sources, and automatically resolves source files from those build targets; - It detects command lines that are too long, and writes, at config time, the list of source files into a text file to be consumed by the xgettext command; - It detects dependencies between pot extraction targets, based on the dependencies between source targets. --- docs/markdown/i18n-module.md | 47 +++++++++++++++++++++++++++++++++ docs/markdown/snippets/i18n_xgettext.md | 12 +++++++++ 2 files changed, 59 insertions(+) create mode 100644 docs/markdown/snippets/i18n_xgettext.md (limited to 'docs') diff --git a/docs/markdown/i18n-module.md b/docs/markdown/i18n-module.md index a939a3473..da6fce74e 100644 --- a/docs/markdown/i18n-module.md +++ b/docs/markdown/i18n-module.md @@ -74,3 +74,50 @@ for normal keywords. In addition it accepts these keywords: * `mo_targets` *required*: mo file generation targets as returned by `i18n.gettext()`. *Added 0.62.0* + + +### i18n.xgettext() + +``` meson +i18n.xgettext(name, sources..., args: [...], recursive: false) +``` + +Invokes the `xgettext` program on given sources, to generate a `.pot` file. +This function is to be used when the `gettext` function workflow it not suitable +for your project. For example, it can be used to produce separate `.pot` files +for each executable. + +Positional arguments are the following: + +* name `str`: the name of the resulting pot file. +* sources `list[str|File|build_tgt|custom_tgt]`: + source files or targets. May be a list of `string`, `File`, [[@build_tgt]], + or [[@custom_tgt]] returned from other calls to this function. + +Keyword arguments are the following: + +- recursive `bool`: + if `true`, will merge the resulting pot file with extracted pot files + related to dependencies of the given source targets. For instance, + if you build an executable, then you may want to merge the executable + translations with the translations from the dependent libraries. +- install `bool`: if `true`, will add the resulting pot file to install targets. +- install_tag `str`: install tag to use for the install target. +- install_dir `str`: directory where to install the resulting pot file. + +The `i18n.xgettext()` function returns a [[@custom_tgt]]. + +Usually, you want to pass one build target as sources, and the list of header files +for that target. If the number of source files would result in a command line that +is too long, the list of source files is written to a file at config time, to be +used as input for the `xgettext` program. + +The `recursive: true` argument is to be given to targets that will actually read +the resulting `.mo` file. Each time you call the `i18n.xgettext()` function, +it maps the source targets to the resulting pot file. When `recursive: true` is +given, all generated pot files from dependencies of the source targets are +included to generate the final pot file. Therefore, adding a dependency to +source target will automatically add the translations of that dependency to the +needed translations for that source target. + +*Added 1.8.0* diff --git a/docs/markdown/snippets/i18n_xgettext.md b/docs/markdown/snippets/i18n_xgettext.md new file mode 100644 index 000000000..0ad0a14b1 --- /dev/null +++ b/docs/markdown/snippets/i18n_xgettext.md @@ -0,0 +1,12 @@ +## i18n module xgettext + +There is a new `xgettext` function in `i18n` module that acts as a +wrapper around `xgettext`. It allows to extract strings to translate from +source files. + +This function is convenient, because: +- It can find the sources files from a build target; +- It will use an intermediate file when the number of source files is too + big to be handled directly from the command line; +- It is able to get strings to translate from the dependencies of the given + targets. -- cgit v1.2.3