Supporting tools for https://github.com/gflohr/esgettext.
The package also contains code for parsing po files and for writing them.
- Prerequisites
- Installation
- The Tools
- Configuration
- Copyright
Most of the esgettext tools depend at least indirectly on the GNU gettext
tools. If the command xgettext --version outputs some kind of version
information, you are most probably set. Otherwise check the information for
your platform below.
Use the package manager of your vendor to search for something like "gettext-tools" or just "gettext" and install it. The gettext tools are available for every Unix or Linux flavor.
You either need MacPorts or HomeBrew.
$ sudo port install gettext$ brew install gettextThe options that I know of are
See their documentation for more information.
If you have better information, please file an issue or improve the documentation with a pull request.
You don't have to install the esgettext tools globally but if you are lazy, just do it. For npm you go with:
$ sudo npm install --global @esgettext/toolsFor Yarn, you would do this:
$ sudo yarn global add @esgettext/toolsNormally, it is better to install them just locally:
$ npm install --save-dev @esgettext/toolsor for yarn:
$ yarn add --dev @esgettext/toolsThe tools are really just one tool esgettext that supports several
commands.
In the following, it is assumed that you have installed the tools locally.
If you have installed them globally, just omit the leading npx.
Try this for an overview:
$ npm install --save-deve @esgettext/tools
$ npx esgettext --helpThe command npx esgetext xgettext extracts translatable strings from your source
files into .po resp. .pot files.
You can use npx esgettext extract as an alias for npx esgettext xgettext.
See the detailed esgettext-xgettext usage information for more details.
All other commands should be understandable by their help output. Try
npx esgettext --help for an overview over all commands, and
npx esgettext COMMAND --help for help for a specific command.
Instead of passing options on the command line, you can add a lot of defaults
in a configuration file or just in package.json.
Configuration files are checked in this order:
- esgettext.config.mjs
- esgettext.config.cjs
- esgettext.config.js
- esgettext.config.json
- package.json
The JavaScript versions should have one default export with the configuration.
The JSON version just defines the configuration. Alteratively, you can add
a field "esgettext" to your package.json.
You should always configure po.locales with a list of locale identifiers that
your package supports. Otherwise, using esgettext does not make sense.
You should also set package.textdomain unless you are happy with the
default which is just your package name read from package.json.
All other configuration values have sane defaults.
The required format is always the same. Note that the configuration gets validated against a schema. All tools will fail with a validation error if you pass an invalid configuration.
All fields in the configuration are optional because you are always able to pass them on the command line.
Options passed on the command line have higher precedence than options given
in a configuration file. Options that you define inside a section esgettext
in package.json have higher precedence than options that default to
general fields inside package.json.
A complete example for a configuration can look like this:
package: {
textdomain: 'com.example.my-package',
'msgid-bugs-address': 'you@example.com',
name: 'my-package',
'copyright-holder': 'Yours Truly <you@example.com>',
},
po: {
directory: 'po',
locales: ['de', 'fr-CA', 'fr-FR', 'it'],
}General information about your package.
The textdomain of your package, usually something like
com.example.YOUR-PACKAGE. You should configure this.
An email address or URL where to send bug reports or questions about message ids. This is added to the respective field in all generated po files.
If you omit this field, it will be read from the fields bugs.email or
bugs.url (in that order) in package.json.
The name of your package.
If you omit this field, it will be read from the field name in
package.json.
The copyright holder of your package. This is added as a comment to all generated po files.
If you omit this field, it will be read from the field people.author in
package.json.
The version of your package.
If you omit this field, it will be read from the field version in
package.json.
The location of your translation and translation workflow files and feature thereof.
The directory where all translation related files reside, usually 'po'.
An array of locale identifiers. This should always be configured.
Installation options.
Where to install compiled translation files, usually something like
src/locale, assets/locale, or dist/assets/locale.
Information for helper programs.
The path to the msgmerge program of your system.
An array of options to pass to the msgmerge program. Only boolean options
without arguments are supported. And you have to omit the leading hyphens,
for example ['verbose'] or ['v'], and not ['--verbose'] or ['-v'].
The path to the msgfmt program of your system.
An array of options to pass to the msgmerge program. Only boolean options
without arguments are supported. And you have to omit the leading hyphens,
for example ['verbose'] or ['v'], and not ['--verbose'] or ['-v'].
Copyright (C) 2020-2024 Guido Flohr guido.flohr@cantanea.com, all rights reserved.
This software is available under the terms and conditions of the WFTPL.