tml-angular

v0.0.20

Published

2 years ago

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

Downloads

0High
0Medium
0Low

translationexchange

internationalization translation localization translate localize i18n t9n tr8n l10n tml

TML for Angular.JS

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)

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="Invite" tml-description="An invitation you received from your friend"></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 {num} visit" | trl:{ user: logged_in_user, num: 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"/>

Copyright and license

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.