@esgettext/runtime

GNU gettext-alike translation runtime library.

Table of Contents

- API Documentation
- Internationalizing Hello World
- Choosing a Textdomain
- Install the Library
- Import the Library
- Prepare Your Sources
- Translation Methods
- Simple Translations With _()
- Variable Interpolation With _x()
- Plural Forms With _nx()
- Message Context With _p()
- Specific Locale with _l
- TODO: Gender-Specific Translations
- Selecting the Preferred Language with selectLocale()
- Internationalizing a Library
- Frequently-Asked Questions
- Why do Template Strings not Work?
- What Does the Error "template literals with embedded expressions are not allowed as arguments to gettext functions because they are not constant" Mean?
- Copyright

API Documentation

If you are already familiar with the concepts of the esgettext runtime library,
you can go straight to the API documentation.

Internationalizing Hello World

You have written this little piece of JavaScript:

``javascript
console.log('Hello, world!');
`

What are the steps needed to internationalize it with this library?

$3

First, you have to choose a unique identifier for your project so that the
translation catalogs will have a unique name. You are almost free
in what you are choosing but you have to keep in mind that the textdomain
will be part of a URI or filename and therefore a couple of rules apply:

- A textdomain _must not_ contain a slash ("/").
- A textdomain _should not_ contain a colon (":"), because of Windows.
- A textdomain _should not_ contain a backslash ("\"), because of Windows.
- A textdomain _should not_ contain binary characters, because of common sense.

In general, you should only use lowercase characters that are valid inside
hostnames, namely "a-z", "0-9", the hyphen "-", and the dot ".".

If possible, follow this advice:

1. If your organization has a domain, use the reverse(!) domain name followed by the name of your product for example "com.example.hello"
2. Otherwise, if your project sources are publicly hosted use the reverse domain name of your hoster followed by an identifier of your project. For example, the textdomain for https://github.com/gflohr/esgettext would then be "com.github.gflohr.esgettext".
3. Otherwise, use common sense.

We will use the the third rule and pick the textdomain "hello".

$3

You normally install the library with npm or yarn.

With npm:

`shell
$ npm install --save @esgettext/runtime
`

Or with yarn:

`shell
$ yarn add @esgettext/runtime
`

$3

How to import the library, depends on your environment.

If you have the import keyword (TypeScript or ES module syntax):

`javascript
import { Textdomain } from '@esgettext/runtime';
`

If you can use require:

`javascript
const { Textdomain } = require('@esgettext/runtime');
`


If you are writing javascript loaded by a browser:

`html


`

If you want a specific version, you can do like this:

`html


`

$3

Change your hello.js to read like this:

`javascript
import { Textdomain } from '@esgettext/runtime';

