15 November 2016

Do It Yourself Localization

When developing an application you often reach a point when you want to make it a great fit for the world audience. This includes translation to their native language. Usually you have to solve two different aspects of localization for your app:
  • Using localization in your app. This is actually pretty simple and there are ton of ways to do it and many different frameworks and libraries that make it very simple for you. Also effort to use localization is often very close to using unlocalized hardcoded texts and the effort does not grow with number of languages.
  • Getting localization to your app. In another words how to make sure you have a translation of every piece of text in your app ready for a release. Although sounds simple there may be a lot of manual work and a lot of people involved. With each change in the text used in the application you have to ensure all translators deliver the translations back to the application. This effort grows with the amount of text you need to localize and number of languages you support.
In this blog post I will focus only on the second one. I have experienced translation processes that were complex and error-prone beyond my belief. If you are a big enterprise than you can probably continuously spend some money to making complex process work reasonably well. We were looking for the simplest process with minimum overhead - manual work and cost.


Everybody may have different view on what is important for their translation process. Lets see what was our focus. We wanted to achieve a few things:
  • Have localization on a single place and have it always current
  • Enable anybody to contribute to localization without any developer or other specialized tools
  • Enable community to contribute without breaking the app
  • Do not require any of the contributors to get involved in any technical stuff
  • Zero-cost for contributors and minimal costs for us
  • Minimize amount of emailing and other communication around localization
  • Enable to comment and discuss the translations in a way that is tracked and others can learn from it
  • Enable translators to easily export and import data if they would be inefficient in Google Sheets
  • Totally automated inclusion of translations into Icon Cast
  • Automatically check translations for most common issues
As always we didn't have to do everything at once. We just had to know that we make steps in the right direction for us. Icon Cast was ready for localization from the version 1.0. In version 1.4 we have started to use a new localization workflow although it contained some manual steps. With version 1.8 we will use the localization workflow with two languages and fully automated. So it took some time.

Translation Software? Or Not?

There are tons of translation software and services you can choose. These products provide good features - usually for translators. They remember past translations and automatically offer you the same translation when the original is the same. They do automatic machine translation prior to doing the translation by a human. They have marketplaces for translators where you can offer jobs and get back offers from translators willing to take the job. And that is far from all.

While going through the different tools we have realized we are not actually searching for a translation software. Rather for a tool that would enable us to smoothly manage the translations we do ourselves and we would eventually receive from the community. So it does not have to be that translator-friendly but has to fit well into our release workflow.

This lead us to simply use Google Sheets. I'm not sure how rare this choice is. Based on some googling it seems that we are at least not a single case. There are some projects that work with Google Sheets such as localize-with-spreadsheet or Easy Localization.

There are some features we have not really tried to address when choosing a way how to do translations:
  • Having a translator-centric tool
  • Checking amount of work done by translators which then translates to payment
  • Complex enforced workflows of translation and approval process
We have focused on a tool that would enable us to rapidly update localization and include it in the application. So the tool is our workflow-centric not translator-centric. This means the translator is forced to use Google Sheets directly or has to export-import data to make translation in their own tool.

Calculating the amount of work done can be done but it will require some work either in the spreadsheet or in the code you would use to download localization. It is certainly nothing you would get out of the box. The same for more complex translation workflows. It may be much harder to enforce in spreadsheets.

Google Sheets Perks

We have picked Google Sheets for having a centralized translation of Icon Cast. Primarily because we already use Google Sheets so it ads no extra cost. It is super easy to let anybody comment and contribute. Many people know how to use spreadsheet applications on a basic level.

All our text is translated in a single table. Each row represents one piece of text and each column represents a single language. It is a simple matrix with keywords, comments and the original English translation in the first columns.

Some basic highlighting at least for missing translations

With using Google Sheets you will get certain features for free. We found some of them useful for localization. So we will give you a couple of hints. I will not elaborate on tracking changes and ability to comment every cell. These might be pretty useful as well. I will focus on less known features that might save you some work in your translation workflow.


You can use formulas in translations to insert dynamic content. It is great to reuse commonly used values and texts. One disadvantage is that translators are not very familiar with writing spreadsheet formulas and usually will just put static text there. So usually only the original localization is the one that really contains formulas unless you invest some additional time.

Formula for adding a dynamic value to text

