@esgettext/tools
v1.3.4
Published
Gettext-like po creation and manipulation
Downloads
102
Readme
@esgettext/tools
Supporting tools for https://github.com/gflohr/esgettext.
The package also contains code for parsing po files and for writing them.
Table of Contents
- Prerequisites
- Installation
- The Tools
- Configuration
- Copyright
Prerequisites
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.
Un*x/Linux
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.
Mac OS X
You either need MacPorts or HomeBrew.
MacPorts
$ sudo port install gettextHomeBrew
$ brew install gettextMS-DOS (Microsoft Windows)
The 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.
Installation
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
The 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:
$ npx esgettext --helpesgettext xgettext
The 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.
Other Commands
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.
Configuration
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
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.
Validation
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.
Configuration Schema
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': '[email protected]',
name: 'my-package',
'copyright-holder': 'Yours Truly <[email protected]>',
},
po: {
directory: 'po',
locales: ['de', 'fr-CA', 'fr-FR', 'it'],
}package
General information about your package.
package.textdomain
The textdomain of your package, usually something like
com.example.YOUR-PACKAGE. You should configure this.
package.msgid-bugs-address
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.
package.name
The name of your package.
If you omit this field, it will be read from the field name in
package.json.
package.copyright-holder
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.
package.version
The version of your package.
If you omit this field, it will be read from the field version in
package.json.
po:
The location of your translation and translation workflow files and feature thereof.
po.directory
The directory where all translation related files reside, usually 'po'.
po.locales
An array of locale identifiers. This should always be configured.
install
Installation options.
install.directory
Where to install compiled translation files, usually something like
src/locale, assets/locale, or dist/assets/locale.
programs
Information for helper programs.
programs.msgmerge
programs.msgmerge.path
The path to the msgmerge program of your system.
programs.msgmerge.options
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'].
programs.msgfmt
programs.msgfmt.path
The path to the msgfmt program of your system.
programs.msgfmt.options
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
Copyright (C) 2020-2024 Guido Flohr [email protected], all rights reserved.
This software is available under the terms and conditions of the WFTPL.