Modernizing my Power BI Connector with Forge
When I first built the Power BI Connector, I focused on getting the core functionality right. The app worked well, but under the hood it was showing its age. Colors were hardcoded, text was English-only, and dark mode support was something I'd been putting off. Atlassian's i18n and design token features solve both of these problems. i18n allows your app to serve translated content based on a user's language and locale, and design tokens allow your app's colors to automatically respond to the active theme in Jira. I recently rewrote a substantial portion of the connector's codebase to take advantage of both, and in this article I want to walk through what that involved and what I learned along the way.
Internationalization
Setting up Internationalization (i18n) in Forge involves creating a JSON translation file for each language you want to support, updating your manifest to point to those files and define fallback behaviour, and then replacing hardcoded strings in your app code with translation keys using the i18n function or the useTranslation hook.
I decided to add support for all 26 languages that Forge supports. The full list is available in the Forge supported locale codes reference.
A few things I'd pass on to anyone going through this process:
Wait until your app is stable: Every time you change a piece of text it isn't just one edit. You need to get that string translated into 25 other languages and update every translation file. If your app is still changing frequently, i18n will slow you down considerably.
Test every language: Some languages are significantly longer than English, and I regularly found text wrapping unexpectedly or content overlapping and becoming unreadable during testing. In some cases a direct translation wasn't possible and I had to shorten the original text so it could be translated accurately while still conveying the same meaning. Changing your language requires updating your settings at Atlassian account preferences for each one, which gets tedious fast.
Automate as early as possible: I use a translation service that I was able to automate into a single output file, and then wrote a script to distribute the translations across all 26 files at once. Without that in place, the overhead would have been unmanageable. Getting a process like this set up at the start will save a significant amount of time.
Examples:
Design Tokens and Theming
Design tokens and theming is a Forge feature that allows your app's colors and styling to automatically respond to the active theme in Jira, including dark mode, without any manual effort. Rather than hardcoding color values, you reference Atlassian's design tokens and the theming is handled for you.
If you are already using CSS custom properties or Sass variables in your app, adopting design tokens should feel familiar. The concept is the same: you reference a variable instead of a hardcoded value, and the value is controlled centrally. The difference is that Atlassian's design tokens are tied to the active theme, so the values update automatically in response to theme changes.
The effort required was relatively small compared to implementing i18n — it mostly involved replacing hardcoded color values throughout my CSS files. Once that was done, the theme colors were handled automatically without any additional logic on my end. Before this change, dark mode in my app looked pretty rough because I hadn't considered or tested it at all. Now, I'm really happy with how the app looks in both light and dark themes, and it stays automatically in sync with Jira.
Examples:
Conclusion
Both of these features required a significant amount of rework to implement, but I'm glad I prioritized them. The app is more accessible, supports a much wider range of users, and feels more integrated with Jira than it did before.
If you have any questions about the process feel free to reach out to me at jack@pallas-apps.com. I maintain the connector full time and we recently released a major new version with features not covered in this article. If you are interested you can find out more on our website or on the Atlassian Marketplace.
Was this helpful?
Thanks!
Jack Dillon - Pallas Apps
2 comments