Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/medic/translation-checker
Check translations from .properties files with Mustache placeholders markup or messageformat syntax.
https://github.com/medic/translation-checker
library messageformat mustache nodejs properties
Last synced: about 1 month ago
JSON representation
Check translations from .properties files with Mustache placeholders markup or messageformat syntax.
- Host: GitHub
- URL: https://github.com/medic/translation-checker
- Owner: medic
- License: agpl-3.0
- Created: 2020-08-08T00:47:15.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2022-09-15T10:21:28.000Z (over 2 years ago)
- Last Synced: 2024-05-01T11:35:55.254Z (8 months ago)
- Topics: library, messageformat, mustache, nodejs, properties
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/@medic/translation-checker
- Size: 69.3 KB
- Stars: 2
- Watchers: 15
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# translation-checker
Check translations from [.properties](https://en.wikipedia.org/wiki/.properties)
files with [Mustache](http://mustache.github.io/) placeholders markup
or [messageformat](https://messageformat.github.io/messageformat/) syntax.
## Getting started
Node 8.10+ required. Install with:
$ npm install @medic/translation-checker
Here is how you can use it:
```js
const {
checkTranslations,
TranslationException
} = require('@medic/translation-checker');
const dir = `${somePath}/translations`;
let fileNames;
try {
fileNames = await checkTranslations(dir);
// Your files passed the validations!
// fileNames = ['messages-en.properties', 'messages-es.properties', ...]
} catch (err) {
if (err instanceof TranslationException) {
// Oops, translation errors !!
fileNames = err.fileNames; // ['messages-en.properties', 'messages-es.properties', ...]
if (!err.errors) {
return log.error('Exception checking translations:', err.message);
}
for (const error of err.errors) {
switch (error.error) {
case 'cannot-access-dir':
return log.warn('Could not find custom translations dir:', dir);
case 'missed-placeholder':
case 'wrong-placeholder':
log.error(error.message);
break;
case 'missing-key':
case 'empty-message':
// less severe, lets log it with WARN severity instead of ERROR
log.warn(error.message);
break;
default: // 'wrong-messageformat', 'wrong-placeholder'
// This are more severe errors
log.error(error.message);
break;
}
}
} else {
throw err; // unexpected ;(
}
}
```
Logs from the example above will look like:
```
WARN Empty message found for key 'report.pregnancy.u_lmp_date' in 'en' translation
WARN Empty message found for key 'report.pregnancy.method_lmp' in 'en' translation
ERROR Cannot compile 'es' translation with key 'Number in month' has placeholders that do not match any in the base translation provided
ERROR Cannot compile 'es' translation n.month = '{MONTHS, plural one{1 mes} other{# meses}}' : Expected "," but "o" found.
```
## Arguments
`checkTranslations(dir, options)` (async)
- `dir`: the directory to scan
- `options.languages`: Array of lowercase ISO 639-1 code languages to be checked. Defaults to all valid files found in `dir`.
- `options.checkPlaceholders`: Whether to check missed placeholders or not. Defaults to `true`.
- `options.checkMessageformat`: Whether to check wrong Messageformat or not. Defaults to `true`.
- `options.checkEmpties`: Whether to check empty messages or not. Defaults to `true`.
- `options.checkMissing`: Whether to ensure all keys in "en" file also exist in other languages. Defaults to `false`.
## Error details
All the errors raised by `checkTranslations()` are instances of `TranslationException`. The exception
object has an `errors` array with one object for each error detected as following:
```javascript
{
"lang": "en", // The language where the error was found
"error": "wrong-messageformat", // The error code
"key": "n.month2", // The translation key
"message": "Cannot compile ..." // A message with more details about the error
}
```
These are the `error` codes and what they mean:
- **`cannot-access-dir`** - the directory passed doesn't exist or is not accessible
- **`wrong-file-name`** - one of the translation files has a wrong name or has
an unknown ISO 639 language code on it, eg. `messages-e$.properties`
- **`missed-placeholder`** - a mustache placeholder eg. `{{firstName}}` was found
in a translation, but main translations ('en' or 'ex') don't have
placeholders for that translation at all
- **`wrong-placeholder`** - a mustache placeholder eg. `{{firstName}}` was found
in a translation that do not match any in the base translations ('en' or 'ex')
placeholders
- **`empty-message`** - empty message found in a translation
- **`missing-key`** - a key was found in the English translation file but not
found in one of the other languages
### Placeholders check
The mustache placeholder check works as following:
- You need to call `checkTranslations(dir, options)` with
`options.checkPlaceholders = true` (default).
- `options.languages` needs to be unset (default) or set at least with
one or both of the two codes considered "template" languages: 'en', 'ex'
- 'ex' is not a real ISO language code, but if you have a
`messages-ex.properties` file, you can place there placeholders
that can be used for a specific key,
eg. `hello = {{firstName}} {{lastName}} {{username}}`
- 'en' language (`messages-en.properties`) is considered the "template"
or base language, and any placeholder used in any other translation
file other than 'en' or 'ex' needs to be present in one of these
two templates. Eg. if you have in the 'en' translation the following
translation `records.total = {{count}} records`, this is a valid 'es'
translation: `records.total = {{count}} registros` but this not:
`records.total = {{count}} registros de {{max}}`. You can use the
`{{max}}` placeholder either adding it to the 'en' translation or
adding an entry in the `messages-ex.properties` file like this:
`records.total = {{max}}` (or `records.total = {{count}} {{max}}`)
Check the JSDoc of the source code to see more options.
### Messageformat check
"Messageformat" check are also performed by default, you can
disable it with `options.checkMessageformat = false`.
A common error is by mistake translate the messageformat
keywords when using online translator tools, eg. this
translation that is OK in English:
```properties
n.month = {MONTHS, plural, one{1 month} other{\# months}}
```
Wrong translated to Spanish:
```properties
n.month = {MONTHS, plural, uno{1 mes} otros{\# meses}}
```
Will raise an error with a the message:
```
Invalid key `uno` for argument `MONTHS`. Valid plural keys for this locale are `one`,
`other`, and explicit keys like `=0`
```
The right translations is:
```properties
n.month = {MONTHS, plural, one{1 mes} other{\# meses}}
```
### Empty message checks
Validations fail if a key is found like this:
```properties
n.month =
```
But some times empty keys are acceptable because
the software that use the translations fallback
to the default language, so to disable empties
check set `options.checkEmpties` to `false`
(default is `true`).
## Publishing
$ npm publish --access=public