Capabilities
Client Library
Color Theme Compliance (Beta)
UI Functions

Localization

Trello Power-Ups were designed with Internationalization in mind. When creating a plugin or iframe, you can optionally pass in the options argument one of the following:

localization object:

1
2
localization: {
  defaultLocale: 'en',
  supportedLocales: ['en', 'fr'],
  resourceUrl: './strings/{locale}.json'
}

localizer object:

1
2
localizer: {
  localize: function (key, data) {
    ... synchronously returns a localized string for the given key and data ...
  }
}

loadLocalizer function:

1
2
loadLocalizer: function (locale) {
  ... returns a Promise that resolves to a localizer object ...
}

You can pass those to TrelloPowerUp like so:

1
2
var t = window.TrelloPowerUp.iframe({
  localization: {
    defaultLocale: 'en',
    supportedLocales: ['en', 'fr'],
    resourceUrl: './strings/{locale}.json'
  }
});

// or

window.TrelloPowerUp.initialize({
  'capability': function (t, opts) { ... }
}, {
  localization: {
    defaultLocale: 'en',
    supportedLocales: ['en', 'fr'],
    resourceUrl: './strings/{locale}.json'
  }
});

Additionally, you can set window.localizer to your own custom localizer and the t.localize* methods will use it.

Once a localizer has been initialized, you can call the following new handlers (which behind the scenes make use of the localizer). We make the current user locale available to you via window.locale. Additionally, you can grab it off the options object from any of the interfaces or callbacks as well.

Localization in iframes other than the connector

When you are using

1
2
var t = window.TrelloPowerUp.iframe({
  localization: {
    defaultLocale: 'en',
    supportedLocales: ['en', 'fr'],
    resourceUrl: './strings/{locale}.json'
  }
});

The localizer is not guaranteed to be loaded and ready until the t.render function is called. So trying to use any localization methods prior to that could fail.

Alternatively you could do something like:

1
2
var i18n-settings = {
  defaultLocale: 'en',
  supportedLocales: ['en', 'fr'],
  resourceUrl: './strings/{locale}.json'
};

var t = window.TrelloPowerUp.iframe();

window.locale = /[\?&]locale=([\w-]+)/.exec(location.search)[1];

window.TrelloPowerUp.util.initLocalizer(window.locale, { localization: i18n-settings })
.then(() => {
  // t.localize methods are now available
  t.localizeNode(document.getElementById('content'));
});

We cover localizing a simple Power-Up in our YouTube series:

t.localizeKey(key, data)

Given a key, and optional replacement data, synchronously returns the output of window.localizer.localize(key, data)

Assume you have a resources file like:

1
2
{
  "btn-name": "Hi {name}"
}

1
2
window.TrelloPowerUp.initialize({
  'card-buttons': function (t, opts) {
    return [{
      text: t.localizeKey('btn-name', { name: 'Trello' }),
      url: 'https://developer.atlassian.com/cloud/trello/',
    }];
  }
});

That will generate a button with the text: Hi Trello

t.localizeKeys(keys)

Synchronously localizes multiple keys. You can either provide an array of keys ['key1', 'key2'] or an array of key-data arrays [['key1', { data: 1 }], ['key2', { data: 2 }]]. This will return an array of strings, in the same order as the keys were passed in.

1
2
window.TrelloPowerUp.initialize({
  'card-buttons': function (t, opts) {
    return [{
      text: t.localizeKeys([['btn-name', { name: 'Trello' }]]),
      url: 'https://developer.atlassian.com/cloud/trello/',
    }];
  }
});

t.localizeNode(DOMelement)

Synchronously inserts localized texts into DOM nodes starting at the provided node and all of its children. Tag a node in your HTML with data-i18n-id="key" for its text content to be replaced based on that key. You can pass args with data-i18n-args='{ "arg1": "data" }'. You can also have placeholder text replaced with data-i18n-attrs='{ "placeholder": "key" }'. This will also use the args defined in data-i18n-args.

Currently there is no support for dot notation when replacing args.

Let's assume we have an overlay iframe that looks like this:

1
2
<html>
  <head>
    <link rel="stylesheet" href="https://p.trellocdn.com/power-up.min.css">
    <link rel="stylesheet" href="./css/overlay.css">
    <script src="https://p.trellocdn.com/power-up.min.js"></script>
  </head>
  <body>
    <div id="content">
      <h2 data-i18n-id="tips-for-overlay">Tips for using t.overlay()</h2>
      <hr/>
      <ol>
        <li data-i18n-id="only-for-user-actions">
          You should only call t.overlay() as a response to a user action, such as clicking a button.
        </li>
        <li data-i18n-id="prefer-t-popup">
          Try to use t.popup() when possible instead of t.overlay() as it helps to better maintain context.
        </li>
        <li data-i18n-id="easy-to-close">
          When using an overlay, be sure to keep the user aware they haven't left their Trello board, and make it easy and intuitive to close.
        </li>
        <li data-i18n-id="load-and-render-fast">
          Try to get your overlay to load and render as quickly as possible.
        </li>
      </ol>
    </div>
    <script src="./js/overlay.js"></script>
  </body>
</html>

Our javascript to make sure that gets localized might look like:

1
2
var t = window.TrelloPowerUp.iframe({
  localization: {
    defaultLocale: 'en',
    supportedLocales: ['en', 'fr'],
    resourceUrl: './strings/{locale}.json'
  }
});

t.render(function(){
	let contentNode = document.getElementById('content');
  t.localizeNode(contentNode);
});

For reference the ./strings/en-US.json file would look like:

1
2
{
  "tips-for-overlay": "Tips for using t.overlay()",
  "only-for-user-actions": "You should only call t.overlay() as a response to a user action, such as clicking a button.",
  "prefer-t-popup": "Try to use t.popup() when possible instead of t.overlay() as it helps to better maintain context.",
  "easy-to-close": "When using an overlay, be sure to keep the user aware they haven't left their Trello board, and make it easy and intuitive to close.",
  "load-and-render-fast": "Try to get your overlay to load and render as quickly as possible."
}

Rate this page: