Angular

This adds angular directives that allow you to perform seamless and advanced translations using TML from TranslationExchange.

Learn more about TML

Requirements

  • AngularJS
  • TranslationExchange account

Getting started

You can get it from Bower

bower install tml-angular  

Or on NPM

npm install tml-angular  

Include it on your app (regular script tag)

The following example is for bower, replace bower_components if you put it elsewhere. Make sure to include it after the angular script tag

<script src='bower_components/angular/angular.js'</script>  
<script src='bower_components/tml-angular/src/tml-angular.js'></script>

angular.module('app', ['tml']);  

Include it on your page (browserify)

angular.module('app', [require('tml-angular')]);  

Preparing your angular app

For best results, your angular app should start after the TML library has been initialized.
Remember to remove ng-app from your HTML and instead manually bootstrap the angular app, like in the following example:

tml.init({  
  key: "YOUR_KEY",
  onLoad: function (app) {
    angular.bootstrap(document, ['YOUR_NG_APP']);
  }
});

Usage

As an element, with scope defined data

<tml-tr>Welcome {user}</tml-tr>  

This expects a user key to be defined on the scope where this directive is used.

$scope.user = 'John Doe';

As an attribute, with scope defined data

<h3 tml-tr>Welcome {user}</h3>  

You can also specify the string to be translated as the value of the attribute:

<h3 tml-tr="Welcome {user}"></h3>  

As an element, with custom token associations

You can pass angular expressions in attributes wherever you use tml-tr

$scope.stats = { visit_times: 240 };
<h3 num='stats.visit_times' tml-tr>Welcome {user}, this is your {num} visit</h3>  

As an element, using a values object

Instead of using scope names, it is possible to pass an object with token values, as custom as you make it

$scope.userParams = { name: 'Steve', age: 28, birthday: true };
<div class="user-profile">  
  <h3 tml-tr values="{ user: userParams.name, age: userParams.age }">
            Hello {user}, you're {age} years old!
  </h3>
   <cake ng-if='userParams.birthday' />
</div>  

Note: this cannot be combined with scope parameters
use either custom attributes + scope variables or a values object, not both.

Phrase description

The description of a phrase is not mandatory, but it should be used in cases when the label alone is not sufficient enough to determine the meaning of the sentence being translated. As a general rule, you should always provide description to words, phrases and sentences that are only meaningful within a specific context. TML uses label and description together to create a unique key for each phrase. The description serves two purposes: it creates a unique key for each label and it also gives a hint to the translators for the context in which the label is used.

<h3 tml-tr="Invite" tml-description="Link to invite your friends to join the site"></h3>

<span tml-tr tml-description="An invitation you received from your friend">Invite</span>  

Some examples of advanced usage

Translate input placeholders and other special fields

There's a global function for translating labels, called trl(template, values), it has access to the scope it runs from, so the values object is optional

<input type="text" placeholder="{{ trl('Your username') }}" />  
<input type="password" placeholder="{{ trl('Your password') }}" />  

You can also use trl as a filter, this is recommended for simple strings only, because filter doesn't have access to the scope by default.

<input placeholder="{{ 'Your username' | trl }}" type="text" />  
<input placeholder="{{ 'Your password' | trl }}" type="password" />  

Passing parameters is possible with filters:

Use the surrounding scope (pass the this keyword):

{{ "Hello {user}" | trl:this }}

Pass a custom values object:

{{ "Hello {user}, this is your {count} visit" | trl:{ user: logged_in_user, count: visitCounter } }}

The cool thing about filters is how easy it is to combine them (but otherwise - prefer to use the other options):

<h3> {{ "Hello {user}" | trl:this | toUpper }} </h3>  

Accessing current language options

There are a few useful properties exposed on the $rootScope:

currentLocale - Language specific stylesheets

Dynamically replace the stylesheet based on locale of the language

<link rel='stylesheet' href="/stylesheets/style-{{currentLocale}}.css"/>  

Show a block for a specific locale

<h5 ng-if="{{currentLocale == 'fr'}}">Hello French Speakers</h5>  

isRtl - Right to left stylesheets

Dynamically replace the stylesheet based on direction of the language

<link rel='stylesheet' href="/stylesheets/style{{isRtl ? '.rtl' : ''}}.css"/>