opichals / ember-i18n Goto Github PK

Internationalization for Ember

Ember-I18n requires

• Ember v1.x
• Handlebars-runtime v1.x - v2.x
• jQuery v1.7 - v2.x

Set Ember.I18n.translations to an object containing your translation information. If the values of Ember.I18n.translations are Functions, they will be used as-is; if they are Strings, they will first be compiled via Ember.I18n.compile, which defaults to using Handlebars.compile. (That means that if you haven't precompiled your translations, you'll need to include the full Handlebars, not just handlebars-runtime.js in your application.)

Given

Em.I18n.translations = {
  'user.edit.title': 'Edit User',
  'user.followers.title.one': 'One Follower',
  'user.followers.title.other': 'All {{count}} Followers',
  'button.add_user.title': 'Add a user',
  'button.add_user.text': 'Add',
  'button.add_user.disabled': 'Saving...'
};

<h2>{{t "user.edit.title"}}</h2>

yields

<h2>
  <script id="metamorph-28-start"></script>
  Edit User
  <script id="metamorph-28-end"></script>
</h2>

<h2>{{t title_i18n_key}}</h2>

yields

<h2>
  <script id="metamorph-28-start"></script>
  Add a user
  <script id="metamorph-28-end"></script>
</h2>

if controller.title_i18n_key is 'button.add_user.title'. If it subsequently changes to 'user.edit.title', the HTML will become

<h2>
  <script id="metamorph-28-start"></script>
  Edit User
  <script id="metamorph-28-end"></script>
</h2>

<h2>{{t "user.followers.title" count="2"}}</h2>

yields

<h2>
  <script id="metamorph-28-start"></script>
  All 2 Followers
  <script id="metamorph-28-end"></script>
</h2>

<h2>{{t "user.followers.title" countBinding="user.followers.count"}}</h2>

yields

<h2>
  <script id="metamorph-28-start"></script>
  All 2 Followers
  <script id="metamorph-28-end"></script>
</h2>

if user.getPath('followers.count') returns 2.

The Em.I18n.TranslateableProperties mixin automatically translates any property ending in "Translation":

userButton = Em.Object.extend(Em.I18n.TranslateableProperties, {
  labelTranslation: 'button.add_user.title'
});

userButton.get('label');

yields

"Add a user"

Add the mixin Em.Button.reopen(Em.I18n.TranslateableAttributes) and use like this:

{{#view Em.Button titleTranslation="button.add_user.title">
  {{t "button.add_user.text"}}
{{/view}}

yields

<button title="Add a user">
  <script id="metamorph-28-start"></script>
  Add
  <script id="metamorph-28-end"></script>
</button>

<a {{translateAttr title="button.add_user.title" data-disable-with="button.add_user.disabled"}}>
  {{t "button.add_user.text"}}
</a>

yields

<a title="Add a user" data-disable-with="Saving...">
  <script id="metamorph-28-start"></script>
  Add
  <script id="metamorph-28-end"></script>
</a>

The above translation data can also be expressed as nested JSON objects:

Em.I18n.translations = {
  'user': {
    'edit': {
      'title': 'Edit User'
    },
    'followers': {
      'title': {
        'one': 'One Follower',
        'other': 'All {{count}} Followers'
      }
    }
  },
  'button': {
    'add_user': {
      'title': 'Add a user',
      'text': 'Add',
      'disabled': 'Saving...'
    }
  }
};

This format is often smaller and so makes downloading translation packs faster.

If you want to support inflection based on count, you will also need to include Ember-I18n's pluralization support (lib/i18n-plurals.js) after the Ember-I18n core (lib/i18n.js) itself and set Ember.I18n.locale to the current locale code (e.g. "de").

Em.I18n.locale = 'en';

Now whenever you pass the count option to the t function, template will be pluralized:

Em.I18n.locale = 'en';

Em.I18n.translations = {
  'dog': {
    'one': 'a dog',
    'other': '{{count}} dogs'
  }
};

Em.I18n.t('dog', { count: 1 }); // a dog
Em.I18n.t('dog', { count: 2 }); // 2 dogs

The suffixes 'one' and 'other' are appended automatically.

Example using pluralization in the template:

{{t 'dog' count=dogs.length}} // Assuming dogs property is an array

Depending on the locale there could be up to 6 plural forms used, namely: 'zero', 'one', 'two', 'few', 'many', 'other'.

• There is no way to pass interpolations to attribute translations. I can't think of a syntax to support this. It might be possible to look up interpolations from the current context.
• Em.I18n.translations must be fully populated before Ember renders any views. There are no bindings on the translations themselves, so Ember will not know to re-render views when translations change.

For more detail on running tests and contributing, see CONTRIBUTING.md.