Debian Codegraph @

subprojects/meson-docs/docs/markdown/i18n-module.md

raw
1 # I18n module
2
3 This module provides internationalisation and localisation functionality.
4
5 ## Usage
6
7 To use this module, just do: **`i18n = import('i18n')`**. The
8 following functions will then be available as methods on the object
9 with the name `i18n`. You can, of course, replace the name `i18n` with
10 anything else.
11
12 ### i18n.gettext()
13
14 Sets up gettext localisation so that translations are built and placed
15 into their proper locations during install. Takes one positional
16 argument which is the name of the gettext module.
17
18 * `args`: list of extra arguments to pass to `xgettext` when
19 generating the pot file
20 * `data_dirs`: (*Added 0.36.0*) list of directories to be set for
21 `GETTEXTDATADIRS` env var (Requires gettext 0.19.8+), used for local
22 its files
23 * `languages`: list of languages that are to be generated. As of
24 0.37.0 this is optional and the
25 [LINGUAS](https://www.gnu.org/software/gettext/manual/html_node/po_002fLINGUAS.html)
26 file is read.
27 * `preset`: (*Added 0.37.0*) name of a preset list of arguments,
28 current option is `'glib'`, see
29 [source](https://github.com/mesonbuild/meson/blob/master/mesonbuild/modules/i18n.py)
30 for their value
31 * `install`: (*Added 0.43.0*) if false, do not install the built translations.
32 * `install_dir`: (*Added 0.50.0*) override default install location, default is `localedir`
33
34 This function also defines targets for maintainers to use:
35 **Note**: These output to the source directory
36
37 * `<project_id>-pot`: runs `xgettext` to regenerate the pot file
38 * `<project_id>-update-po`: regenerates the `.po` files from current `.pot` file
39 * `<project_id>-gmo`: builds the translations without installing
40
41 (*since 0.60.0*) Returns a list containing:
42 * a list of built `.mo` files
43 * the maintainer `-pot` target
44 * the maintainer `-update-po` target
45
46 ### i18n.merge_file()
47
48 This merges translations into a text file using `msgfmt`. See
49 [[custom_target]]
50 for normal keywords. In addition it accepts these keywords:
51
52 * `output`: same as `custom_target` but only accepts one item
53 * `install_dir`: same as `custom_target` but only accepts one item
54 * `install_tag`: same as `custom_target` but only accepts one item
55 * `data_dirs`: (*Added 0.41.0*) list of directories for its files (See
56 also `i18n.gettext()`)
57 * `po_dir`: directory containing translations, relative to current directory
58 * `type`: type of file, valid options are `'xml'` (default) and `'desktop'`
59 * `args`: (*Added 0.51.0*) list of extra arguments to pass to `msgfmt`
60
61 *Added 0.37.0*
62
63 ### i18n.itstool_join()
64
65 This joins translations into a XML file using `itstool`. See
66 [[custom_target]]
67 for normal keywords. In addition it accepts these keywords:
68
69 * `output`: same as `custom_target` but only accepts one item
70 * `install_dir`: same as `custom_target` but only accepts one item
71 * `install_tag`: same as `custom_target` but only accepts one item
72 * `its_files`: filenames of ITS files that should be used explicitly
73 (XML translation rules are autodetected otherwise).
74 * `mo_targets` *required*: mo file generation targets as returned by `i18n.gettext()`.
75
76 *Added 0.62.0*