@tradeshift/ng-translate-t

ng-translate-t

Angular 1.x module to provide convenient translation directives.

The problem

Using translations across views in Angular apps is tedious and error prone with $scope variables, and angular specific with existing libraries like angular-translate.

This solution

We provide configurable directives, t and t-attrs, focusing on extracting the metadata for the translations, and allowing you to specify your own lookup method.

The directives extract the text, dynamic params, context and shouldEscape from the attributes.

Table of contents

• Installation
• Usage
• API
• License

Installation

Install via npm

npm i ng-translate-t

Usage

Register the module

// recommended w/ commonJS module:
angular.module('app', [require('ng-translate-t')]);
// UMD / browser use:
angular.module('app', ['ng-translate-t']);

Configure your translation provider:

app
  .config($translateProvider => {
    // Set your preferred translation function here:
    $translateProvider.setTranslationFunction((text, params, context, shouldEscape) => {
      // Our translators are lazy, so we translate everything to "42".
      return '42';
    });
  });

See the example for a demo app.

API

$translateProvider.setTranslationFunction(fn: TranslationFunction): void

Replaces the translationFunction with fn. Defaults to window.t.

Types:

• TranslationFunction: (text, params, context, shouldEscape): string

Params:

• text: string is the extracted string for translation
• params: {[k: string]: string} are parameters to pass to do e.g. dynamic pluralization
• context: string gives context to translators and allows different translations of the same text based on context, e.g. whether it's for a form or an image
• shouldEscape: boolean allows conditional escaping (HTML or other) where needed

t directive

Used to replace the contents (innerHTML) of an element with translated strings.

If the element has children, their attributes are replaced with a ref="1" count (in depth-first order), in order to preserve translation hashes when e.g. style attributes change.

Attributes:

• [t-[param]]: string. Any attribute starting with t- will become a params key (camelCased), with the value read from $scope under the corresponding key.
• [t-context]: string passed to translationFunction as context
• [t-escape]: boolean passed to translationFunction as shouldEscape

<t>Translatable string</t>
<div t>Translatable string</div>

<!-- passing down $scope.oranges as orangesCount -->
<div t t-oranges-count="oranges">
  You have {orangesCount} {orangesCount, plural,
    one {orange}
    other {oranges}
}
</div>

[t-attrs] directive

Used to replace attributes of an element with translated strings.

Attributes:

• [t-attrs]: string comma delimited string of attributes to replace with translations.
• [t-context]: string passed to translationFunction as context
• [t-escape]: boolean passed to translationFunction as shouldEscape

<div t-attrs="title" title="Translatable string"></t>
<img t-attrs="alt,title" title="Translated title" alt="Translated alt" src="#" />

License

ISC. Copyright (c) 2018, Tradeshift.