Does i18n Have an Optimal Sequence?

Suppose you begin the long and complex task of internationalizing your software, only to discover a fundamental flaw in your i18n framework. What if your language files aren’t compatible with the translation vendor? What if the chief architect has identified a key software component for replacement? What if your approach isn’t compatible with each of the locales you wish to target? Overlooking the optimal sequence of i18n, or missing critical components altogether, can lead to significant, and costly, mistakes.

I18n Communication, Planning and Architecture

Large companies with multiple development teams operate within a paradox. The development teams operate independently to ensure fast delivery of product enhancements, but that same independence often results in a lack of communication or big picture design of the system itself. The first step in any i18n project is to communicate with the teams and examine both the long and short terms plans of all aspects of the product.

It’s surprisingly common for long term architectural plans to be overlooked in the i18n process. For example, a company may have a solid framework using RequireJS, and the development team moves forward using the integrated RequireJS framework for i18n. But just a few years later, support for the RequireJS framework stagnates, and the architects find themselves in the unfortunate position of needing to upgrade not only their RequireJS component, but their entire i18n framework that uses it. Following the optimal sequence of i18n would have solved this problem.

Do you write documentation? Small, agile teams often do very little in this regard, preferring instead to focus on manageable enhancements that can easily be documented with a short paragraph. But i18n of a large software product is a different beast, and requires detailed planning and documentation. And with that documentation comes a listing of the components that need to be refactored, what changes are needed with each refactor, and the sequence of refactors needed to ensure a seamless implementation in that agile environment.

Looking beyond design, are there specific refactors in an i18n project that should happen before others? The short answer is yes. Once a proper design has been determined, it’s still critical that upgrading of certain components takes place before others. Failure to do so can lead to lost time as developers wait for dependent projects to complete, redundant passes through code as interfaces are upgraded haphazardly, and bugs in the app when code does not interface properly throughout the entire i18n process.

String Externalization and Concatenation

First, let’s talk strings. Supposed Jeff was given the task of externalizing the strings in the app. With the string externalization framework in place, this would simply be a matter of replacing each string with a call to the string framework. On the surface, the task seems pretty easy: if you see a string, externalize it! But Jeff and his superiors didn’t consider the optimal sequence of i18n, and they overlooked a critical prerequisite: concatenations. So, Jeff continued on his merry way, refactoring strings like this:

   var text = “The ” + fieldName + ” field is required.”;

   and turning them into this:

   key.the = “The “;

   key.fieldisrequired = ” field is required.”;

   var text = GetString(key.the) + fieldName + GetString(key.fieldisrequired);

It wasn’t until much later that they discovered sentence structure plays a key role in localization, and concatenations should therefore be refactored to use insertion points prior to the strings being externalized. Using Jeff’s incorrect refactor, the phrase

   “The Name field is required.”

   could not be properly translated into Spanish since the word “field” (campo in Spanish) switches to the left side of the inserted “Name” (Nombre in Spanish):

   “El campo Nombre es obligatorio.”

   Even further, translators have difficulty translating partial sentences. What does “The” refer to? Will it refer to a masculine or feminine noun? A more proper refactor would therefore have been:

   key.thefieldisrequired = “The {0} field is required.”;

   var text = String.Format(key.thefieldisrequired, fieldName);

By using the refactored concatenation, the Spanish translation can adjust for the revised sentence structure:

   key.thefieldisrequired = “El campo {0} es obligatorio.”;

   var text = String.Format(key.thefieldisrequired, fieldName);

I18n and the Database

Next, let’s talk database. Suppose Sally’s project was to refactor addresses in the app, allowing storage of additional address lines and adding a country. On the surface, the project seemed pretty easy. The db administrator had already added a Countries table for reference, plus added 2 additional address columns to the client database. Sally thought everything was good to go.

