Clarify that gettext() only serves for extraction

[rubenv]

This comes up again and again:

• Annotating strings in Javascript code #19
• 33557ea#commitcomment-4616121

[dipson]

I think changing the example here would help: http://angular-gettext.rocketeer.be/dev-guide/annotate-js/

It would be useful to include an example of displaying a string which is extracted from JS.

To modify your current example slightly...

Controller:

angular.module("myApp").controller("helloController", function ($scope, UserService, gettext) {
    $scope.greeting = gettext("Hello");
    $scope.username = UserService.getName();
});

View:

<div ng-controller="helloController">
    <h1>{{ greeting | translate }}, {{username}}</h1>
</div>

[rubenv]

Well, the example you're proposing could be written as <h1 translate>Hello, {{username}}</h1>, which is even better (not all languages want the ,, or the same word order, putting the entire text in a string gives translators the freedom to do adjust that).

But I totally agree, we need a good example. I typically run into these when generating mark-up (e.g. a list of translated menu items generated with ng-repeat).

[danse]

I was also confused by this, and looking for more info. Maybe it is just the interface being counterintuitive? Maybe having translated = gettext('original') is just what is most commonly expected and needed. I agree that translating in the template is much cleaner, but there are many cases for needing this in the javascript, for example when using directives written by other people

[rubenv]

I agree that translating in the template is much cleaner, but there are many cases for needing this in the javascript, for example when using directives written by other people

Use gettextCatalog.getString for those purposes. What you are trying to do is perfectly possible. See here: http://angular-gettext.rocketeer.be/dev-guide/annotate-js/#translating-directly-in-javascript-

[danse]

I knew that, but i argue that the behaviour many expect and the related use case should not be considered probably wrong

Yup, that looks ugly, as a reminder that it's probably the wrong thing to do.

This is mostly true, but if someone is digging into "translating directly in javascript" probably the translate directive, widely presented in all the rest of the doc, is not the suitable solution for her case. As i said, the case may just be a directive written by somebody else, like the modal in angular-strap. Just an opinion

[rubenv]

i argue that the behaviour many expect and the related use case should not be considered probably wrong

Except it is. To do translations properly means doing it in the views. Note that nothing is impossible with the current design, it simply encourages the proper usage.

You should take this as a general guideline: the easiest path is probably the best one.

The only exception where translating directly in JS is desired is as you mention: interop with other libraries. It's perfectly possible to do that, it's just not the easiest and most obvious way, but that's because in most cases it's not the thing you need anyway.