Textdomain.locale = 'fr';
const gtx = Textdomain.getInstance('hello');
gtx.bindtextdomain('/assets/locale');
gtx.resolve().then(function () {
console.log(gtx._('Hello, world!'));
});
`

_Hint:_ If you cannot use import, use one of the other techniques shown
above to make the Textdomain class available in your source!

What is happening here?

First, you set the locale (resp. language) to the desired value. Here we
choose "fr" for French. See the section Selecting the Preferred Language with selectLocale()
for a more flexible way to select the user's locale.

You then get an instance of a Textdomain object. You cannot use the regular
constructor because it is private! The argument to the
getInstance() class
method is the textdomain you have chosen.

You then have to tell the library where to find translations for the "hello"
textdomain. You do that with the instance method
bindtextdomain() that
receives a (base) directory as its argument. The actual translation catalog
would then be searched at /assets/locale/fr/LC_MESSAGES/hello.mo.json (or
hello.mo or hello.json, depending on your environment).

Don't worry that there are no translations at the moment. Failure is handled
gracefully by the library falling back to using the original, untranslated
strings. See the docs for tools for
instructions on how to create translation catalogs.

You then have to resolve() the translations. The method returns a promise,
and your actual code should be moved into the promise's then() method.

Now that everything is loaded you can translate all messages by replacing
'some string' with gtx._('some string'). That's it!

$3

The method _() is the simplest but by far not the only translation method
that esgettext has to offer.

#### Simple Translations With _()

The method _() has already been introduced:

`javascript
console.log(gtx._('Hello, world!'));
`

It returns the translation of its argument or just the argument if no
translation can be found.

#### Variable Interpolation With _x()

Imagine you want to express RGB colors in human-readable form. The esgettext
way to do that goes like this:

`javascript
console.log(gtx._x(
'red: {r}, green: {g}, blue: {b}', {
r: red,
g: green,
b: blue
}
);
`

You use placeholders surrounded by curly braces ({}), and provide an object
as an additional argument where the keys are the placeholder names and the
values, the respective values to be interpolated.

Placeholder names must be valid C identifiers: They must begin with a
lower- or uppercase letter ("a" to "z", "A" to "Z") or an underscore ("\_")
followed by an arbitrary number of characters from the same set or decimal
digits ("0" to "9"). In regular espression syntax: /^[_a-zA-Z][_a-zA-Z0-9]*$/.

#### Plural Forms With _nx()

Translating a string with plural expressions is unfortunately somewhat
convoluted:

`javascript
console.log(
gtx._nx('One file copied', '{count} files copied.', count, {
count: count,
}),
);
`

Count, count, count, count.

If the variable count has the value 42, the above would yield in English:
"42 files copied.". If count had the value 1, it would yield: "One file
copied.".

The method _nx() has this signature:

`javascript
_nx(
(msgid: string),
(msgidPlural: string),
(numberOfItems: number),
(placeholders: Object),
);
`

Many times, the placeholder name will equal the variable name, so that you see
that name once inside the plural string as the placeholder, then as the
argument numberOfItems, then as the key in the placeholder hash, and again
as the value for that key.

Note that there is also a method _n() that does the same as _nx() but
without inpterpolation but it only exists for completeness and is useless for
practical purposes.

#### Message Context With _p()

It is sometimes possible that one English sentence can have multiple, different
meanings in another language. For example "Sun" can mean our planet's star or
the abbreviation of "Sunday". In order to allow translators to provide
accurate translations for each meaning, you can distinguish them by message
context:

`javascript
weekday = gtx._p('wday', 'Sun');
star = gtx._p('star', 'Sun');
`

The first argument is the context (a free-form string), the second is the
string to translate.

It is actually sufficient to use a context just for one of the two cases.

There are also methods _px(), when you need placeholders or _npx(), when
you need placeholders and plural forms in addition to a message context.

#### Specific Locale with _l

Most of the time, the locale resp. language is set just once by setting the
static property locale:

`javascript
Textdomain.locale = 'fr';
console.log(gtx._('Hello, world!'));
`

Alternatively, you can pass the locale with every call to a translation
method:

`javascript
console.log(gtx._l('fr', 'Hello, world!'));
`

There is not just _l(), but actually all of the above mentioned methods have
versions with a leading _l, like
_lx()
or as complicated as
_lnpx().

One use-case for the
_l()
family of methods
would be a web server. A web server handles requests asynchronously, and a
global locale doesn't make sense. Instead, the language is typically bound
to the request or response and should be taken from there.

#### TODO: Gender-Specific Translations

This is on the todo list for a future version. You will be able to do something
like:

`javascript
msg = gtx._g(
user.gender,
'They have liked your photo.',
'She has liked your photo.',
);
`

$3

Negotiating the preferred locale can be performed with the help of esgettext.
If your application supports the locales "en-US", "en-GB", "fr-FR", and
"de-DE", you can select a suitable locale for the current user by calling
Textdomain.selectlocale

`javascript
Textdomain.locale = Textdomain.selectLocale(['en-US', 'en-GB', 'fr-FR']);
`

Textdomain.selectLocale()
will return the most suitable locale for the current user. For browser code,
the browser will be queried for the user language preferences, for server
code the environment variables LANGUAGE, LC_ALL, LANG, and LC_MESSAGES
will be queried in that order.

You can also explicitly specify, which locales the user has requested by
passing a second argument:

`javascript
Textdomain.locale = Textdomain.selectLocale(
['en-US', 'en-GB', 'fr-FR'], // Supported by the application.
['de-DE', 'fr-FR'],
); // Requested by the user.
`

Internationalizing a Library

Internationalizing a library is very simple. Take this sample library:

`javascript
function greet(name) {
return Hello, ${name};
}
`

Internationalized, it would look like this:

`javascript
import { Textdomain } from '@esgettext/runtime';

const gtx = Textdomain.getInstance('hello-library');
gtx.bindtextdomain('/assets/locale');

function greet(name) {
return gtx._x('Hello, {name}', { name: name });
}
`

The main differences to an internationalized application are:

- You do not set Textdomain.locale because the main application (the application that loads your library) does it.
- You do not call resolve() because whenever the main application calls resolve(), the catalogs for your library will also be loaded.

Frequently-Asked Questions

$3

A common error is to use template strings with interpolations as arguments to
the translation functions, for example:

`javascript
console.log(gtx._(red: ${red}, green: ${green}, blue: ${blue});
`

That seems to work for English but the string never gets translated.

The reason is that the argument to
_()
is the lookup key into the translation database but that key has to be constant.
The method receives an argument like "red: 127, green: 63, blue: 31" because
the JavaScript engine has already interpolated the variables into the string.
But that string does not exist in the database.

You have to use
_x()
instead:

`javascript
console.log(gtx._x(
'red: {r}, green: {g}, blue: {b}', {
r: red,
g: green,
b: blue
}
);
`

$3

See Why do Template Strings not Work?
above! The extractor esgettext-xgettext` complains that you are using a
template string with interpolated expressions.

Copyright

Copyright (C) 2020-2024 Guido Flohr , all
rights reserved.

This software is available under the terms and conditions of the
WTFPL.