How can we provide great user experiences across the globe?
It all starts with internationalization. Let’s explore how to elevate our product UX for users around the world.
Internationalization and PatternFly
What’s the best way to attract and support users who speak different languages or live in a variety of regions? The PatternFly team recently researched and defined some best practices for internationalization, one tool for improving those users’ experiences.
As a developer, I primarily work on a product called Red Hat OpenShift. We’re heavy users of PatternFly React and recently received some requests to support additional languages and region-dependent timestamps.
We used PatternFly’s internationalization best practices to guide successful internationalization work on OpenShift. Read on to learn more about internationalization’s benefits and best practices.
What’s internationalization and why do we need it?
To examine why we need to internationalize projects and products, let’s explore a hypothetical situation in which you might decide to begin the internationalization process.
Imagine you own a successful U.S. software company called TinyCorp. Recently, you’ve started receiving different types of inquiries than you’re used to.
A potential customer in China writes in to ask if your product can be made available in Chinese, and a customer from the UK wonders why timestamps are formatted differently than what he would expect for his location.
When you speak to your development team, you need to talk about internationalization, the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.
Your process at TinyCorp parallels ours at Red Hat — we needed to internationalize our product to meet diverse user needs. Internationalizing OpenShift meant developing and optimizing its UX for individuals operating from across the globe.
What’s the difference between internationalization and localization?
You can think of internationalization as all the heavy lifting to prepare your product for localization. After internationalization, localization readies products for a new language or region through actions like securing translations and conducting product and user testing.
Using internationalization frameworks
Internationalization frameworks allow you to use your own code base — you just mark what strings the internationalization library should pay attention to. From there, the internationalization library handles detecting the language, managing translations, updating strings with language changes, and more, depending on the framework. It can also communicate with plugins or be extended by third-party libraries.
Joachim Schuler on the PatternFly team did a lot of research on internationalization frameworks and recommended i18next. i18next is very flexible and portable — you can learn it once and use it across almost any framework or platform. There are also language or framework-specific libraries, such as react-i18next. React-i18next adds additional features, such as hooks and higher order components, that make internationalization easier to integrate into a React-based application.
If you’re not familiar with i18next, you can use all sorts of plugins to add functionality. Some of these plugins include tools for detecting the browser language, a backend for loading strings, and a code parser that can help you automatically extract strings you’ve marked for internationalization into JSON files i18next can read. There are even tools to help you convert those JSON files into the correct format for your translation team, and vice versa.
Ultimately, we used the following libraries in our OpenShift project:
- i18next and react-i18next for internationalization
- Code parser for extracting marked strings: i18next-parser
- Pseudolocalizer: i18next-pseudo
- Browser language detector: i18next-browser-languageDetector
- Backend: i18next-http-backend
- Converter for transforming i18next JSON files into the correct format for translation and vice versa: i18next-gettext-converter
The pseudolocalizer grew particularly useful –– it helped us test and improve components to make sure that they could handle long strings (since many languages can be longer than English) and ensure strings were marked for internationalization in testing. We recommend the option to turn brackets on so you can tell if your text is getting cut off!
Accessibility concerns
When you work on an internationalization project, it’s also important to maintain accessibility. Internationalize attributes like aria-label, aria-placeholder, aria-roledescription, or aria-valuetext in addition to your other hard-coded strings to support a great experience for users who rely on assistive technology and communicate in a different language.
Getting started with internationalization
With general best practices and goals laid out for accessible internationalization, we began the process of internationalizing OpenShift. If you’re looking to start your own internationalization project, we recommend taking a look at this roadmap.
1. Define your scope.
- What content and languages will you target?
- What tools will you use?
- Who else needs to be involved?
2. Define your timeframe.
- When will you start?
- When will the feature go live?
3. Create a proof of concept to test out your tools and anticipate challenges.
- Identify and fix configuration issues.
- Add additional plugins if needed.
4. Establish workflows and best practices.
- Create opportunities for your developers to ask questions and share their own insights.
5. Mark your code for internationalization and add tests.
- Update existing tests that rely on hard-coded strings or require mocked internationalization functions.
- Create a system for testing that all strings are internationalized.
6. Maintain your code.
- Think about next steps and ensure all new code is properly internationalized going forward.
Following this internationalization roadmap provides a great opportunity to examine and standardize your content. Internationalization requires touching every string, so why not clean up inconsistencies in casing or terminology, too?
Internationalization with PatternFly
PatternFly abstracts certain text –– in order for your internationalization efforts to impact your entire interface, you’ll need to keep track of what text PatternFly provides by default. Pass in custom text or aria attributes so you can fully translate your user interface. Thankfully, PatternFly makes this easy with clearly defined props in the documentation.
In an internationalization project, as in any project, be sure to factor in extra time for product-level adjustments. As we worked on OpenShift, we realized that we needed additional communication tools and infrastructure. When you’re going from a proof of concept to a project on a larger scale, things like cross-team communication, shared documentation, testing infrastructure, and tools for automation become essential.
Internationalization for products
In some cases, it may not be possible to internationalize every string in your application. In our case, we had to limit OpenShift internationalization to the hard-coded strings available in our front-end code. It’s important to consider how this limitation will impact your user experience.
As with many open source projects, OpenShift has a lot of contributors.
Centralized communication became very important as the internationalization effort picked up beyond the core user interface team and even expanded outside of the company. We shared getting started information, documentation, and tips and tricks via a shared Google doc, and had a dedicated Slack channel for questions and cross-team communication.
With larger products, you may also have to work around more complex architecture.
OpenShift is a monorepo and separates its code into a main public folder and many packages. Our architects wanted to have our internationalization files for each package, for example, located inside each package. This took some extra code on our end to get the parser to read every file across the application. Test-wise, we had to write a custom Jest resolver for i18next to work with our existing unit test architecture. We also had to start working on integration testing infrastructure for ensuring all strings are internationalized.
Automating workflows became more important as the number of contributors increased.
We added a check for whether i18next JSON files were committed, and scripts for adding more nuanced English defaults, consolidating conflicting i18next JSON files, and importing and exporting translation files used by Red Hat’s globalization team.
Your organization may have a localization or globalization team that you can work with.
At Red Hat, we’re extremely lucky to have a globalization team with translators and dedicated quality engineers. They’ve been a great resource for us and will help us test the product as we integrate translations. We encourage you to reach out to yours!
OpenShift is nearing the end of its internationalization roadmap for this release, and we’ve started working with the globalization team on translating the product.
If you’re considering embarking on your own internationalization journey, we hope this article has helped you set your course. Bon voyage!
Have a story of your own? Write with us! Our community thrives on diverse voices –– let’s hear yours.
