readme.md

Angular-Translate Quality

This library allows to verify the correctness of angular-translate elements.
Angular-translate is an Angular library to manage internationalization through JSon files and keys in HTML views. Each language is managed in its own JSon file.

This library allows to check that...

• ... the json file is valid (e.g. no tabs used in values).
• ... a key is declared only once in a JSon file (no duplicate).
• ... a key is declared in upper case.
• ... there is no trailing space in the JSon files (reduce the size).
• ... keys are sorted alphabetically (ease the search for a specific key).
• ... values that contain HTML mark-ups are closed correctly.
• ... values do not contain forbidden patterns (to ban words, check typography, etc).
• ... values are trimmed (no white space character at the beginning or the end).
• ... all the JSon files have the same keys (no missing key).
• ... all the equivalent values (across all the JSon files) have the same number of HTML mark-ups.
• ... all the HTML files reference a key that was declared in the JSon files.
• ... no HTML file mixes the translate directive and the translate filter.
• ... all the alt and title attributes are translated in HTML files.
• ... all the mark-ups texts are translated in HTML files.
• ... all the Angular texts ({{ 'some text' }}) are translated in HTML files.
• ... all the i18n keys are used somewhere in the HTML files.
• ... all the translate filters are well-formed (e.g. no {{ KEY_WITHOUT_QUOTES | translate }}).

This library does not support...

• ... keys declared in Javascript code (only in JSon files).
• ... namespaces in JSon files (at least, not for the moment).

Options

• options.loc_i18n: the location of the JSon files. Default is ./src/i18n/.
• options.loc_html: the location of the JSon files. Default is ./src/**/.
• options.cb: a callback function to handle error messages. Default is console.log.
• options.fail_on_warning: whether the result should be marked as invalid when warnings are found. Default is false.
• options.exclusions: a list of (entire) strings that should be considered as not translatable.
• options.forbidden_patterns: a set of forbidden patterns in values. No default value.
• options.external_keys_cb: a callback function to handle errors related to external keys. No default value.
• options.forbidden_patterns_cb: a callback function to handle errors related to forbidden patterns. No default value.
• options.check_html: true to search non-translated text in HTML mark-ups and attributes, as well as in Angular texts ({{ 'some text' }}). Default is true. All the mark-ups are verified. About attributes, only alt and title are verified.
• options.indent: the indentation used in translation files. Default is \t.
• options.ignore_order: normally keys should be arranged in alphabetical order to ease search for a specific key. Using this option, this check can be deactivated. Default is false.
• options.ignore_empty_values: normally values should not be empty. Using this option, this check can be deactivated. Default is false.

Usage

Add the dependency in your file...

npm install angular-translate-quality --save-dev

... and use it...

var qual = require('angular-translate-quality');
var valid = qual.validate();

... or with your own custom options...

var qual = require('angular-translate-quality');

function cb(msg) {
  console.log(msg);
}

var valid = qual.validate({
  loc_i18n: './i18n/**/',
  loc_html: './html/**/',
  cb: cb
});

Forbidden Patterns

Forbidden patterns is an option to ban words or verify typography in translated text (values in JSon files).
Each JSon file can have its own patterns.

In this example, we assume we have en.json, fr.json and it.json files.
We only define forbidden patterns in en.json and fr.json.

var options = {
      forbidden_patterns: {}
};

options.forbidden_patterns.en = [
  {regex: '\\s+[,.;:?!]', msg: '[EN] All the punctuation marks refuse any preceding white space character.'},
  {regex: 'banned', sensitive: true, msg: '"banned" is a forbidden key word.'}
];

options.forbidden_patterns.fr = [
  {regex: '\\s,', msg: 'Une virgule s\'écrit sans espace avant.'},
  {regex: ',([^ ]| {2,})', msg: 'Une virgule s\'écrit avec un seul espace après.'},
  {regex: '^[a-z]', sensitive: true, msg: 'A sentence starts with an upper-case letter.'}
];

The structure of this option is the following.

• Object keys: name of a JSon file, without the .json extension. en.json => en
• Object values: array of objects.

Each object has the following properties.

• regex: a regular expression that should output an error when found.
• sensitive: true if the pattern search should be case-sensitive (default: false, i.e. case insensitive).
• msg: the message to display when the regular expression was found in a value.

It is possible to intercept errors related to forbidden patterns.
As an example, considering the rules given above, a date pattern (e.g. MMM d, y @ h:mm:ss a) would be rejected. For such situations, it is possible to use a call back handler.

var options = {
  forbidden_patterns: {}
};

// ...

options.forbidden_patterns_cb = function(errorCallback, key, value, errorMsg, lineNumber, filename) {

  // Ignore the keys defined here, but only for English language
  var keysToIgnoreForEnglish = ['KEY_2'];
  var invalid = false;
  if (filename !== 'en' || keysToIgnoreForEnglish.indexOf(key) === -1) {
    // Display an error message
    errorCallback(lineNumber + ': ' + errorMsg);
    // Fail the validation
    invalid = true;
  }

  return invalid;
}

Exclusions for Non-Translated Text

When checking HTML files, mark-ups and some attributes (alt, title) are verified.
Angular-translate elements are removed from the text during the check. If the result is not empty (or only made up of white spaces), an error is returned. Notice that HTML entities (e.g. ») are also skipped from the check. It is possible to add exclusions too. Thus...

<img src="" alt="..." />

... can be made valid by using the exclusions option.

var options = {
      exclusions: ['...'] 
};

Handling Not Found Keys

When options.check_html is true, this library searches for keys that re not used anywhere in HTML files. However, it is possible that keys are used in JS files instead of HTML ones. Let's consider the following example.

HTML view:

<p>{{ formatStatus( node ) | translate }}</p>

JS controller:

$scope.formatStatus = formatStatus;

function formatStatus( node ) {
  // Find the right i18n key
  return KEY;
}

Basically, the translation key is dynamically deduced by a controller function.
So, the key(s) will not be found in HTML files but in the JS file. Therefore, we do not want any warning here.

To deal with such situations, we can use the options.external_keys_cb option.
This option points to a callback function that takes the error callback (options.cb) and an array of the keys that were not found. This callback must return false to consider the messages as warnings, true to mark the validation as invalid.

It is a way to filter warnings.

$options.external_keys_cb = function(errorCallback, notFoundKeys) {
  notFoundKeys.forEach(function(key) {
    
    // Manual check or read some file...
    // If not found, add an error message.
    errorCallback('Key ' + key + ' was not found anywhere.');
  });

  // Consider these errors as warnings => return false.
  return false;
}

The warnings returned by this callback function will replace those that would have been emitted by default for not found keys.

Example with Gulp

var qual = require('angular-translate-quality');
var gutil = require('gulp-util');

gulp.task('check_i18n', function() {

  var res = qual.validate();
  if (! res) {
    throw new gutil.PluginError({
      plugin: 'check_i18n',
      message: 'Errors were found about internationalization.'
    });
  }
});

To run checks then, just execute gulp check_i18n.

License

This package is licensed under the terms of the MIT license.

Changing the Version

Simply update the version in the package.json file.
Then, commit and push your change to the Git repository, before running the release command.

Developers

• Initialize: npm install
• Test: gulp test
• Send coverage report to Coveralls: gulp coveralls
• Lint check: gulp lint
• Release: gulp complete-release
• Local build: npm pack

For Linagora folks, releases to our NPM repository are managed through our Jenkins server.
Please, log into it and run the angular-translate-quality-release job.