But after adding the new address fields and running a test, she discovered that Japanese characters weren’t being properly stored in the database. After a great deal of debugging, she discovered the address columns were VARCHAR and couldn’t store Unicode characters! She spent the next few hours putting in a request to the database admin to upgrade the address columns to NVARCHAR, and waited patiently for the database to be upgraded.

But Sally’s next problem quickly arose. The ZipCode column was only 10 characters long, and she realized that international Postal Codes could be significantly longer than that. So again, she put in a request for a database change, and again she waited patiently for the upgrade.

Sally’s problems, however, were not over. As she continued her i18n of addresses, she discovered that some countries have “States” and others have “Provinces”. The Countries table they’d originally created had no knowledge of this distinction, but clearly one needed to be made. So again, Sally put in a request to the db administrator to add a new column to the Countries table, and waited patiently for the upgrade.

One of the greatest inefficiencies in software development is improper planning. By ignoring the optimal sequence of i18n, Sally and the db administrator had to go back and forth multiple times, upgrading the database piecemeal and slowing the i18n process considerably. The proper sequence should have been: Complete Address Design > Complete Database Refactor > Complete Code Refactor.

Synchronizing i18n Processes

Finally, let’s talk synchronization. The I18n Team at Widgets R Us had a number of front-end and back-end modules that needed refactoring, and they began merging their front-end upgrades first. All seemed fine, until customers began reporting program exceptions in various areas throughout the app. A crisis was underway.

As it turned out, the I18n Team had refactored the dates sent to the server to be in ISO format (YYYY-MM-DD). And while they had tested many of the adjaxPostSync calls, there were still a number of untested interfaces where the server was expecting a localized MM/DD/YYYY format, and the app was crashing with the unexpected data.

Improper synchronization in the i18n process can lead to program errors, and unhappy customers. In the case of Widgets R Us, the server interfaces either should have been refactored first to allow the use of both ISO and localized dates, or the client and server modules should have been upgraded together.

Does i18n have an optimal sequence? Every app is unique in its requirements, but the answer is definitely “yes”. Communication amongst all development teams is paramount, extensive planning and design is critical, and the sequence of implementation is vital. Failing to follow the optimal sequence of i18n can lead to time consuming, and costly, mistakes. Don’t let it happen to you.

A Better Approach to Internationalizing and Localizing Software

Adapting software so that it supports multiple languages and locale formats is not trivial and it is important to your global success. A localized User Interface can have a positive impact on your customers’ satisfaction with your product. The globalization requirements span your software architecture and ongoing development practices. It is important to create ongoing processes so that internationalization (i18n) and localization (L10n) can be easily integrated into your sprints and releases.

Why Software Localization is Valuable

Companies that are looking to grow globally find that fully localized software is one of the key elements to sustained growth. You may gain some initial traction without localization, but if you want to move beyond early adopters and be more competitive, the localization process is an essential step. The localized software is easier to use and helps build long-term customer satisfaction. In addition, companies that invest in i18n and L10n often find they are at a competitive advantage in international markets which helps maintain pricing power.

But before you can effectively localize, you must internationalize your software to enable multilingual capabilities. This includes:

  • Adding locale frameworks
  • Externalizing strings
  • Refactoring string concatenations
  • Replacing locale-limiting programmatic functions/methods and patterns
  • Database internationalization
  • Managing potential 3rd party product issues

Getting Started

Internationalizing your existing application may seem daunting but the effort is typically rewarded with increased revenues. There’s a reason many companies underestimate the effort required to internationalize software. Many good programmers don’t have experience with internationalization and are therefore unfamiliar with best practices. They may regard i18n as a simple string externalization exercise – which of course is not the case. To complicate matters, without tools to keep the development teams on track, it is inevitable that i18n technical debt will creep into new features. Below are some tips and suggestions to help make your internationalization and localization efforts efficient, effective, and successful.

1. Dedicated Team