Named Ranges

You can name individual cells or entire ranges to reuse them easily without having to reference them with their sheet coordinates. This means it is easy to move the data without breaking anything that depends on them. Also usage is a bit simpler as you type the name only as you can see in the image in Formulas section.

Go to Data → Name ranges... to play with the named ranges.

Named ranges make it easy to reference important reused values

Protected Sheets and Ranges

Protected Sheets and Ranges may be useful when you want to enable only certain people to edit specific cells. In our case we are the only ones who can edit the columns where are the keys for individual localized texts, comments to them and the English originals. We then plan to enable each translator to edit only columns for the language they translate into. This ensures people do not accidentally break things.

To protect cells from modification go to Data → Protected sheets and ranges...  Then just follow the instructions. It is pretty straightforward. You can pick individual people who can edit chosen sheets or data ranges.

Translate Add-on

Some people may prefer to start with a machine translation before an actual person does it right. Automatic translation might be useful when you want to test your application for right-to-left scripts such as Hebrew or Arabic. Eventually try to test it with scripts that have generally different look and proportions than latin characters such as Chinese. You might need to do some corrections after the translation is done if you use variables or other placeholders in the texts though.

Go to Add-ons  Get add-ons... and search for "translate" to find the auto translation add-on. Then enable the add-on for this sheet. We also had to close and reopen the sheet for options for translation to appear in the Add-ons menu.

The automatically translated cells are highlighted by the add-on
The add-on is available here.

Even with no add-on there is a function in Google Sheets to use Google Translate to help you fill the cells initially. Just use "=GOOGLETRANSLATE(<cell>, <source language>, <target language>)" formula.

You can use this as any other formula

Details and Context

You can use links in spreadsheets or show images from an web address. Links might be great to reference for example a large screenshot where the text is used or a link to the documentation that provides more information about the functionality related to the text.

In the future we plan to show icons that are related to the translated keywords so translators are sure what the keywords refer to.


Thanks to formulas you can do some checks for translations. For example you can check that the translated text is not empty, that the text length is within required bounds, etc. At the end we decided against this as we can do more complex checks much easier in our Java builder. 

If you have some spreadsheet wizards in your team the Google Sheet may be an ideal place to make at least some of these checks as they provide immediate feedback to translators. This is something tests during build time cannot do at the moment.

Start Simply

Ideally the process of including translations in your app is absolutely automatic. This means that during build you download the spreadsheet values and directly embed it into your application without a developer having to do anything. This requires some development work on your side though. And you might not have time to do this.

When we started with translations in Google Sheets in Icon Cast 1.4 we had not such automation. Mainly because we were struggling with authentication with Google for some reason. We had only English at that time. So you had to do two copy-and-pastes from Google Sheets to Java properties files before release. However having the localization central, shared and easy to contribute for everyone pays of.

To make copy paste simple we have added another sheet with formulas that basically produce localization in Java properties format. You can use the same approach to generate different data formats if properties do not work for you.

Formula for composing Java properties
You can download starter spreadsheet that is intended for generating Java properties. Let us know if you have an idea how to improve it so other people may benefit.


Ideally at some point you will avoid manual copy pasting and make download of localization from Google Sheets a part of your build process. The best place to start with using Google Sheets APIs in Java is Google Sheets Quickstart. Just make sure you follow the instructions because we did not initially and that gave us some headache with authorization.

Depending on your builder (we use a custom Java bases builder) the integration may differ. If the integration with a builder such as Maven is an issue you can just create a small utility that will download the data and create creates the property files before the build process.


There are numerous ways how to localize your application. We have tried to make it the way it suited us. We wanted the localization to be on one place where people without GIT or any other developer tools can access it. We also wanted to have inclusion of localization files to be fully automated. Google Sheets are great for collaborative work on the localization and we had to implement a bit of Java code that downloads the translations and saves them as property files to the application during our build process.

You can start very simply without coding with our sample spreadsheet that produces Java property files for you. So you can only copy-and-paste them to your application. We used this in Icon Cast 1.4 to 1.7 before implementing the full automation.

How do you do localizations? As always we welcome any hints. Also if there is anyone who would like to help us making Icon Cast international let us know at contact@pureprototype.com and you can try our localization workflow yourself :)

No comments:

Post a Comment