It’s not uncommon for some companies to start internationalization efforts with only one or two developers. Within a few months, they are pulled from i18n and put onto a “higher priority” project and sometime later replaced with different developers. This inconsistent approach almost always fails. After a year or more and significant resources expended, the project is still not complete, and the opportunity cost only continues to rise.

Creating a dedicated project team is the most important step in ensuring your internationalization effort will be successful. Using third-party contractors to lead the effort, combined with some of your own development resources, is one way to make sure the team persists even when internal resources are diverted. This approach has the advantage of allowing multiple internal developers to participate in the i18n process, rapidly improving the learning and socialization of internationalization techniques.

2. Software Architecture

Before diving into externalizing strings, it is important to first look at the software requirements and architecture. Is Unicode required? String externalization in the user interface is obvious, but are strings also passed through and processed in your software back end? How will you support locale selection within your application’s various programming languages? How will locale be selected and is there a fallback? What changes will need to be made within your database? Are there third-party libraries that need to be considered? Like many programming tasks, getting the approach correct up front will save many hours of wasted time doing rework. Are you choosing to use established methods for locale support or creating your own (we don’t suggest the latter)? Using standard resource file types and conventions will make automation of the translation process much easier.

3. Finding i18n Bugs

One of the more challenging aspects of internationalizing existing software is finding all of the i18n issues. Within thousands or even millions of lines of code, these can be difficult to identify and resolve. Fortunately, there are static analysis tools available, like Lingoport’s Globalyzer, to make the task of finding and fixing i18n bugs faster and easier. It is also important to put in place a method to quickly check new source code as it is being written so that internationalization becomes part of the agile process rather than addressed later in backlogs when it will cost much more in time and hassle. When developers can quickly scan their work from their IDE to find i18n issues, they are much more likely to fix the issues as they are writing the software.

4. Automation

The very nature of agile development involves rapid new feature development. For localization, this means many relatively small localization changes, performed more frequently. Traditional approaches to software localization involve many manual steps to perform a localization update. The process of finding and enumerating new strings from resource files in repositories, sending them out for translation, and returning the translations to the repo, can be tedious and error-prone. When changes are made to the source string, sequencing of the returned translations is almost always an issue. In addition, errors in the source files are multiplied across all of the locales during translation so it is important to validate the formatting prior to sending the files for translation. The good news is that this entire process can be automated so that no one needs to take on the role of “file nanny”, shuttling files back and forth to translation. For example, Lingoport’s Resource Manager handles these tasks using continuous integration along with an automated connection to your localization company or translation management system.

5. Selecting a Translation Partner

Language Service Providers (LSPs), also known as translation agencies, provide professional translation services including software and app localization.

Selecting a translation agency that has experience in and an understanding of software and app localization is key for ensuring your localized product is well received in new language markets.

Here are some things to look out for when evaluating translation agencies:

  1. Will the localization process be synced with your development process and does it fit seamlessly into your existing workflow?
  2. Do they offer integrated technology solutions to provide continuous translation and streamlining string hand-offs?
  3. Are they providing a veteran team of in-country linguists and industry tools to deliver quality translations that meet your deadlines and budget?
  4. Are they a full-service agency that can be called upon throughout the enterprise with professional translation services that include website, documentation, video and marketing content translation?
  5. Do they provide an optional Quality Assurance (QA) step that includes efficient, in-context validation of language and formatting to ensure your product looks and functions as intended?

When selecting an LSP, you are outsourcing a set of specialized and time-sensitive tasks that are closely coupled to your creative and development process. Quality should be a priority at each step in the process, from project set up through quality assurance. Working with a localization partner who can navigate both cultural and technological challenges will not only take your product across borders but also help it succeed across language markets.

The unique challenges of software demand dedicated effort to internationalization and localization. The proper tools and partnerships are required to meet your agile development workflow. Lingoport and Acclaro provide the expertise and solutions to help you meet your worldwide market goals.



Acclaro is a strategic partner of Lingoport.